Design a multi-agent setup

Advanced · ~15 min · Prerequisites: None

What you'll do

Think through when to split agent work, map distinct roles to separate agents, plan how members move between them, and make sure the setup fits within the 20-agent cap.

One agent per role

A single agent that tries to do everything — support tickets, sales drafts, research summaries, content creation — ends up doing none of them well. Its instructions grow long and contradictory, its tools accumulate scope, and members don't know which agent to reach for.

The better pattern is one role per agent: each agent has a tight job, short instructions, and only the tools its job needs. The agent is better at its specialty, easier to maintain, and easier for members to pick.

Four ready-made examples of this pattern are already in your org: Customer Support, Sales Assistant, Research Analyst, and Content Creator each own a single domain. Use them as your model when scoping custom agents. See Building an agent for how to define an agent's scope.

Map roles to agents

Start with the workflows your team runs most. For each workflow, ask:

1. Is there a catalog agent that already covers this? If yes, use it before building a custom agent.
2. Is the job distinct enough to warrant its own agent? A job is distinct when it needs its own instructions, its own set of tools, or its own voice — and it's clearly different from what any existing agent does.
3. How often does a member need this? Daily workflows justify a dedicated agent. One-off tasks may not.

Write the list of roles, then assign each to an agent — existing or to-be-built. Identify overlaps early: if two proposed agents have nearly identical instructions, merge them.

Hand-offs between agents

Agents don't call each other automatically. Hand-offs are a member action: they finish a task with one agent and open a new thread with another.

Design for smooth hand-offs by:

• Naming agents clearly. Members should be able to tell at a glance which agent to open next. "Research Analyst" before "Content Creator" is a natural flow when writing a data-backed piece.
• Structuring output for the next step. Ask the Research Analyst to output a summary in a format the Content Creator can directly use. Members paste it into the next thread.
• Documenting the workflow. A short note in each agent's description — "Use this after Research Analyst" — helps members build the habit.

If you need fully automated hand-offs (one agent triggering another without member intervention), explore triggers and scheduling. See Triggers and Scheduling.

Mind the cap

Your org can run up to 20 custom agents at once. Draft agents count toward this limit, so keep only the drafts you're actively working on.

Before you start building, count the slots already in use at /admin/agents (the N / 20 counter in the top right). If you're close to the cap, decide which existing agent to retire or merge before adding a new one.

Catalog agents don't count against the cap.

Try this next