Step 7: Getting started with Plain AI — setting up the Customer Agent and Sidekick
Where Plain really shines is its ability to deploy AI in a smart, flexible way that supercharges how your team does support — this is the step where you learn how to set up your AI agents (either your own or the ones we've built) to make your team seem much larger than it is.
Plain has two built-in agents: the Customer Agent (which replies to customers based on the knowledge it has access to) and the Sidekick Agent (which works internally for your team inside threads and Slack). Moreover, because Plain is an infra-first platform, you can choose to bring your own agents for both external (customer-facing) and internal (team-facing) work and still enjoy the same native feeling as our in-house agents.
This guide will walk you through pointing the Customer Agent at a knowledge source, assigning it in test mode from a workflow so your team can review its drafts privately before it sends a public-facing reply, running your first Sidekick investigation, and where to plug in your own agents if you've built them.
What good looks like
What we define as "good" for this step is seeing both agents do real work in your workspace:
At least one knowledge source is connected and being read by (we call this indexing) the Customer Agent
You've run a few real customer questions through the Customer Agent playground (Customer Agent → Playground) to verify it finds your docs and hands off cleanly to a human instead of guessing
A workflow assigns the Customer Agent to threads in Test mode and you can see the draft replies it would have sent in the thread timeline (with the docs it cited, when knowledge citations are enabled for your workspace)
You have used the Sidekick Agent on a real thread at least once to see how it pulls context and takes action based on your prompt (in this case, drafting a reply you approve into the composer)
What to consider
Using Plain's built-in agents vs. bringing your own (or both). For the purpose of this exercise (and because it's simpler to set up) you'll be setting up Plain's built-in agents, but, because Plain is infrastructure, you're not forced into using them — you can bring your own agent for both external (customer-facing, like the Customer Agent) and internal (team-facing, like Sidekick) roles. When you register a service as an Agent under Settings → Machine users & Agents, it becomes a first-class citizen in Plain:
External (customer-facing) custom agents can be assigned to threads from a workflow or by a teammate, show a live status indicator on the thread, and reply across Slack, MS Teams, email, and chat (or drop a draft into the composer for a human to review) without you writing a single line of channel integration code.
Internal (team-facing) custom agents can participate in private agent discussions on the thread timeline (triggered by a workflow or
@mentioned by a teammate), investigate against your internal systems, and pause to request inline human approval from a teammate before executing a sensitive tool call.
Do you have documentation to point it at? The Customer Agent only answers from the knowledge sources you give it — without indexed docs, it will simply hand off every thread. It reads any customer-facing Plain Help Center automatically, and can index an external docs site via sitemap or URL.
How to implement
The Customer Agent only works on threads that a workflow (or a teammate) assigns to it — furthermore, as part of that assignment workflow action, you can select whether the Customer Agent responds in Test mode, or in Live mode.
Step 1: Add and index a knowledge source
If you're using a Plain Help Center (Step 8), published articles on a customer-facing Help Center are indexed automatically. If you don't have a docs site yet, skip the source for now and still run the Playground below. With nothing indexed, the agent hands off, which is what that last Playground check is looking for. You can index the Help Center from Step 8 once it exists. To add an external docs site or changelog as well:
Open Knowledge in the left-hand sidebar; it lands on the Knowledge sources page
Scroll to the Sitemaps card and paste the address (e.g.
https://yourdomain.com/sitemap.xml) into the Sitemap URL field; single pages go in the Individual URLs card below itClick Add sitemap (or Add URL) — Plain reads the sitemap and indexes its pages automatically
The new row shows a spinner while Plain reads the sitemap; reload the page to see it turn into a green check once the sitemap has been read — once the sitemap has been read, Plain then indexes each page it finds. Then check the Health card and the Failed ingestions list at the top of the page for pages that failed to index.
Step 2: Take the Customer Agent for a spin in the Playground
Before wiring the Customer Agent into a workflow, you can chat with it directly in the Playground to see how it responds using your live knowledge sources, custom instructions, and tone of voice rules — without creating a real thread.
Open Agents in the left-hand sidebar, select Customer Agent, then open the Playground tab
Paste a real question a customer has asked recently that your docs cover, and press Send
Inspect the step-by-step trace above the reply: expand Searched knowledge sources to see the exact queries it ran and the documents it pulled, expand Used knowledge sources to see which pages it cited, and read the Judges line — Judges passed the draft means its internal quality check approved the reply, while Judges rejected the draft expands to show which judge objected and why
Click Reset and ask a question your docs don't cover (or ask to speak to a human) to confirm the trace shows Recorded knowledge gap and Unassigned itself from thread and ends on Handed off rather than guessing
Step 3: Assign the Customer Agent in Test mode from a workflow
In test mode, the Customer Agent joins the thread as an additional assignee so your normal team assignment and queues don't change. On each customer message, it posts a private timeline entry titled [agent name] would have replied or would have handed off to a teammate (with the reason for handoff).
Open your routing workflow from Step 6 (or create a new workflow triggered on Thread created)
Add an If/Else condition scoping where you want to test first (for example, a non-Enterprise tier, or a single channel)
On the If branch, add an Assign to action step, open its assignee picker, hover Agent, and under Customer Agent select your agent's display name with (Test Mode)
Click Publish workflow
After a few days of traffic, review the drafts under Customer Agent → Activity. When you're happy with the quality on that scope, edit that workflow step, switch the assignee from the (Test Mode) option to the plain agent name (live), or click Switch to live mode in the step panel, and click Save changes.
When the Customer Agent is in (Live) mode and hands a thread off (because the customer asked for a human, raised billing/security/an incident, or hit a gap in your docs), it sends a short handoff message and unassigns itself.
Step 4: Run one Sidekick investigation per teammate
Unlike the Customer Agent, Sidekick never messages customers — it reads the thread timeline, attachments, the customer's past threads, and your connected tools, and helps your team investigate or draft from inside Plain (or from Slack Discussion channels).
Open any real thread with a bit of history in Plain
Press
B(or click Ask Sidekick Agent at the bottom of the screen — the button reads just Sidekick Agent when the thread column is narrow; if the thread has a task on it, you can also click Handle with Agent on the task)Ask a concrete question — e.g. "Summarize this customer's recent threads and draft a reply based on our docs" — and review the response in the Sidekick panel that opens on the right
If the answer includes a draft reply, click Approve draft under it — the draft lands in the thread's reply composer, where you can edit it before sending; nothing goes to the customer until you click Reply
Have each person on the team do this once during setup so everyone knows where it lives before the queue gets busy.
Optional: Bring your own agent (external or internal)
If you've already built your own AI agent, or want to build one connected to your own database or internal tools, you can plug it into Plain so it works alongside your team just like the built-in Customer Agent or Sidekick.
How it works
Plain doesn't host your custom agent's code — your agent runs on your own infrastructure (even a simple, single-file serverless function on Vercel, Cloudflare Workers, or AWS Lambda is enough). Whenever your agent is assigned a thread or asked a question in Plain, Plain sends a webhook to your URL. Your agent does its thinking, then makes a few GraphQL API calls back to Plain to update its status and post its reply.
Tip: Let an LLM write the glue code. You don't need to build the webhook listener and API calls by hand. Point Cursor or Claude Code at Plain's agent-friendly docs (https://www.plain.com/docs/getting-started.md and the Bring your own agent guide) and ask it to generate a small TypeScript or Python server for your agent. You can test it locally on your laptop using ngrok or a Cloudflare Tunnel before deploying.
Why reporting "agent status" matters
Because a custom agent runs outside of Plain, Plain only knows what your agent is doing if your agent tells it what it's doing. Updating your agent's status via the API is what makes an external agent feel truly native to both your customers and your teammates:
What customers see: When a customer-facing agent marks a thread as
IN_PROGRESS, customers in Plain Chat immediately see a live working/typing indicator with your agent's public name and avatar — this way they know an answer is on the way.What your team sees on threads: While a thread's agent status is
IN_PROGRESSorHANDLED, Plain automatically keeps it in the Handled by Customer Agent view and out of your human Needs first response / Needs next response queues — this prevents teammates from accidentally jumping in and replying while the agent is working on investigating and sending a response. When the agent sets its status toHANDED_OFF, the thread drops back into your human queues.What your team sees in internal discussions: When an internal agent sets its discussion status to
IN_PROGRESS, teammates see a live "thinking" indicator in the discussion panel (and a Stop button if they want to cancel the turn). When it flips back toIDLE, they know the answer is ready.
Setting up BYOA + BYOS
Register the agent in Plain
Go to Settings → Machine users & Agents → Add machine user
Choose Agent as the Type (rather than API integration), set the name and avatar you want teammates and customers to see, and copy the API key
Go to Settings → Webhooks and add your agent's URL so Plain can notify it when there's work to do
The core API calls for an external, customer-facing agent (BYOA)
When you assign a thread to your agent (via the Assign to user workflow step or manually):
How Plain wakes your agent up (Webhooks): Subscribe to
thread.thread_assignment_transitioned(when the thread is first assigned to your agent) and the inbound message events (thread.email_received,thread.slack_message_received,thread.ms_teams_message_received,thread.chat_received) for customer follow-ups.What your agent calls back (GraphQL):
Read the conversation (
thread): Fetches the messages, customer details, and account fields so your agent has context.Show it's working (
updateThreadAgentStatus): Set toIN_PROGRESSas soon as your agent starts thinking (shows the typing indicator to the customer and hides the thread from human queues), thenHANDLEDonce answered, orHANDED_OFFif a human needs to step in.Answer or draft (
replyToThreadoraddGeneratedReply):replyToThreadsends the reply straight to the customer on Slack, MS Teams, email, or chat;addGeneratedReplydrops a draft into the composer so a human can review it first.Hand off cleanly (
createNote+unassignThread): Leave a quick internal note explaining why the agent is escalating, then unassign the agent so your normal routing workflow hands the thread to a human team.
The core API calls for an internal, team-facing agent (BYOS)
When a workflow (via Start agent discussion) or a teammate starts a private thread discussion with your agent:
How Plain wakes your agent up (Webhooks): Subscribe to
discussion.discussion_createdanddiscussion.message_created(when a teammate asks a question), plusdiscussion.tool_call_approval_resolvedanddiscussion.question_resolved(if your agent asks for human sign-off).What your agent calls back (GraphQL):
Show it's thinking (
updateDiscussionAgentStatus): Set toIN_PROGRESSwhile the agent is working andIDLEwhen it finishes its turn.Show its work (
upsertDiscussionToolCall): Optionally log the steps or lookups your agent is running so teammates can see an expandable trace of what it checked.Ask a human before acting (
requestDiscussionToolCallApprovalorrequestDiscussionQuestion): Pauses the agent and displays an interactive Approve / Deny button (or a multiple-choice question card) in the discussion before your agent runs an important action.Post the answer (
sendDiscussionMessage+changeThreadDiscussionStatus): Sends the agent's findings back into the private discussion and marks itRESOLVEDwhen done.
See Bring your own agent for copy-pasteable payload examples.
Some gotchas to be aware of:
Sitemap validation is strict: Plain rejects URLs that don't return a valid sitemap (like a docs homepage or
robots.txt), skips.pdffiles, and marks pages under 100 characters of body text or over 1 MB as Failed.Pages behind a login can't be crawled unless authenticated access is configured. A private or internal Plain Help Center can still power answers, but the Customer Agent only includes clickable citation links to publicly accessible pages.
Whenever the Customer Agent can't answer a question from your sources (in either Live or Test mode), Plain records a knowledge gap and raises a task for your team — check Customer Agent → Knowledge weekly for a ready-made list of docs to write next.
Customers never see the internal name "Customer Agent" — they see the display name configured under Customer Agent → Preferences (which defaults to
<Workspace Name> Support) with an AI agent badge.
How to verify if this step is working/complete
Confirm your sitemap shows a green check on the Knowledge page and the Health card reports no failed pages.
Send a test message from a personal account that matches your workflow condition, asking a question your docs clearly answer. Open the thread and confirm a private Customer Agent timeline entry appears with a draft reply and citations, and that no message was sent to the customer.
Send a second test asking something your docs don't cover, and confirm the private entry states why it would have handed off.
Open Ask Sidekick Agent (
B) on the thread and run one prompt to confirm it returns an answer.
Troubleshooting/FAQ
No Customer Agent draft appeared on my test thread.
The Customer Agent only runs on threads that a published workflow assigns to it, and Plain skips messages sent from your own workspace domain. Here are the two reasons a test thread gets no draft:
The workflow is still a draft, or the thread didn't match your condition
Saving a workflow doesn't publish it, and a thread that misses the
If/Elsebranch is never assigned to the agent.Try this: Open the workflow from Step 3, confirm it shows Published, and check its run log to see whether the condition matched.
You sent the test from your work address
Plain treats anyone on your workspace domain (or any Plain user) as internal, so their messages don't trigger a Customer Agent turn.
Try this: Send a fresh test from a personal email address that matches your workflow condition.
The draft says it would hand off on a question our docs definitely answer.
The Customer Agent only answers from pages whose status is Indexed — it can't read pages that are still indexing, failed validation, or weren't in your sitemap. Plain skips .pdf files and marks pages under 100 characters of body text (after stripping nav and footers) or over 1 MB as Failed.
Try this: Open Knowledge in the sidebar, confirm the sitemap shows a green check, and check the Health card and the Failed ingestions list at the top of the page. Once the page is indexed, re-run the question in Customer Agent → Playground and expand Searched knowledge sources to verify it pulls the page.
A customer received a live reply when we meant to be in test mode.
Test mode and Live mode are chosen per Assign to user workflow step, not globally across the workspace, so even if you edited one workflow to (Test), another workflow may still be assigning the agent as (Live).
Try this: Check the status card on the Customer Agent overview page to see how many workflows currently assign the agent in Live vs Test mode, then open the workflow that ran on that thread and switch its Assign to user step from (Live) to (Test).
Where do I see all threads the Customer Agent has touched?
Once the Customer Agent replies in Live mode, it sets the thread status to Waiting for customer, which hides the thread from default Todo-only views.
Try this: Check Customer Agent → Activity for a full log of drafts, replies, and handoffs, or open the Handled by Customer Agent view in your sidebar and toggle on Show all statuses.