Teams API

Agent teams coordinate multiple peer agents that share a TODO list and exchange messages. Enable them via include_teams=True on create_deep_agent. See Teams for the conceptual overview.

AgentTeam

pydantic_deep.toolsets.teams.AgentTeam dataclass

Multi-agent team with shared state.

Coordinates shared TODO lists and peer-to-peer messaging between team members. Execution is delegated to the subagent system via a DynamicAgentRegistry.

spawn() async

Register all members on the message bus and prepare handles.

assign(member_name, task_content) async

Add a task to the shared todo list and claim it for a member.

broadcast(message) async

Send a message to all members.

wait_all() async

Wait for all running member tasks to complete.

dissolve() async

Unregister all members, cancel running tasks, mark team dissolved.

TeamMember

pydantic_deep.toolsets.teams.TeamMember dataclass

A member of an agent team.

TeamMemberHandle

pydantic_deep.toolsets.teams.TeamMemberHandle dataclass

Handle to a running team member.

SharedTodoItem

pydantic_deep.toolsets.teams.SharedTodoItem dataclass

A todo item for team-shared task management.

Unlike the regular Todo (from pydantic-ai-todo), this includes assigned_to, blocked_by, and created_by fields for multi-agent coordination.

SharedTodoList

pydantic_deep.toolsets.teams.SharedTodoList

Asyncio-safe shared TODO list for agent teams.

Uses asyncio.Lock for concurrent access safety. Supports claiming, dependencies, and auto-unblocking.

add(content, *, blocked_by=None, created_by=None) async

Add a new item. Returns its ID.

claim(item_id, agent_name) async

Claim an item for an agent.

Returns False if already claimed, not found, not pending, or blocked by incomplete dependencies.

complete(item_id) async

Mark an item as completed.

get_available() async

Get items that are pending, unclaimed, and not blocked.

get_all() async

Get all items.

get(item_id) async

Get a single item by ID.

remove(item_id) async

Remove an item. Returns False if not found.

count() async

Get the number of items.

TeamMessage

pydantic_deep.toolsets.teams.TeamMessage dataclass

A message between team members.

TeamMessageBus

pydantic_deep.toolsets.teams.TeamMessageBus

Peer-to-peer message bus for agent teams.

Unlike InMemoryMessageBus (parent-child only), this supports any registered agent sending to any other registered agent.

register(agent_name)

Register an agent to send/receive messages.

unregister(agent_name)

Unregister an agent.

send(sender, receiver, content) async

Send a message to a specific agent.

Raises KeyError if the receiver is not registered.

broadcast(sender, content) async

Send a message to all registered agents except the sender.

receive(agent_name, timeout=0.0) async

Get pending messages for an agent.

Parameters:

Name	Type	Description	Default
agent_name	str	Agent whose inbox to read.	required
timeout	float	If > 0 and inbox is empty, wait up to this many seconds for a message before returning.	0.0

Raises KeyError if the agent is not registered.

registered_agents()

Get list of registered agent names.

create_team_toolset

pydantic_deep.toolsets.teams.create_team_toolset(*, id=None, descriptions=None, registry=None, agent_factory=None, task_fn=None, task_manager=None)

Create a toolset for managing agent teams.

When registry and task_fn are provided, team members are registered as subagents and assign_task delegates execution to the subagent system.

Parameters:

Name	Type	Description	Default
id	str | None	Toolset identifier. Defaults to "deep-team".	None
descriptions	dict[str, str] | None	Optional mapping of tool name to custom description.	None
registry	Any | None	DynamicAgentRegistry for registering team members as subagents at runtime.	None
agent_factory	Callable[..., Any] | None	Callable (SubAgentConfig) -> Agent used to create member agents. Passed as agent_factory on the SubAgentConfig so _compile_subagent uses it.	None
task_fn	Any | None	The subagent task() tool function. When provided, assign_task calls it to execute via the subagent engine.	None
task_manager	Any | None	Subagent TaskManager for checking task status.	None

Returns:

Type	Description
FunctionToolset[Any]	A FunctionToolset with team management tools.