Subagents for Pydantic AI

Multi-Agent Orchestration for Pydantic AI

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?¶

Specialization: Each subagent has focused instructions and tools for its domain. A "researcher" agent researches, a "writer" agent writes.
Parallel Execution: Run multiple tasks simultaneously in async mode. Start a research task, continue with other work, check results later.
Nested Hierarchies: Subagents can spawn their own subagents. Build complex multi-agent workflows with natural delegation patterns.
Smart Mode Selection: Auto-mode intelligently chooses sync vs async based on task complexity and requirements.

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(
        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 by default.

Alternative: Toolset API¶

Python

from pydantic_ai import Agent
from subagents_pydantic_ai import create_subagent_toolset, SubAgentConfig

toolset = create_subagent_toolset(
    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 tasks sync (blocking) or async (background)
Auto-Mode Selection	Intelligent mode selection based on task characteristics
Nested Subagents	Subagents can spawn their own subagents
Runtime Agent Creation	Create specialized agents on-the-fly
Parent-Child Q&A	Subagents can ask parent for clarification
Task Cancellation	Soft and hard cancellation support
Pluggable Message Bus	Extensible communication layer

Available Tools¶

When you add the subagent toolset, your agent gets these tools:

Tool	Description
`task`	Delegate a task to a subagent (sync, async, or auto)
`check_task`	Check status and get result of a background task
`answer_subagent`	Answer a question from a blocked subagent
`list_active_tasks`	List all running background tasks
`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 - Learn about subagents, toolsets, and types
Examples - See subagents in action
API Reference - Complete API documentation

_{Built with ❤️ by vstorm-co}