Subagents Pydantic AI

0.2.2 verified Fri May 01 auth: no python

Subagent toolset for pydantic-ai enabling dual-mode execution (async/sync) and dynamic agent creation. Current version 0.2.2, requires Python >=3.10, released monthly.

pip install subagents-pydantic-ai

Common errors

error AttributeError: 'Agent' object has no attribute '_register_toolset' ↓

cause Using old private API before 0.0.4; replaced with public API.

fix

Upgrade to >=0.0.4 and use toolsets= parameter in Agent() constructor or agent.run().

error TypeError: object of type 'Model' has no len() ↓

cause Passing a Model object (e.g. TestModel()) as default_model before 0.0.8 was not accepted.

fix

Upgrade to >=0.0.8; SubAgentConfig.model now accepts str | Model.

Warnings

breaking From 0.1.0 onwards, SubAgentCapability is the recommended API. Older create_subagent_toolset is deprecated and may be removed in a future version. ↓

fix Use SubAgentCapability instead of create_subagent_toolset for new code.

breaking Minimum pydantic-ai-slim bumped to 1.74.0 in 0.2.1. Older versions will cause import errors. ↓

fix Upgrade pydantic-ai-slim to >=1.74.0.

deprecated The create_subagent_toolset function is deprecated starting in 0.2.0 in favor of SubAgentCapability. ↓

fix Migrate to SubAgentCapability.

gotcha When using sync mode with can_ask_questions=True, you must provide an ask_user callback to create_subagent_toolset. Otherwise ask_parent silently fails. ↓

fix Upgrade to >=0.2.2 and pass ask_user callback.

Imports

create_subagent_toolset
```
from subagents_pydantic_ai import create_subagent_toolset
```
Primary function to create subagent toolset.
SubAgentConfig
```
from subagents_pydantic_ai import SubAgentConfig
```
Used to define subagent configurations.
SubAgentCapability
```
from subagents_pydantic_ai import SubAgentCapability
```
Capability wrapper for subagent delegation.
SubAgentSpec
```
from subagents_pydantic_ai import SubAgentSpec
```
Declarative spec for YAML/JSON config.

Quickstart

Minimal async example using SubAgentCapability.

import asyncio
from pydantic_ai import Agent
from subagents_pydantic_ai import SubAgentCapability, SubAgentConfig

async def main():
    agent = Agent(
        "openai:gpt-4o-mini",
        system_prompt="You are a helpful assistant that can delegate to subagents.",
        capabilities=[SubAgentCapability(
            subagents=[
                SubAgentConfig(
                    name="researcher",
                    description="Research any topic thoroughly.",
                    instructions="You are a research assistant. Use web search if needed.",
                    model="openai:gpt-4o-mini",
                )
            ]
        )],
    )
    result = await agent.run("What is the capital of France?")
    print(result.data)

asyncio.run(main())