pydantic-team

Type-safe team orchestration for pydantic-ai Agents.

v1 focuses on hierarchical (leader + specialists) teams — the same idea as Agno's TeamMode.coordinate and pydantic-ai agent delegation, without hiding usage/token tracking.

For sequential, branching, or stateful pipelines, use pydantic-graph (already pulled in by pydantic-ai).

Install

uv add pydantic-team
# or from a checkout:
uv sync --group lint --group dev

Requires Python 3.10+.

Documentation

Full guides and API reference (MkDocs + mkdocstrings):

uv sync --group docs
make docs-serve   # http://127.0.0.1:8000
make docs         # build into site/

HierarchicalTeam

The leader registers each member as a tool and passes usage=ctx.usage on nested runs so TeamResult.usage includes every agent involved.

import asyncio

from pydantic_ai import Agent
from pydantic_team import HierarchicalTeam

researcher = Agent(
    'openai:gpt-4o',
    name='researcher',
    instructions='Research the topic and return concise notes.',
)
writer = Agent(
    'openai:gpt-4o',
    name='writer',
    instructions='Turn research notes into a short article.',
)

team = HierarchicalTeam(
    leader_model='openai:gpt-4o',
    members=[researcher, writer],
    system_prompt_override=(
        'Delegate to researcher or writer based on the task, then synthesize a final answer.'
    ),
)


async def main() -> None:
    result = await team.run('Explain pydantic-ai agent delegation briefly.')
    print(result.data)
    print(result.usage)


asyncio.run(main())

You can also pass an existing leader_agent= instead of leader_model=. Nested HierarchicalTeam instances are valid members (set name= for a clear tool id).

See the hierarchical teams guide for nested teams, usage details, and TestModel testing.

Result type

from pydantic_team import TeamResult

# result: TeamResult
# result.data  — final leader output
# result.usage — aggregated RunUsage (requests + tokens)

Sequential / complex control flow

Use pydantic-graph when you need an ordered pipeline, branches, loops, or shared state. This library intentionally does not reimplement that.

Development

make install      # uv sync + pre-commit
make format
make lint
make typecheck
make test         # pytest with --cov-fail-under=100
make ci           # format + lint + test
make ci-strict    # lint + typecheck + test
make docs         # MkDocs build (needs --group docs)
make docs-serve

Unit tests use pydantic-ai TestModel only — no live LLM calls.

License

MIT