Sub-agents

The sub-agent tool enables your agent to delegate specialized tasks to existing agents, reducing load and context bloat in the main agent. Think of sub-agents as isolated domain experts that the parent agent can invoke independently for specific tasks. A sub-agent is a reference to another agent by its agent_key. You create those agents first, and then add them as sub-agents.

This approach is especially useful when tasks require distinct expertise or when a single agent becomes too complex. When you add a sub-agent, you define its purpose in the sub-agent tool description, or in the main agent instructions. The main agent passes input to the sub-agent, which can access all files and artifacts available to the parent agent.

Each sub-agent maintains its own tools, instructions, and conversation history, allowing it to complete tasks independently before returning results to the main agent.

Use sub-agents when tasks benefit from specialized instructions and tools. For example, a document processing system might delegate legal review, technical accuracy checks, and content reformatting to separate sub-agents, since each task requires different expertise.

Sub-agents Tutorial

Try our Sub-agents Jupyter notebook for a hands-on example. Build a research assistant with three specialized sub-agents, including API validation to prevent common errors.

Agent key

The agent_key uniquely identifies an agent. A parent agent needs this value to
reference and invoke specific agents as subagents. You can get the agent_key from the Agents List (UI) or the List Agents endpoint (API).

How sub-agents work

When a parent agent invokes a sub_agent tool:

1. The sub-agent tool creates a new session, or resumes a previous one using a session_key.
2. The sub-agent tool calls the referenced agent (identified by agent_key) with the input message:
   • The sub-agent processes this request using its own instructions, tools, and memory.
   • The sub-agent can only access its own tools.
   • The parent agent cannot access the sub-agent's tools.
3. The sub-agent tool returns the session_key and sub_agent_response (the sub-agent's final output) to the parent agent.

For more information about sub-agents architecture and how they work, see our blog.

Tips

• The sub-agent tool always returns only the final response of the sub-agent. Activity inside the sub-agent is not returned to the parent agent. Ensure that you write sub-agent instructions so that the final message is self-contained.
• Sub-agents operate in isolated workspaces. They do not share memory, history, or tool state with the parent unless configured with artifact sharing.

Add a sub-agent with the UI

The easiest way to add a subagent is with the UI when you create or update an agent.

1. In the agent creation wizard, go to the Tools tab.
2. Click Add tool.
3. Find the Sub Agent tool in the list.
4. Enter a name for your sub agent, add a description, and enter the agent_key. You can get this value from the Agents List (UI).
5. Click Update agent.

Configure a sub-agent tool

You can also configure the sub-agent tool inline with the API. The configuration defines which agent to invoke (agent_key), optional session behavior, and optional argument_override. You can get the agent_key value from the List Agents endpoint (API).

argument_override lets you hardcode values for fields exposed to the LLM of the sub-agent tool (message and session_tti_minutes). The LLM cannot modify overridden fields or see the values that were supplied.

You can also use dynamic references inside argument_override. These values are resolved at runtime using $ref syntax and can read from:

• session.metadata.*
• agent.metadata.*

Session modes

The sub-agent tool supports three session modes that control whether sessions are resumed or created fresh each time:

• llm_controlled: (Default) The model decides when to resume a previous session or start a new one.
  If the LLM provides a session_key, the session resumes. If not, a new session starts.
• persistent: The sub-agent tool always reuses the same session created on first invocation.
  Use this for agents that build knowledge across multiple invocations, such as research or iterative drafting workflows.
• ephemeral: The sub-agent tool always starts fresh. Each call creates a new session.
  Use this when you want strict isolation and do not want state to carry across invocations.

Invoke a sub-agent

After configuring a sub-agent tool, the parent agent can invoke it by passing a task message. The sub-agent tool then calls the referenced sub-agent with this message. The message field is exposed to the LLM and defines the specific task the sub-agent must perform.

Session management

The sub-agent tool maintains sessions for sub-agents across invocations using a session_key.

• If the parent agent does not provide a session_key, the sub-agent tool creates a new session.
• If the parent agent retains the session_key of the sub-agent, the sub-agent tool resumes that session.

Sub-agent sessions are owned by the parent agent. No other agent can access them. If a parent attempts to resume a session it did not create, the request is rejected.

Artifact sharing

Parent agents can share artifacts with sub-agents through the sub-agent tool. The sub-agent tool passes the artifact to the sub-agent's workspace using the artifact_id.

note

The parent must own the artifact before sharing it. If the artifact does not exist in the parent’s workspace, the system returns an error.

Sub-agent patterns

Single task: Use when tasks do not require any context to carry over.

SINGLE TASK

Code example with json syntax.json

1

Persistent sub-agent sessions: When when tasks have multiple steps, such as iterative reviews or content generation.

PERSISTENT SUB-AGENT SESSIONS

Code example with json syntax.json

1

Multiple specialized sub-agents: Assign different sub-agents for a variety of tasks.

MULTIPLE SPECIALIZED SUB-AGENTS

Code example with json syntax.json

1

Example: Inline code review sub-agent

INLINE CODE REVIEW SUB-AGENT

Code example with curl syntax.curl

1