Local, state and national government agencies receive thousands of citizen enquiries every week, covering rates, permits, waste collection, parking, and more. ToothFairyAI lets you build a retriever agent that answers these questions instantly and accurately, using your own policy documents as the source of truth.
This guide walks through every tool and step you need, from creating the agent and organising your content to deploying a widget on your council website. By the end, you'll have a working citizen services agent that routes questions to the right knowledge and hands complex cases off to staff when needed.
Overview
A retriever agent is purpose-built for knowledge-backed Q&A. Instead of generating answers from general knowledge, it searches your uploaded documents first, then composes an answer grounded in what it found. That makes it the right starting point for citizen services, where accuracy and traceability matter.
What you need
- A ToothFairyAI workspace with API key and workspace ID
- Council service documents (PDFs, web pages, or text files)
- Admin access to your council website for widget embedding
Step 1: Create a Retriever Agent
Use the ToothFairyAI agent creation tool to create a new agent. Set the mode to "retriever" because this is the ideal mode for knowledge-backed Q&A; it searches your documents before generating a response. Enable agentic_rag so the agent can perform multi-step retrieval across several documents when a question is complex.
Set a clear label such as "Citizen Services Agent" and write goals that instruct the agent to answer only from uploaded documents and to direct citizens to the relevant department when it cannot find an answer. These guardrails keep responses grounded and set a clear fallback for edge cases.
Step 2: Organise Your Knowledge Hub
Before uploading documents, create folders in the Knowledge Hub to keep content organised. Use the folder creation tool to set up folders like "Rates & Payments", "Permits & Licensing", and "Waste & Recycling". Structure here pays off later when the agent routes queries and when administrators need to update a single service area.
Then upload your council PDFs and web pages into the appropriate folders using the document creation tool. Set doc_type to "readComprehensionPdf" for PDFs or "readComprehensionUrl" for web pages. Assign topic entities, such as "Rates" or "Permits", to each document so the agent can route queries to the right knowledge area.
Step 3: Create Topic Entities
Use the entity creation tool to create topic entities that match your service categories, for example "Rates", "Permits", "Waste Collection", "Parking". These topics are attached to documents and help the agent understand which knowledge area a question belongs to.
You can also create intent entities such as "pay_rates" or "apply_permit" so the agent recognises what the citizen wants to do, not just what they are asking about. Distinguishing intent from topic lets the agent take a more useful action instead of only returning information.
Step 4: Connect to External Services (Optional)
If you want the agent to take actions, such as redirecting a citizen to a payment portal or checking application status, use the function creation tool to connect to your existing APIs. Create a function with the appropriate URL, request type, and parameters.
Store API credentials securely using the authorisation and secrets tools. The agent will then call these functions during conversation when a citizen needs to complete a transaction, closing the gap between answering a question and helping the citizen get something done.
Step 5: Deploy to Your Website
Go to settings and scroll down to appearance and web widget. In this section you can configure your agent using a logo, welcome message, colour scheme and more. Taking a few minutes to match the widget to your council's branding helps citizens trust the experience.
To deploy the widget, go to "apply this agent to your website" and copy the code, or you can simply click on the blue link that says "Go to widget". Paste the snippet into your council site and the agent is live.
Outcome
Citizens get instant, accurate answers sourced directly from council policy documents. Call centre volume drops significantly. Staff are freed to handle complex cases that require human judgement. Every response is traceable to a source document, ensuring accountability and compliance.
Hypothetical example: Maplewood City Council
Maplewood City Council receives over 3,000 phone and email enquiries per week about bin collection schedules, rate payments, and building permits. Using ToothFairyAI, the council creates a retriever agent, uploads 45 policy PDFs into organised Knowledge Hub folders, and tags them with 12 topic entities.
They deploy the widget on the council homepage. Within the first month, 60% of citizen questions are answered by the agent without human involvement, average response time drops from 18 hours to under 10 seconds, and call centre staff report having more time for complex cases. The council also connects a function to the rates payment API, allowing citizens to be directed straight to the payment portal when they ask "How do I pay my rates?"
Where do I find my API key?
Simply log in, select your workspace and go to admin. Once in admin you will need to click on TfCode and API integration where you will find your API key and Workspace ID. From there you can authenticate any external integration or function you build.
