Skip to main content
There are two ways for one agent to use another, and they do different jobs. This guide sets up both.

​
Before you begin

  • For Call sub-agent: an agent with two sub-agents, each with a provider. See Create an agent.
  • For Agent Task Tool: a second agent that is enabled and whose entry is a trigger. See Entries and entry handlers.
  • Both checks run the agents. Your model company bills you for those runs.

​
Let a sub-agent ask another sub-agent

The example is an agent named Support desk. Its Support sub-agent answers customers, and asks a Researcher sub-agent for the facts first.
The canvas with a Support sub-agent and a Researcher sub-agent
1

Open the calling sub-agent

Click Support on the canvas. Its panel opens.
2

Add the tool

Under Tools, open Add a tool… and choose Call sub-agent…. The Configure Call sub-agent dialog opens.
3

Name the tool

In Display name, enter ask_researcher. Use letters, numbers, and underscores, with no spaces. Some model companies reject a tool whose name contains a space.
4

Say when to use it

In When to use, enter Ask the researcher to look up the facts needed to answer the customer. The model reads this to decide when to call the tool.
5

Choose the sub-agent to call

Under Sub-agent, choose Researcher.
The Configure Call sub-agent dialog with a display name, a description, and Researcher chosen
6

Save the tool

Click Save tool. The tool appears under Tools.
7

Tell the calling sub-agent to use it

In the System prompt of Support, say when to use the tool:
Without this, the model may answer on its own and never call the tool.
8

Set what the called sub-agent asks

Click Researcher. The caller does not pass its question along. The called sub-agent asks whatever its own User prompt says, so point that prompt at the message that started the run:
Give it a System prompt for its own job, such as You look up facts and answer in one or two sentences.
The Researcher panel with a User prompt that reads the question from the request
9

Save and run

Click Save, then Run, and enter a request:
The Log shows Support starting a tool, Researcher answering, the tool finishing, and then the reply from Support.
The Run panel showing the tool call, the Researcher's answer, and the final response from Support
The called sub-agent uses its own provider, tools, and workspace, and does not see the caller’s conversation. Add one tool for each sub-agent you want reachable.

​
Pass a question of the caller’s own

If you create agents from config files, the calling model can write its own question for the called sub-agent. Declare a parameter on the tool with params, and read it in the called sub-agent’s prompt with tool_param:
The called sub-agent’s userPrompt then reads {{ tool_param "question" }}. The dashboard’s Configure Call sub-agent dialog has no setting for parameters. For the whole shape of an agent, see the CLI reference.

​
Hand a task to another agent

The example is a Helpdesk agent that hands report writing to a separate agent named Weekly report.
1

Check the other agent

Open the Weekly report agent. Its entry has to be a trigger, and the agent has to be enabled.
2

Make the other agent read the task

In its sub-agent’s User prompt, enter:
Click Save. The task arrives under the name instruction.
3

Add the tool to the first agent

Open the Helpdesk agent and click its sub-agent. Under Tools, open Add a tool… and choose Agent Task Tool…. The Configure Agent Task Tool dialog opens.
4

Name the tool and say when to use it

In Display name, enter start_weekly_report. In When to use, enter Hand over writing the weekly report. Say what it should cover.
5

Choose the agent

Under Agent, choose Weekly report. The list shows enabled agents whose entry is a trigger.
The Configure Agent Task Tool dialog with the Weekly report agent chosen
6

Save the tool and tell the agent to use it

Click Save tool. In the sub-agent’s System prompt, say when to use the tool and what to say afterwards:
Without the second sentence, the model may say the report has started without starting it.
7

Save and run

Click Save, then Run, and ask for the report. The Log shows “attempting to execute tool” and “successfully executed tool”, and the agent replies that the report has been started.
The Run panel showing the tool step and the agent confirming the report was started
The other agent’s answer never comes back to the first one. If the agent you want is missing from the Agent list, it is disabled or its entry is not a trigger.

​
Limit who can set this off

Both tools take guards. A guard checks who sent the message before the tool runs, so you can let everyone talk to an agent while only some people can make it call another one. See Guard rails.

Add a tool to an agent

The other kinds of tool a sub-agent can have.

Guard rails

Limit what people can make your agent do.

Entries and entry handlers

Triggers and the other ways an agent is started.

Tools

Every tool type and its fields.