Subagents for Pydantic AI

Declarative multi-agent orchestration — sync, async, or auto.

---

Part of Pydantic Deep Agents

Subagents for Pydantic AI is one library in Pydantic Deep Agents — the open-source Claude Code alternative & Python agent framework. Use it standalone, or get every library wired together in a single create_deep_agent() call.

Subagents for Pydantic AI adds multi-agent delegation to any Pydantic AI agent. Spawn specialized subagents that run synchronously (blocking), asynchronously (background), or let the system auto-select the best mode.

Think of it as the building blocks for multi-agent systems - where a parent agent can delegate specialized tasks to child agents, and those children can have their own children.

Why use Subagents?

1. Specialization: each subagent has focused instructions and tools for its domain. A "researcher" agent researches, a "writer" agent writes, and neither carries the other's context.

2. Parallel execution: run several tasks in the background, keep working, and collect results with wait_tasks — reacting to the first finisher instead of stalling on the slowest.

3. Course correction: steer a running subagent when you learn something new, keeping its partial progress, and answer its questions when it needs clarification.

4. Accountability: every delegation records its cost, tokens, tool calls, and traceparent, so a fan-out is not a black box.

Quick Start (Capability API)

The recommended way to add subagent delegation — one import, plug and play:

Python

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.",
            ),
        ],
    )],
)

result = await agent.run("Research Python async patterns")

SubAgentCapability automatically registers all tools and injects a dynamic system prompt listing available subagents. A general-purpose subagent is included when a default_model or default_agent_factory is given to build it from.

Alternative: Toolset API

Python

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="...", instructions="...")],
)
agent = Agent("openai:gpt-4.1", toolsets=[toolset])

Note

With the toolset API you need to wire get_subagent_system_prompt() into the agent's instructions manually. SubAgentCapability handles this automatically.

Core features

Feature	Description
Dual-mode execution	Run a task blocking or in the background, or let mode="auto" decide
Chat traces	Continue a subagent's conversation across delegations
Questions	A subagent asks its parent for clarification mid-task
Steering	Redirect a running task without losing its progress
Cancellation	Cooperative (clean boundary) or immediate
Retries	Transient gateway failures resume from accumulated history
Usage limits	One ceiling for every delegation, or one computed per task
Observability	Per-task cost, tokens, tool-call counts, traceparent
Dynamic agents	Create specialists at runtime, reusable or one-shot

Available tools

Your agent gets these tools. create_agent and delegate are opt-in — see delegation configuration.

Tool	Description
task	Delegate a task to a configured or registry-backed subagent
create_agent	Create a reusable specialist at runtime (opt-in)
delegate	Create an ephemeral specialist and run a task in one call (opt-in)
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

Part of the Pydantic AI Ecosystem

Subagents for Pydantic AI is part of a modular ecosystem:

Package	Description
Pydantic Deep Agents	Full agent framework (uses this library)
pydantic-ai-backend	File storage and Docker sandbox backends
pydantic-ai-todo	Task planning toolset
summarization-pydantic-ai	Context management processors

Installation

Bash

pip install subagents-pydantic-ai

Next steps

• Installation — get started in minutes
• Core concepts — subagents, toolsets, observability, types
• Execution modes — when to block and when not to
• Failure handling — what propagates and what is contained
• Examples — see subagents in action
• API reference — the generated reference

---

_{Built with ❤️ by vstorm-co}