Subagents Pydantic AI
Subagent Delegation framework for Pydantic AI, enabling nested subagents that can spawn their own specialists on-the-fly, with smart sync/async/auto mode selection, runtime agent creation, and clean multi-agent architecture. Adds specialization, parallel execution, and task cancellation.
Install / Use
npx skills add vstorm-co/subagents-pydantic-aiInstalls into whichever agent you are using.
Quality Score
Category
Development & EngineeringSupported Platforms
README
Part of Pydantic Deep Agents — the open-source Claude Code alternative & Python agent framework. Use this library standalone, or get everything wired together in one
create_deep_agent()call.
Subagents for Pydantic AI adds multi-agent delegation to any Pydantic AI agent. Spawn specialist subagents that run synchronously (blocking), asynchronously (background), or let the system auto-select the best mode — with built-in token tracking and cancellation.
Use Cases
| What You Want to Build | How Subagents Help | |------------------------|-------------------| | Research Assistant | Delegate research to specialists, synthesize with a writer agent | | Code Review System | Security agent, style agent, and performance agent work in parallel | | Content Pipeline | Researcher → Analyst → Writer chain with handoffs | | Data Processing | Spawn workers dynamically based on data volume | | Customer Support | Route to specialized agents (billing, technical, sales) | | Document Analysis | Extract, summarize, and categorize with focused agents |
Installation
pip install subagents-pydantic-ai
Or with uv:
uv add subagents-pydantic-ai
Quick Start
The recommended way to add subagent delegation is via the Capabilities API:
from pydantic_ai import Agent
from subagents_pydantic_ai import SubAgentCapability, SubAgentConfig
agent = Agent(
"openai:gpt-4.1",
capabilities=[SubAgentCapability(
default_model="openai:gpt-4.1",
subagents=[
SubAgentConfig(
name="researcher",
description="Researches topics and gathers information",
instructions="You are a research assistant. Investigate thoroughly.",
),
SubAgentConfig(
name="writer",
description="Writes content based on research",
instructions="You are a technical writer. Write clear, concise content.",
),
],
)],
)
result = await agent.run("Research Python async patterns and write a blog post about it")
SubAgentCapability automatically:
- Registers all delegation tools (
task,check_task,answer_subagent,list_active_tasks, etc.) - Injects dynamic system prompt listing available subagents
- Includes a general-purpose subagent when given a
default_modelor adefault_agent_factoryto build it from
Alternative: Toolset API
For lower-level control:
from pydantic_ai import Agent
from subagents_pydantic_ai import create_subagent_toolset, SubAgentConfig
toolset = create_subagent_toolset(
default_model="openai:gpt-4.1",
subagents=[
SubAgentConfig(name="researcher", description="Researches topics", instructions="..."),
],
)
agent = Agent("openai:gpt-4.1", toolsets=[toolset])
Note: With the toolset API, you need to wire
get_subagent_system_prompt()manually.SubAgentCapabilityhandles this automatically.
Execution Modes
Choose how subagents execute their tasks:
| Mode | Description | Use Case |
|------|-------------|----------|
| sync | Block until complete | Quick tasks, when result is needed immediately |
| async | Run in background | Long research, parallel tasks |
| auto | Smart selection | Let the system decide based on task characteristics |
Sync Mode (Default)
# Agent calls: task(description="...", subagent_type="researcher", mode="sync")
# Parent waits for result before continuing
Async Mode
# Agent calls: task(description="...", subagent_type="researcher", mode="async")
# Returns task_id immediately, agent continues working
# Later: check_task(task_id) to get result
Auto Mode
# Agent calls: task(description="...", subagent_type="researcher", mode="auto")
# System decides based on:
# - Task complexity (simple → sync, complex → async)
# - Independence (can run without user context → async)
# - Subagent preferences (from config)
Give Subagents Tools
Provide toolsets so subagents can interact with files, APIs, or other services:
from pydantic_ai_backends import create_console_toolset
def my_toolsets_factory(deps):
"""Factory that creates toolsets for subagents."""
return [
create_console_toolset(), # File operations
create_search_toolset(), # Web search
]
toolset = create_subagent_toolset(
default_model="openai:gpt-4.1",
subagents=subagents,
toolsets_factory=my_toolsets_factory,
)
Dynamic Agent Creation
Create agents on-the-fly and delegate to them seamlessly:
from subagents_pydantic_ai import (
create_subagent_toolset,
DynamicAgentRegistry,
)
registry = DynamicAgentRegistry()
agent = Agent(
"openai:gpt-4o",
deps_type=Deps,
toolsets=[create_subagent_toolset(
default_model="openai:gpt-4o",
registry=registry,
delegation_configuration="persisted",
allowed_models=["openai:gpt-4o", "openai:gpt-4o-mini"],
)],
)
# Now the agent can:
# 1. create_agent(name="analyst", ...) — creates a new agent in registry
# 2. task(description="...", subagent_type="analyst") — delegates to it
Delegation Configuration
Choose which delegation entry points are exposed:
| Mode | Entry-point tools |
|------|-------------------|
| "default" | task (backward-compatible) |
| "persisted" | create_agent, task |
| "persisted_and_oneshot" | create_agent, task, delegate |
| "oneshot_only" | delegate |
Async task lifecycle tools remain available in every mode. One-shot specialists are not registered and cannot be reused by name.
from subagents_pydantic_ai import create_subagent_toolset
toolset = create_subagent_toolset(
default_model="openai:gpt-4o",
delegation_configuration="persisted_and_oneshot",
allowed_models=["openai:gpt-4o", "openai:gpt-4o-mini"],
capabilities_map={
"filesystem": lambda deps: [create_fs_toolset(deps.backend)],
},
)
# Parent agent calls:
# delegate(
# description="Analyze this CSV and summarize trends",
# instructions="You are a data analyst. Return concise findings.",
# name="data-analyst",
# mode="sync",
# )
Use "persisted" or "default" with create_agent / task when you need reusable specialists. Use delegate for ephemeral one-off work.
Subagent Questions
Enable subagents to ask the parent for clarification:
SubAgentConfig(
name="analyst",
description="Analyzes data",
instructions="Ask for clarification when data is ambiguous.",
can_ask_questions=True,
max_questions=3,
)
The parent agent can then respond using answer_subagent(task_id, answer).
Available Tools
| Tool | Description |
|------|-------------|
| task | Delegate a task to a configured or registry-backed subagent |
| create_agent | Create a reusable registry-backed specialist (opt-in modes) |
| delegate | Create and run an ephemeral specialist in one call (opt-in modes) |
| check_task | Check status and get the full result of a background task |
| wait_tasks | Wait for background tasks, in all or any mode |
| list_active_tasks | List the running background tasks of this run |
| answer_subagent | Answer a question from a blocked subagent |
| send_message_to_subagent | Steer a running background subagent |
| soft_cancel_task | Request cooperative cancellation |
| hard_cancel_task | Immediately cancel a task |
Declarati
Related Skills
node-connect
385.5kDiagnose OpenClaw Android, iOS, or macOS node pairing, QR/setup code, route, auth, and connection failures.
python-debugpy
385.5kDebug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach.
skill-creator
385.5kCreate, edit, audit, tidy, validate, or restructure AgentSkills and SKILL.md files.
browser-automation
385.5kUse when controlling web pages with the OpenClaw browser tool, especially multi-step flows, login checks, tab management, or recovery from stale refs/timeouts.
