How to Spawn a Subagent?

[liukaizheng]

I want to spawn a subagent by tool-call. when executing the subagent tool, the result is the handle of async task of spawning subagent instead of waiting subagent finished. How do I know the subagent is finished? how to keep the current turn running to wait subagent finished?

[gold-silver-copper]

The Rig way to model this is to make the subagent a tool.

Rig already implements Tool for Agent<M>, so an agent can be passed directly into another agent with .tool(sub_agent). When the parent agent calls that tool, Rig awaits the subagent's prompt(...) call and uses the subagent's final answer as the tool result.

That means the current turn stays running automatically. You do not need to return a task handle or manually check whether the subagent has finished.

There is an existing example in the repo: examples/agent_with_agent_tool.rs.

The key part is:

let calculator_agent = openai_client
    .agent(providers::openai::GPT_4O)
    .preamble("You are a calculator...")
    .tool(Adder)
    .tool(Subtract)
    .build();

let agent_using_agent = openai_client
    .agent(providers::openai::GPT_4O)
    .preamble("You are a helpful assistant...")
    .tool(calculator_agent)
    .build();

In this workflow:

1. The parent agent decides to call the subagent tool.
2. Rig invokes the subagent.
3. Rig waits for the subagent to finish.
4. The subagent's final answer is returned as the tool result.
5. The parent agent continues its turn with that tool result.

So for your use case, instead of spawning the subagent and returning an async task handle, register the subagent itself as a tool:

let sub_agent = client
    .agent(openai::GPT_5_2)
    .name("researcher")
    .description("Handles focused research tasks")
    .preamble("You are a focused research subagent.")
    .default_max_turns(4)
    .build();

let parent_agent = client
    .agent(openai::GPT_5_2)
    .preamble("Use the researcher tool when delegation is useful.")
    .tool(sub_agent)
    .default_max_turns(4)
    .build();

let answer = parent_agent
    .prompt("Research this topic and summarize the result.")
    .max_turns(4)
    .await?;

The important detail is that the subagent tool returns only after the subagent has produced its final answer. That final answer is what the parent agent receives as the tool result.

[liukaizheng]

Thanks for your patient answer. But there's still something nagging at me.

In a streaming prompt loop, all tools are executed synchronously. Spawning a subagent is usually time-consuming and blocks the main thread. So I'd like the tool result of spawning a subagent to be an async task handle rather than the actual tool result.

What's the right rig way to achieve this?