Skip to main content
A ready-to-run example is available here!

Overview

The TaskToolSet lets a parent agent launch sub-agents that handle complex, multi-step tasks autonomously. Each sub-agent runs synchronously — the parent blocks until the sub-agent finishes and returns its result. Sub-agents can be resumed later using a task ID, preserving their full conversation context. This pattern is useful when:
  • Delegating specialized work to purpose-built sub-agents
  • Breaking a problem into sequential steps handled by different experts
  • Maintaining conversational context across multiple interactions with a sub-agent
  • Isolating sub-task complexity from the parent agent’s context
Each task call blocks until its sub-agent finishes. To run independent task calls concurrently, configure the parent agent’s tool_concurrency_limit. See parallel tool execution.

How It Works

The agent calls the task tool with a prompt and a sub-agent type. The TaskManager creates (or resumes) a sub-agent conversation, runs it to completion, and returns the result to the parent.

Task Lifecycle

  1. Creation: A fresh sub-agent and conversation are created
  2. Running: The sub-agent processes the prompt autonomously
  3. Completion: The final response is extracted and returned
  4. Persistence: The conversation is saved to disk for potential resumption
  5. Resumption (optional): A previous task can be resumed with its full context preserved

Setting Up the TaskToolSet

1

Register Custom Sub-Agent Types (Optional)

By default, a "default" general-purpose agent is available, but you can register your own custom types for specialized behavior:
2

Add TaskToolSet to the Agent

The tool auto-registers on import — no explicit register_tool() call is needed.
3

Create a Conversation

The DelegationVisualizer is optional but recommended — it shows the multi-agent conversation flow in the terminal.

Tool Parameters

When the parent agent calls the task tool, it provides these parameters:

Task Observation

The tool returns a TaskObservation containing:

Resuming Tasks

A key feature of TaskToolSet is the ability to resume a previously completed task. When a task finishes, its conversation is persisted to disk. Passing the resume parameter with the task ID reloads the full conversation history, allowing the sub-agent to continue where it left off.

Ready-to-run Example

This example is available on GitHub: examples/01_standalone_sdk/41_task_tool_set.py
examples/01_standalone_sdk/40_task_tool_set.py
You can run the example code as-is.
The model name should follow the LiteLLM convention: provider/model_name (e.g., anthropic/claude-sonnet-4-5-20250929, openai/gpt-4o). The LLM_API_KEY should be the API key for your chosen provider.
ChatGPT Plus/Pro subscribers: You can use LLM.subscription_login() to authenticate with your ChatGPT account and access Codex models without consuming API credits. See the LLM Subscriptions guide for details.

Parallel Trip Planning Example

This example registers lodging and activity planners, then gives the parent agent TaskToolSet with tool_concurrency_limit=2. Each task call blocks until its sub-agent returns, but independent calls can run concurrently. The parent combines the results into london_trip_report.txt and asks a follow-up question. The planners use their own knowledge, without web access. The report is not a live travel search. DelegationVisualizer labels the conversations; the example uses TaskToolSet, not the retired DelegateTool.
examples/01_standalone_sdk/25_agent_delegation.py
You can run the example code as-is.
The model name should follow the LiteLLM convention: provider/model_name (e.g., anthropic/claude-sonnet-4-5-20250929, openai/gpt-4o). The LLM_API_KEY should be the API key for your chosen provider.
ChatGPT Plus/Pro subscribers: You can use LLM.subscription_login() to authenticate with your ChatGPT account and access Codex models without consuming API credits. See the LLM Subscriptions guide for details.

Next Steps