Skip to main content
The subagent tool allows an AI assistant to delegate complex, specialized, or multi-step tasks to a dedicated sub-agent. The sub-agent runs in its own isolated session with its own context, tools, and skills, and then returns a final result back to the parent agent. This is particularly useful for breaking down large problems, utilizing specialized agents (e.g., a “Data Analyst” or “Code Reviewer” agent), or running tasks that require a specific set of tools without cluttering the main session’s context.

​
When to Use This Tool

Use the subagent tool when you need to:
  • Delegate Specialized Tasks: Hand off a specific task to an agent that is pre-configured with the right system prompt, tools, and skills for that job.
  • Isolate Context: Run a complex task in a separate session so the intermediate steps and tool outputs don’t pollute the main conversation history.
  • Parallelize Work: (When used in conjunction with parallel tool execution) Spawn multiple sub-agents to handle different parts of a problem simultaneously.

​
Input Parameters

The tool accepts the following parameters:
ParameterTypeRequiredDescription
promptstringYesThe detailed instruction or task for the sub-agent.
agent_idstringNoOptional ID (UUID) of a specific assistant/agent to use. If not provided, a default generic agent is used.
toolsarray of stringsNoOptional list of tool names the sub-agent should have access to. These will be merged with the assistant’s default tools.
skillsarray of stringsNoOptional list of skill IDs the sub-agent should have access to. These will be merged with the assistant’s default skills.
modelstringNoOptional model to use for the sub-agent. If not provided, it falls back to the assistant’s default model or the system default (e.g., gpt-4o).
external_user_idstringNoOptional external user ID to propagate context and permissions.
document_idsarray of stringsNoOptional list of document IDs to attach to the sub-session. These will be merged with the assistant’s default documents.
workspace_idsarray of stringsNoOptional list of workspace IDs to attach to the sub-session. These will be merged with the assistant’s default workspaces.

​
Output Structure

The tool returns an object containing the final result produced by the sub-agent. 
{
  "result": "The final text response or result generated by the sub-agent after completing its task."
}

​
Example Usage

​
Scenario: Delegating Data Analysis

Input: 
{
  "prompt": "Analyze the attached Q3 financial data and summarize the key revenue trends. Focus on month-over-month growth.",
  "agent_id": "uuid-for-data-analyst-agent",
  "tools": ["python_interpreter", "read_document"],
  "document_ids": ["uuid-for-q3-financial-data"]
}
Result: The subagent tool will spawn a new session using the specified Data Analyst agent. The sub-agent will use the python_interpreter and read_document tools to analyze the data. Once finished, it will use its internal submit_result tool to return the final summary. 
{
  "result": "Based on the Q3 financial data, revenue grew by 5% in July, 8% in August, and 12% in September. The key driver for this growth was the new enterprise software tier..."
}

​
Advanced Features

​
1. Context and Resource Propagation

When spawning a sub-agent, you can pass specific document_ids and workspace_ids. The system will automatically verify the user’s access to these resources and attach them to the sub-session. If no specific resources are requested, the sub-agent will inherit the default files and workspaces configured for that specific agent_id.

​
2. Tool and Skill Merging

The tools and skills arrays provided in the input are merged with the default tools and skills of the target assistant. This allows you to dynamically grant temporary capabilities to a sub-agent for a specific task.

​
3. The submit_result Mechanism

Internally, the sub-agent is instructed to use a special submit_result tool when it has completed its task. This ensures that the sub-agent explicitly defines what the final output should be, rather than the system having to guess from the conversation history.

​
4. Intermediate Results and Monitoring

While the sub-agent is processing the task, it runs in a separate, isolated session. The tool emits a data event (SUB_AGENT_STARTED) containing the sub_session_id. Clients can use this sub_session_id to monitor the sub-agent’s progress, view intermediate messages, and see tool executions in real-time before the final result is submitted. If you want to render the sub-agent’s activity in a UI, you should use the standard session endpoints to fetch the information for that sub_session_id and connect to its associated stream.

​
5. Recursion Prevention

To prevent infinite loops, the subagent tool cannot call itself recursively. Even if the subagent tool is explicitly requested in the tools array or is a default tool of the target assistant, it will be automatically removed from the sub-agent’s available tools.