Create an Agent Stack
This walks you through creating a new Agent Stack from scratch using the guided setup wizard. You’ll end with a stack containing one or more specialists, optional knowledge access, and a chosen personality preset — ready to test.
Before you start
- A user role with the Agent Stacks permission. This is enough to create the stack and its specialists, but the wizard’s Knowledge step also writes Knowledge Base scoping and Handbook access rules, and those calls need the Knowledge Base — manage articles permission.
- A clear answer to “what is this stack going to do?” — one or two sentences. The wizard uses this to suggest specialists and seed instructions.
- (Optional) Knowledge Base categories you want the AI to read from. You can add these later.
Steps
- Open Settings → Agent Stacks.
- Click New at the top of the stack list on the left. (On a workspace with no stacks yet the empty state offers Create your first Agent Stack instead.)
- On the wizard’s first step, choose how to create the stack:
Start from scratch to build a new stack with the guided setup wizard.
Copy from existing to clone an existing stack and adjust it for a new use case or channel type.
This choice only appears once you already have at least one stack; the first stack always starts from scratch.
Start from scratch
- Purpose — the wizard’s first step, which also carries the stack type. Choose the type:
Text for chat, email, and other text-based channels.
Voice for voice-based conversations. The type cards only appear when the AI voice feature flag is enabled.
If no type is selected or provided, the stack defaults to Text. Then write 1–2 sentences under What will this agent stack handle? and give it a Stack name (what your team will call it internally). Example: “Handle inbound support for our e-commerce store. Answer order questions, process simple cancellations, escalate billing issues to humans.” 2. Agents. The wizard suggests a starter set of specialists based on your purpose — Order Tracker, Cancellation Expert, Returns Specialist, etc. Tick each suggestion on or off, edit its name and its “What does this agent do?” description, delete ones you don’t want, or click Add custom agent to add your own. Routing topics are not part of this step; the description is what the orchestrator routes on. 3. Knowledge. Pick which Knowledge Base categories these specialists should read from, and which Handbook categories. For each, choose Full access to all categories, Select specific categories, or Skip for now. 4. Personality. Pick a persona preset — Friendly help desk, Expert advisor, Concierge, Efficient, Brand-playful, or None. The dimensions snap to the preset’s values; you can tune them on the Personality tab afterwards. 5. Review & create. Confirm the configuration and click Create Stack.
The wizard creates the stack, the specialists, the knowledge bindings, and the personality config. You’re dropped into the stack’s detail view — by default on the General tab.
Copy from existing
Pick the source under Stack to copy, type a Stack name for the copy, and click Create copy. There are no further wizard steps — the copy is made from the first screen. Copying clones the stack settings, its specialists, each specialist’s knowledge scoping, capability assignments and handbook access rules, and the stack’s handover prerequisites. You can use it to create a text or voice counterpart of an existing stack, then adjust the copied configuration before testing and enabling it on channels.
Voice availability follows the same rules as creating a stack from scratch: turning a text stack into a voice copy requires the AI voice feature flag, and the server refuses the copy without it. Copying an existing voice stack as another voice stack is always allowed.
Verify it worked
- The new stack appears in Settings → Agent Stacks in the left list.
- Open the Orchestrator tab. You should see the stack diagram with the orchestrator at the top and one node for each specialist.
- Open the Testing tab and chat as a customer. The orchestrator should pick a relevant specialist and reply in the personality you chose.
What’s next
After the stack exists, the typical next steps are:
- Wire it to channels. A stack only handles conversations on the channels you enable. See your channel settings (Email, Web Chat, Voice, etc.) to enable the AI agent on the channels you want.
- Configure handover. By default a new stack has handover off (
never). Turn it on and pick a team if you want the AI to escalate to humans. - Add capabilities. Capabilities let the AI act, not just talk — look up orders, process refunds, etc.
- Test and tune. Use the Testing tab to flag bad replies and apply the proposed fixes.
Troubleshooting
- Symptom: “Knowledge Base scoping” or “Handbook access rules” appears in a “Couldn’t apply” toast after creation. Fix: the stack and specialists were created, but the post-creation knowledge wiring failed. This can happen when a custom role is missing
modules.knowledge_base, or when there is another permission gap on KB categories. Open the Orchestrator tab, drill into a specialist, and configure Knowledge from there. - Symptom: “Personality preset” failed to apply. Fix: open the Personality tab and pick the preset again. The save will succeed when called from the tab itself.
- Symptom: No suggested specialists appear on the Agents step. Fix: the AI suggestion call failed. Use Add custom agent to add your specialists by hand.