AgentTask & TaskGroup
Task-scoped agents with typed results and ordered orchestration.
An AgentTask[T] is an Agent that completes with a typed result T. A tool
hands control to one with RunTask; the task takes over the session, runs
(possibly across turns), and returns control on Complete. TaskGroup chains
several tasks over a shared chat context.
AgentTask[T]
type AgentTaskOptions struct {
AgentOptions // instructions, tools, models, hooks
PreserveFunctionCallHistory bool
}
func NewAgentTask[T any](opts AgentTaskOptions) (*AgentTask[T], error)
func MustNewAgentTask[T any](opts AgentTaskOptions) *AgentTask[T]AgentTask[T] embeds *Agent, so it takes the same AgentOptions (instructions,
tools, per-agent models, hooks). It adds completion:
func (t *AgentTask[T]) Complete(result T) error
func (t *AgentTask[T]) Fail(err error) error
func (t *AgentTask[T]) Done() bool
func (t *AgentTask[T]) Result(ctx context.Context) (T, error)Inside the task's tools, call Complete to finish with a value (or Fail to
error out); this is what returns control to the caller.
RunTask
func RunTask[T any](ctx context.Context, run *tool.RunContext, task *AgentTask[T]) (T, error)Called from inside a tool on the parent agent. It suspends the parent's
speech handle, activates the task (running its OnEnter), and blocks until the
task completes — then merges the task's context back and resumes the parent.
Takeovers nest as a LIFO stack.
addr := agents.MustNewAgentTask[Address](agents.AgentTaskOptions{
AgentOptions: agents.AgentOptions{Instructions: "Collect a postal address."},
})
result, err := agents.RunTask(ctx, run, addr) // parent resumes with resultIf an explicit UpdateAgent changes the active agent while the task runs, or the
session closes, RunTask still returns the result (or context error) but the
parent is not resumed — control stays where the explicit change left it.
TaskGroup
Runs an ordered set of tasks over a shared chat context.
type TaskGroupOptions struct {
ChatContext *llm.ChatContext
OnTaskCompleted func(context.Context, TaskCompletedEvent) error
ReturnExceptions bool
SummarizeChatContext bool
PreserveFunctionCallHistory bool
}
func NewTaskGroup(opts TaskGroupOptions) (*TaskGroup, error)
func (g *TaskGroup) Add(factory func() TaskGroupTask, id, description string) error
func (g *TaskGroup) Run(ctx context.Context) (TaskGroupResult, error)Add registers a task factory under a unique id (used as the result key);
Run executes them in insertion order. The result is a
TaskGroupResult{ TaskResults map[string]any } keyed by task id.
OnTaskCompleted fires after each task; ReturnExceptions collects failures
instead of stopping the group.
Task ids must be unique within a group — Add rejects duplicates, since ids key
the results map.
Related
- Tasks & sub-agents — the guide with worked examples.
- Agents & handoffs — handoff vs. delegate.
- Agent