subagents-pydantic-ai

From the team behind this repo: AgenticOS, the Sovereign Agentic AI Layer. AI agents your whole team can use and improve: open source (Apache-2.0), self-hosted, built on Pydantic AI.

Subagents for Pydantic AI

Declarative multi-agent orchestration. Delegate to specialist sub-agents — sync, async, or auto — with token tracking and cancellation.

Docs · PyPI · Install · Ecosystem · Deep Agents

Sync / async / auto  •  Nested subagents  •  Runtime agent creation  •  Background tasks  •  Token tracking

---

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_model or a default_agent_factory to 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. SubAgentCapability handles 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") — delega