Sub-Agents

What Are Sub-Agents

Sub-agents let one agent delegate tasks to another agent. When you assign a sub-agent to a parent agent, the sub-agent appears as a callable tool during conversations. The parent agent can decide when to call the sub-agent, pass it a task, receive the response, and incorporate it into its own reply.

This creates a hierarchy of specialists. Instead of building one agent that tries to do everything, you can build focused agents that each handle a specific domain and let a coordinator agent route tasks between them.

When to Use Sub-Agents

Sub-agents are most useful when your workflows involve multiple distinct areas of expertise. Here are some common scenarios:

Specialist Routing

A general-purpose support agent receives all incoming questions. Instead of configuring it with every possible tool and knowledge base, you give it access to specialist sub-agents — one for billing, one for technical issues, one for account management. The parent agent reads the question, decides which specialist to call, and delegates accordingly.

Complex Multi-Step Workflows

Some tasks require actions across multiple systems. For example, processing a customer refund might involve checking the order in Shopify, issuing the refund in Stripe, and updating the support ticket in Zendesk. You can build a sub-agent for each system and have the parent agent orchestrate the full workflow.

Separation of Concerns

Different tasks may require different AI models or instruction sets. A data analysis sub-agent might use a model that excels at reasoning over numbers, while a customer-facing reply agent might use one optimized for natural, empathetic writing. Sub-agents let you mix and match.

Setting Up Sub-Agents

To configure sub-agents:

1. Create the specialist agents first. Each sub-agent is a normal agent with its own instructions, model, connectors, and data sources. Build and test them individually before wiring them together.
2. Open the parent agent's configuration. Navigate to the Agents page and edit the agent you want to serve as the coordinator.
3. Assign sub-agents. In the agent configuration, you will find a section for sub-agents. Select the agents you want the parent to be able to call.
4. Update the parent's instructions. Tell the parent agent about its sub-agents and when to use them. For example: "You have access to a Billing Specialist agent. Delegate any billing-related questions to it."

How Delegation Works

When a parent agent has sub-agents assigned, each sub-agent appears as a tool the parent can call during a conversation. Here is how the process works:

1. A user sends a message to the parent agent.
2. The parent agent reads the message and decides if it should handle the task itself or delegate to a sub-agent.
3. If it delegates, it calls the sub-agent tool with a description of the task.
4. The sub-agent processes the task using its own instructions, tools, and knowledge.
5. The sub-agent returns a response to the parent agent.
6. The parent agent incorporates the sub-agent's response into its own reply to the user.

From the user's perspective, this is seamless — they are chatting with one agent and receiving unified responses. The delegation happens behind the scenes.

What the Parent Agent Controls

• Whether to delegate — The parent decides if a sub-agent is needed based on its instructions and the user's message.
• What to pass — The parent formulates the task description sent to the sub-agent.
• How to use the response — The parent can use the sub-agent's response verbatim, summarize it, combine it with other information, or even discard it if it is not helpful.

What the Sub-Agent Controls

• How to execute the task — The sub-agent uses its own instructions, model, connectors, and data sources. It operates independently within the scope of the delegated task.
• Which tools to call — The sub-agent can use any tools assigned to it, including making API calls to external services.

Example: Support Agent with a Billing Specialist

Here is a concrete example of how sub-agents work in practice:

Setup

Billing Specialist Agent

• Connected to Stripe (tools: search_customers, get_invoices, get_subscription)
• Instructions: "You are a billing specialist. Look up customer billing information, explain charges, and check subscription status. Be precise with numbers and dates."

Support Agent (Parent)

• Connected to Zendesk (tools: get_ticket, search_tickets, add_public_reply)
• Sub-agent: Billing Specialist
• Instructions: "You are a frontline support agent. Handle general inquiries yourself. When a customer asks about billing, charges, invoices, or their subscription, delegate to the Billing Specialist agent."

Conversation Flow

User: "Customer on ticket #4521 is asking why they were charged twice this month."

The Support Agent reads the ticket, sees it is a billing question, and delegates to the Billing Specialist. The Billing Specialist looks up the customer in Stripe, reviews their invoices, and returns a detailed explanation. The Support Agent then drafts a customer-friendly reply combining the billing details with the appropriate support tone, and sends it via Zendesk.