Create a tool to extend an agent's capabilities. Supported tool types include file search, web search, code interpreter, custom tools, and agent as tool. For an overview of all tool types and how they work, see Tools.

Agent as tool

To create an agent-as-tool, set type to agent_as_tool and provide the sub-agent's ID in config.agent_id. The sub-agent must already exist before creating the tool.

Each agent can only have one agent-as-tool. If an agent-as-tool already exists for the provided agent_id, the request returns an error.

Errors

"Tool already exists: <tool-name>" — A tool with this name already exists. Tool names must be unique per user.
"Tool already exists for given agent: <agent-id>" — An agent-as-tool already exists for this agent. Each agent can only have one.

For a full walkthrough including SDK examples and constraints, see Agent as tool.