Install & Compatibility
Where this runs
tested against v0.2.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
44MB installed
● package 44MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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())
Errors
Common errors & fixes
AttributeError: 'Agent' object has no attribute '_register_toolset'
Using old private API before 0.0.4; replaced with public API.
fixUpgrade to >=0.0.4 and use toolsets= parameter in Agent() constructor or agent.run().
TypeError: object of type 'Model' has no len()
Passing a Model object (e.g. TestModel()) as default_model before 0.0.8 was not accepted.
fixUpgrade to >=0.0.8; SubAgentConfig.model now accepts str | Model.
Upgrade
Version history
0.2.7latest on PyPI · released Jun 4, 2026
Audit
Dependencies
pydantic-ai-slimrequiredRequired, minimum version 1.74.0 for async get_instructions support.