Add sub-agents and routing

An agent can call other agents in the workspace. Each sub-agent is an ordinary agent with its own instructions, tools and knowledge, so you can build focused specialists (orders, returns, billing) once and reuse them under several parents. For when to split an agent and how calls flow, see Multi-agent.

Add a sub-agent

Console

1. Open the parent agent and select the Sub-agents tab.
2. Select Add existing agent and choose a Workspace agent, or select Create agent to create a new draft agent and link it in one step.
3. Choose the Release to use. The child needs a published release before the parent can publish.
4. Fill in Use when and, optionally, Do not use when.
5. Choose how the sub-agent Works as (see Modes), then select Add agent.
6. Select Save draft.

A link shows Needs release while its child has no release. When the child publishes a newer release, the link shows it and offers a Use button with that version in draft; the parent keeps its fixed release until you adopt the new one and publish the parent. View agent graph shows the whole tree.

CLI

Add subAgents to the parent’s agent file. In a project, link another project agent by its file key with local; link any workspace agent by ID with agentId:

subAgents:
  - local: orders
    release: latest
    useWhen: The customer asks about an existing order, its shipment or delivery.
    doNotUseWhen: General product or policy questions with no order involved.
    mode: task_tool
  - agentId: 6f0c2a8e-4b1d-4e7a-9c3f-2d5b8a1e7f40
    release: 2.1.0
    useWhen: The customer asks how returns or refunds work in general.
    doNotUseWhen: Starting a return for a specific order.

caplo publish publishes children before parents. A single agent published with caplo agent publish needs its sub-agents to have releases already.

Link fields

Console label	YAML field	Required	Description
Workspace agent	agentId or local	One of them	The child agent. local is a file key in the same project.
Release to use	release	No	latest (default) or a fixed version such as 2.1.0. See Release pinning.
Use when	useWhen	Yes	When the parent should call this agent. Up to 2,000 characters.
Do not use when	doNotUseWhen	For fast routing	Requests that belong to the parent or another agent.
Works as	mode	No	task_tool (default) or active_conversation.

Write useWhen and doNotUseWhen as plain descriptions of customer requests. The parent’s model reads them to decide, and fast routing relies on them entirely.

Modes

Mode	Console label	What happens
task_tool	Answers and returns to this agent	The parent asks the sub-agent in plain words, the sub-agent works with its own tools and knowledge, and the parent writes the reply. The sub-agent remembers earlier requests in the same conversation.
active_conversation	Takes over the conversation	The sub-agent becomes the agent the customer talks to for the rest of the conversation, or until it hands back.

A sub-agent always runs with its own release’s tools, knowledge and settings, not the parent’s. Writes a sub-agent proposes are confirmed by the customer the same way as the parent’s.

Release pinning

Every published parent release pins an exact release of each child, so a child’s change never alters a published parent on its own.

• A fixed version (release: 2.1.0, or the console’s Release to use) keeps that child release until you change the link and publish the parent again.
• release: latest resolves to the child’s newest release that is not revoked when you push or publish the parent. With caplo publish, a child that publishes a new release also republishes the project agents that link it at latest.

When you link an existing agent in the console, the link pins the release you choose. Exported YAML writes latest only for a link without a fixed release, and caplo pull writes the release the draft pins.

Caution

Revoking a child release stops every parent release that pins it from running that child. Publish the parents with a usable child release first. See Publish an agent.

Depth limit

Sub-agents can have sub-agents of their own. policy.maxDepth (Linked agent depth in the console) caps how many sub-agent links may sit below an agent: 1 to 4, default 3. Links cannot form a cycle. caplo validate checks both offline.

Routing

Routing decides how a parent picks a sub-agent for each customer message.

Mode	Console label	Behavior
model (default)	The model decides	The parent’s model reads the conversation and calls a sub-agent or answers itself. Takes about 2 seconds.
fast	Fast routing	A separate decision call picks a sub-agent in about 0.3 seconds. When its confidence is below minConfidence, the model decides instead.

routing:
  mode: fast
  minConfidence: 0.85

minConfidence (Minimum confidence, under Advanced in the console) is 0.60 to 0.99, default 0.85. Raise it if fast routing picks the wrong agent; lower it if too many turns fall back to the model. Omit the routing block for model routing.

Fast routing needs:

• At least one sub-agent, and doNotUseWhen on every link. A draft that lacks one cannot be saved.
• Fast decisions turned on for the workspace. An Owner or Admin enables it in Settings > AI providers and accepts the provider’s data processing terms, because the visitor’s recent messages and your sub-agent descriptions are sent to the decision provider. See Fast decisions. If Fast decisions are turned off later, agents set to fast routing fall back to the model on their next turn.
• Routing eval cases to publish. While the workspace requires evals, each direct sub-agent needs passing cases that set routedBy and name it in subAgent: two per sub-agent by default, set by Passing routing cases per sub-agent in Settings > General. See Routing cases.

Next steps

• Write routing eval cases.
• Publish the children, then the parent.