Tasks & sub-agents

An AgentTask[T] is an agent that completes with a typed result. A tool hands control to one with agents.RunTask; the task takes over the session, runs (possibly across several user turns), and on Complete returns control to the caller with a value. Unlike a handoff (one-way), a task is a call-and-return — use it to collect an address, run a survey step, or capture structured data, then carry on.

Delegate and resume

type Address struct {
    Line1    string `json:"line1"`
    Postcode string `json:"postcode"`
}

collectAddress := agents.MustNewAgentTask[Address](agents.AgentTaskOptions{
    AgentOptions: agents.AgentOptions{
        Instructions: "Collect the caller's postal address, then complete.",
        // a tool inside the task calls task.Complete(addr)
    },
})

getAddress, _ := tool.New("get_shipping_address",
    func(ctx context.Context, run *tool.RunContext, _ *struct{}) (*Address, error) {
        addr, err := agents.RunTask(ctx, run, collectAddress) // blocks until Complete
        if err != nil {
            return nil, err
        }
        return &addr, nil // parent has resumed; return the collected value
    },
)

While the task runs it becomes the active agent; the parent's speech is locked against interruption and its turn is parked. When the task calls Complete, its chat context merges back and the parent resumes — a stack, so takeovers nest (a sub-agent can delegate to a sub-sub-agent, unwinding LIFO).

TaskGroup — a fixed sequence

TaskGroup runs an ordered set of AgentTasks over a shared chat context, each completing with its result, with an optional completion callback and a return-exceptions policy. Reach for it for scripted multi-step flows (a survey, an intake form) rather than model-driven routing.

Next

• Tools — the tools a task (or agent) runs.
• Full API: Reference → AgentTask & TaskGroup.