Skip to content
⌘K
InboxAsk a human

Step 7: Implementing AI and agentic workflows

Updated by Dustin

Where Plain really shines is its ability to deploy AI in a smart, safe, flexible way that supercharges how your team does support.

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, Slack, and automated workflow actions). 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 — including live status indicators and inline human tool-call approval.

This guide will walk you through scoping knowledge by product, staging rollouts from Test Mode to Live per workflow branch, wiring an automated Customer Agent → Sidekick → human handoff, and governing credit consumption.

What good looks like

What we define as "good" for this step is a staged, observable AI deployment where you control which cohorts get live replies, what sources the agent can read on each product, how escalations are pre-investigated for T1/T2, and what your monthly credit burn looks like:

  • Label-scoped knowledge & hard escalation rules: Knowledge sources are indexed and scoped by product label (Product > Compute vs. Product > Data) so answers never cross-contaminate, and Custom instructions (up to 20,000 characters) enforce hard handoff triggers (billing disputes, security disclosures, enterprise outages, cancellation requests)

  • Per-branch Test Mode vs. Live rollout: Your workflows assign the Customer Agent in Live mode only on validated cohorts (e.g. self-serve chat or Pro email), while running Test Mode (private timeline drafts) on new cohorts and skipping high-touch Enterprise Slack Connect channels entirely

  • Automated Customer Agent → Sidekick → Human handoff: When the Customer Agent steps back from a live thread (Customer Agent unassigned), a dedicated handoff workflow runs a Sidekick Agent action to start an investigation discussion before routing the thread to a human queue

  • Native custom agents (BYOA / BYOS): Any in-house external or internal agents are registered under Settings → Machine users & Agents, report live agent status, and pause for inline human approval (Approve / Deny) before executing state-changing tool calls

Four governance pillars at scale

1. Rollout granularity: Test Mode vs. Live lives on each workflow step, not globally

Enabling Plain AI does not make the Customer Agent reply on its own. It only acts on threads that a workflow (or teammate) explicitly assigns to it via the Assign to action. And, on every Assign to step where you pick your Customer Agent, you choose whether it works live or in test mode (a test step shows Test Mode next to the agent's name):

  • Test Mode: The Customer Agent joins the thread as an additional assignee alongside your normal team rotation and posts a private timeline entry showing the exact draft it would have sent, the knowledge sources it cited, and whether its internal judges passed or handed off. Customers see nothing, and your human SLA clocks and queues are unaffected.

  • Live mode: The Customer Agent becomes the primary assignee, replies to the customer, and moves the thread to Waiting for customer (keeping it in the Handled by Customer Agent view and out of your human Todo queues unless it hands off).

Because that choice is per workflow branch, you can run Live on Pro chat, for example, and Test Mode on Enterprise emails all inside one workflow.

2. Knowledge isolation: label-scoped sources vs. custom instructions

When you support multiple products, brands, or deployment models (Cloud vs. Self-Hosted), separate what the agent knows from how it behaves:

  • Label-scope your knowledge sources: Under Customer Agent → Knowledge → Knowledge sources, attach product labels (Product > Compute, Product > Data) to each sitemap or URL source. As long as your Layer 3 categorization workflow applies the product label before Layer 5 assigns the Customer Agent, the agent will only retrieve from sources matching that thread's labels (plus any unscoped global sources).

  • Use Internal Help Centers for T1/T2 runbooks: If you maintain an internal-only Plain Help Center (Access set to Your team with Plain AI set to Allow), both Sidekick and the Customer Agent can use those runbooks to reason and answer, while the Customer Agent will only include clickable citation links to publicly accessible URLs.

  • Put policy and escalation boundaries in Custom instructions: Use the 20,000-character custom instructions block under Customer Agent → Preferences for behavioral rules: tone, tier-specific caveats, and topics where the agent must hand off immediately without attempting an answer. The agent follows these rules without quoting them back to customers.

3. The Customer Agent does not call Sidekick directly — bridge them with a handoff workflow

In Plain's architecture, the Customer Agent and Sidekick have strictly separated jobs:

  • The Customer Agent talks to customers using approved documentation (and can ask one grounded clarifying question before handing off).

  • Sidekick never messages customers — it reads thread history, attachments, past tickets, and connected internal tools to write internal notes or draft replies for engineers.

When the Customer Agent is Live and hands a thread off (because the customer asked for a human, hit a knowledge gap, or matched an escalation instruction), it sets the thread's agent status to HANDED_OFF, re-arms the SLA clock, and unassigns itself. That fires the Customer Agent unassigned workflow trigger — which is where you trigger a Sidekick Agent action to summarize the conversation and pre-investigate before assigning a human team.

4. Credit economics and budget guardrails

At scale, predictable AI spend comes down to knowing what is outcome-billed vs. usage-billed:

Capability

Credit cost (pricing details)

Billing trigger & how to govern it

Customer Agent in Test Mode & Playground

0 credits (Free)

Run unlimited volume in (Test) mode and in Customer Agent → Playground to validate accuracy before spending a cent

Customer Agent in Live mode

100 credits ($1.00) per verified resolution

Charged only when the agent replies at least once, resolves the thread without a human taking over, and the thread stays Done (not reopened) for 7 days. Handoffs and unanswered threads cost 0 credits

Sidekick (interactive & workflow actions)

Usage-based credits

Billed per run based on context/tool complexity. Governance rule: Never fire a Sidekick action workflow step on every inbound ticket — gate it behind conditions (Customer Agent unassigned, Tier equals Enterprise, or Label IS bug)

Connected custom agents (BYOA / BYOS)

15 credits

Charged per thread assignment (external agent) or internal discussion turn

Fail-safe behavior: If your workspace ever exhausts its monthly included credits and any non-expiring top-up packs, the Customer Agent doesn't drop tickets — it automatically hands incoming threads back to your human queues with an internal note.

Implementation blueprint

If you haven't set up the Customer Agent and Sidekick yet, Step 7: Getting started with Plain AI — setting up the Customer Agent and Sidekick in our small-team series covers the first-time setup.

1. Index label-scoped sources and pressure-test in the Playground

  1. Under Customer Agent → Knowledge → Knowledge sources, add your external sitemaps/URLs (Help Centers with Plain AI set to Allow on their Access page are used automatically). Wait for status to flip to Indexed and verify the health bar shows 0 unexpected Failed pages (Plain rejects non-XML sitemaps, and marks .pdf files, pages under 100 chars of body text, and pages over 4 MB as Failed).

  2. Make sure each product-specific source carries its product label (Product > Compute), chosen when you add the source (a source's labels can't be edited, so delete and re-add it to change them), and paste your escalation and tone rules into Customer Agent → Preferences.

    Limit a knowledge source to one product
  3. Open Customer Agent → Playground and test real questions across products. Expand Searched knowledge sources and Used knowledge sources to verify retrieval, check the Judges step (passed the draft or rejected the draft), and confirm out-of-scope questions end with the outcome Handed off.

2. Wire the Customer Agent → Sidekick → Human handoff workflow

Before flipping any cohort to Live, build the safety net that catches every handoff:

  1. Create a workflow named 5b AI · Customer Agent unassigned · Sidekick summary + T1 routing

  2. Set the Trigger to Automatic → Customer Agent unassigned

  3. Add an If/Else condition to gate when Sidekick runs an automated pre-investigation (e.g. Tier equals Enterprise OR Label IS bug), and on the Yes branch add a Sidekick Agent action step with a tight prompt:

Summarize what the customer is trying to accomplish, what the Customer Agent already checked or asked, and the first thing an engineer should look at next.
  1. Following the Sidekick step (and on the No branch), add an Apply labels or Assign to team step (Compute — EMEA or T1 Triage) so the unassigned thread enters your human auto-assignment rotation immediately.

  2. Click Publish.

Build the handoff workflow

3. Plug in your own custom agents (BYOA & BYOS)

If your team already runs a tuned in-house agent, you don't have to abandon it — register it under Settings → Machine users & Agents → Add machine user and for Type, choose Agent, not API User and point a webhook (Settings → Webhooks) at your service.

Register your own agent

Plain handles the multi-channel delivery (Slack Connect, MS Teams, email, chat), typing indicators, queue filtering, and human approval UI; your service just listens to webhooks and calls Plain's GraphQL API back. (Hand Cursor or Claude Code our Bring your own agent guide and https://www.plain.com/docs/getting-started.md to scaffold the handler.)

Role

Webhooks your service subscribes to

GraphQL mutations your service calls back

External, customer-facing agent (BYOA) (assigned via workflow or sidebar)

thread.thread_assignment_transitioned • inbound message events (thread.email_received, thread.slack_message_received, thread.ms_teams_message_received, thread.chat_received)

See the calls below.

Internal, team-facing agent (BYOS) (invoked via Start agent discussion workflow step or @mention)

discussion.discussion_created, discussion.message_created, discussion.tool_call_approval_resolved, discussion.question_resolved

See the calls below.

External, customer-facing agent (BYOA)

  1. updateThreadAgentStatus → set IN_PROGRESS immediately (shows typing indicator in Chat and keeps the thread in Handled by Customer Agent and out of human Todo queues so agents don't collide)

  2. replyToThread (send live) or addGeneratedReply (drop a reviewable draft into the composer)

  3. Set status to HANDLED when answered, or call createNote • unassignThread • HANDED_OFF to escalate to a human team

Internal, team-facing agent (BYOS)

  1. updateDiscussionAgentStatus → IN_PROGRESS (renders live thinking state + Stop button) and IDLE when done

  2. upsertDiscussionToolCall → stream expandable lookup/trace steps to the UI

  3. requestDiscussionToolCallApproval / requestDiscussionQuestion → pause execution and render an inline Approve / Deny card in the discussion before running any state-changing tool call (refunds, cluster restarts, key rotations)

  4. sendDiscussionMessage • changeThreadDiscussionStatus (RESOLVED)

Verification checklist

  1. Label-scoped retrieval check: In Customer Agent → Playground (and on a Test Mode workflow branch), verify a Product > Compute question only pulls from Compute and global knowledge sources.

  2. End-to-end live handoff check: On a test cohort set to Live, send an out-of-scope question (or ask for a human) from a personal address. Confirm the Customer Agent unassigns itself, re-arms the SLA timer, triggers your Customer Agent unassigned workflow, starts the Sidekick discussion, and assigns the thread to your human team.

  3. Weekly knowledge-gap triage: Open Customer Agent → Knowledge and confirm unanswered turns in both Test Mode and Live are logging knowledge gaps for your docs team.

Troubleshooting/FAQ

The Customer Agent replied live on a channel or tier we meant to keep in Test Mode.

Test mode and Live mode are selected on each individual Assign to workflow step rather than globally, so another published workflow (or another branch) is assigning the agent with Live selected.

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, inspect the thread's workflow run log to see which workflow assigned it, and flip that step from Live to Test Mode.

The Customer Agent handed off a thread without a Sidekick summary (or left the thread unassigned).

When the Customer Agent hands off, it unassigns itself and transitions agent status to HANDED_OFF, which requires a published workflow listening to Customer Agent unassigned to run Sidekick and assign a team. If Sidekick is turned off, the Sidekick step fails. Otherwise, check these two causes:

The handoff workflow is listening to Thread status changed instead of Customer Agent unassigned

  • A handoff is an assignment and agent-status transition, so a workflow triggered only on Thread status changed won't catch every handoff.

  • Try this: Set the handoff workflow's automatic trigger to Customer Agent unassigned.

No team label or assignment step runs after the Sidekick action

  • Once the Customer Agent unassigns itself, the thread has no primary assignee until a workflow step applies a team label (with auto-assignment enabled) or runs Assign to team.

  • Try this: Place an Apply labels (with your T1/T2 team label) or Assign to team step immediately after the Sidekick action step in your handoff workflow.

The Customer Agent handed off on a question our product docs cover (or cited the wrong product's docs).

Retrieval depends on the page status being Indexed and on the thread already carrying the product label required by any label-scoped knowledge source when the Customer Agent is assigned. Check these two causes:

The product label wasn't on the thread when the Assign to step for the Customer Agent ran

  • If a knowledge source is scoped to Product > Data, the thread must have Product > Data applied before the Customer Agent is assigned.

  • Try this: Make sure the workflow that applies the product label sits above the workflow that assigns the Customer Agent on the Workflows page (or apply the product label in an earlier step of the same workflow before assigning the agent).

The sitemap or page failed indexing validation

  • Plain marks .pdf files, pages with under 100 characters of body text, and pages over 4 MB as Failed.

  • Try this: Check the Failed count under Customer Agent → Knowledge → Knowledge sources, then test the query in Customer Agent → Playground and expand Searched knowledge sources to inspect retrieval.

The Customer Agent stopped replying mid-month and started handing every thread to our human queues.

When a workspace uses 100% of its monthly included credits and any purchased top-up packs, the Customer Agent pauses automated replies and hands incoming threads to your team with an internal note.

Try this: Check your remaining balance under Settings → Billing, add a non-expiring credit top-up pack (or contact sales@plain.com to adjust your plan allowance), and audit your workflows to ensure Sidekick actions and AI prompt conditions are gated behind tier/label filters rather than running on every inbound message.