Add a Specialist Agent

Add a new specialist agent to an existing Agent Stack — give it a name, a scope, and instructions, then wire knowledge and capabilities.

Updated May 13, 20265 min read

The single most effective way to make an Agent Stack better is to add another focused specialist. This walks through adding one to an existing stack.

Before you start

The stack must already exist. If you don’t have one yet, create an Agent Stack first.
Decide the specialist’s scope: a one-line description of which questions it should handle. “Billing, invoices, refunds, subscription changes” is a good scope. “Customer help” is not — it’s not specific enough to route to.

Open Settings → Agent Stacks and click into the stack you want to add a specialist to.
Click the Agents tab. (You can also use the Orchestrator canvas, but the Agents tab is the most direct path for adding a new one.)
Click + in the agent list (top-left of the pane) to open the Add Specialist Agent dialog.
Fill in:
Name — what this specialist is called internally (and what customers may see if router exposure is on). Examples: Billing Support, Returns Specialist, Onboarding Guide.
Scope — the responsibility text. Used by the router. Be topical, not flowery. Example: Billing, invoices, refunds, subscription changes.
Click Add Specialist. The specialist is created and selected in the list.
The right pane now shows the specialist’s drilldown with four sub-tabs: Setup, Capabilities, Knowledge, Playbooks.
On the Setup tab, fill in Instructions — specialist-specific behavior. Required steps, things to always do, things to never reveal, escalation triggers, reply format. Don’t restate the scope here; the router already used that. Don’t put tone here; tone is stack-wide on the Personality tab.

The new specialist appears in the agent list on the left.
On the Orchestrator canvas it shows up as a new node. Hover over it to see the routing summary card.
Open the Testing tab, send a message that matches the specialist’s scope, and confirm the router routes to it.

A new specialist starts with no knowledge access and no capabilities. To make it actually useful:

Give it knowledge access. Pick the KB categories and Handbook categories it can read.
Add capabilities. From the Capabilities sub-tab, attach the tools / actions this specialist needs. Set the security level for each — L0 (always available) through L3 (requires full authentication). See What are Capabilities?.
Optional: define explicit routing topics. Most stacks don’t need this — the scope text alone is enough — but you can add explicit routing topics if the LLM keeps mis-routing despite a clear scope.

Symptom: The new specialist shows a “No routing signals” warning on the Orchestrator canvas. Fix: the Scope is empty and there are no routing topics. Open the specialist, fill in Scope on the Setup tab, click Save Changes.
Symptom: The router never picks the new specialist even though messages match. Fix: check the Orchestrator routing rules — a tenant or stack rule might be biasing routing toward another specialist. Also confirm the new specialist’s enabled toggle is on.
Symptom: Customer-facing messages reveal the specialist’s internal name. Fix: that’s expected if the stack has “Expose specialist in customer UI” on. Either rename the specialist to something customer-friendly, or turn the option off.