API Reference

Complete API documentation for Subagents for Pydantic AI.

Modules

Toolset

The main entry point for creating subagent delegation capabilities.

• create_subagent_toolset() - Create a subagent toolset
• create_agent_factory_toolset() - Create dynamic agent factory
• SubAgentToolset - The toolset class
• get_subagent_system_prompt() - Generate system prompt

Prompts & Retry

Prompt builders, default tool descriptions, and auto-retry helpers.

• get_subagent_system_prompt() - Generate system prompt
• get_task_instructions_prompt() - Generate task instructions
• RetryConfig - Resolved retry policy
• run_with_retry() - Retry driver
• is_transient_error() - Transient-error classifier
• compute_backoff_delay() - Backoff computation

Types

Data structures used throughout the library.

• SubAgentConfig - Subagent configuration
• CompiledSubAgent - Pre-compiled subagent
• TaskHandle - Background task handle
• TaskStatus - Task status enum
• TaskPriority - Task priority enum
• ExecutionMode - Execution mode type
• TaskCharacteristics - Auto-mode characteristics
• AgentMessage - Inter-agent message
• MessageType - Message type enum
• decide_execution_mode() - Mode selection function

Protocols

Interface definitions for extensibility.

• SubAgentDepsProtocol - Dependencies protocol
• MessageBusProtocol - Message bus protocol

Message Bus

Communication layer components.

• InMemoryMessageBus - Default message bus
• TaskManager - Task coordination
• create_message_bus() - Factory function

Registry

Dynamic agent management.

• DynamicAgentRegistry - Agent registry

Quick Reference

Creating a Toolset

Python

from subagents_pydantic_ai import create_subagent_toolset, SubAgentConfig

subagents = [
    SubAgentConfig(
        name="researcher",
        description="Researches topics",
        instructions="You are a research assistant.",
    ),
]

toolset = create_subagent_toolset(subagents=subagents)

Implementing Dependencies

Python

from dataclasses import dataclass, field
from typing import Any

@dataclass
class Deps:
    subagents: dict[str, Any] = field(default_factory=dict)

    def clone_for_subagent(self, max_depth: int = 0) -> "Deps":
        return Deps(subagents={} if max_depth <= 0 else self.subagents.copy())

All Exports

Python

from subagents_pydantic_ai import (
    # Toolsets
    create_subagent_toolset,
    SubAgentToolset,
    create_agent_factory_toolset,
    # Types
    SubAgentConfig,
    CompiledSubAgent,
    TaskHandle,
    TaskStatus,
    TaskPriority,
    TaskCharacteristics,
    ExecutionMode,
    AgentMessage,
    MessageType,
    ToolsetFactory,
    # Functions
    decide_execution_mode,
    get_subagent_system_prompt,
    get_task_instructions_prompt,
    # Protocols
    SubAgentDepsProtocol,
    MessageBusProtocol,
    # Message Bus
    InMemoryMessageBus,
    create_message_bus,
    TaskManager,
    # Registry
    DynamicAgentRegistry,
    # Prompts
    SUBAGENT_SYSTEM_PROMPT,
    DUAL_MODE_SYSTEM_PROMPT,
    DEFAULT_GENERAL_PURPOSE_DESCRIPTION,
    TASK_TOOL_DESCRIPTION,
)