Agents as tools

An agent tool fixes the delegation target in application code. The parent keeps its conversation and receives the child’s answer. Use a sub-agent client when the model should choose from a catalog, or a handoff when a specialist should take over the current run.

Wait for a child

Given a constructed researcher, import pkg/agents/tools:

researchTool := tools.NewAgentTool(
    "research",
    "Ask the research agent to investigate a topic.",
    researcher,
    tools.SubAgentContextModeIsolated,
)

Add the tool to the parent’s AgentConfig.Tools. A synchronous child pause is forwarded through the parent, with continuation identifiers saved in tool state. Resume the parent through the normal approval flow.

Run a child in the background

researchTool := tools.NewAsyncAgentTool(
    "research",
    "Start research and deliver the answer when it finishes.",
    researcher,
    tools.SubAgentContextModeNone,
)

The constructor chooses whether to wait; there is no model-supplied async flag. The async wrapper returns a task ID and acknowledgement, then delivers the result through the background runner. It implements agents.BackgroundTool. An async child can wait for human input on its own thread. Its task stays pending while the user answers there; the completed answer subsequently reaches the parent. See sub-agent approvals.

Choose thread behavior

Context mode	Behavior
`SubAgentContextModeIsolated`	Parent tool state remembers one child thread for this agent and reuses it
`SubAgentContextModeNone`	Schema exposes optional `thread_id`; results include the child thread ID

Children run in hidden threads, grouped under and parented to the calling thread. They share its namespace and session for attachments, but do not receive the parent’s transcript. A follow-up to a child working on an async task is steered into that task. A separate thread is a history boundary; the child still has its configured tools and credentials. Register participating agents before starting durable workers, and budget for their additional model/tool calls.

Getting started

Core concepts

Models and providers

Tools and capabilities

Multi-agent patterns

Interfaces

Durable execution

Scheduled work

Workflows

Testing and operations

Wait for a child

Run a child in the background

Choose thread behavior

​Wait for a child

​Run a child in the background

​Choose thread behavior

Wait for a child

Run a child in the background

Choose thread behavior