Skip to main content

​
Agency Class

The Agency class orchestrates a collection of Agent instances based on a defined structure (AgencyChart). 
from agency_swarm import Agency, Agent

class Agency:
    def __init__(self,
                 *entry_points_args: Agent,
                 communication_flows: list[tuple[Agent, Agent]] | None = None,
                 agency_chart: AgencyChart | None = None,
                 name: str | None = None,
                 shared_instructions: str | None = None,
                 send_message_tool_class: type | None = None,
                 load_threads_callback: ThreadLoadCallback | None = None,
                 save_threads_callback: ThreadSaveCallback | None = None,
                 user_context: dict[str, Any] | None = None,
                 **kwargs: Any):
        """
        Initialize an Agency instance.

        Parameters:
            *entry_points_args: Agent instances that serve as entry points for external interaction
            communication_flows: List of (sender, receiver) Agent tuples defining allowed communication paths
            agency_chart: [DEPRECATED] Legacy agency structure definition
            name: Optional name for the agency
            shared_instructions: Instructions prepended to all agents' system prompts
            send_message_tool_class: Custom SendMessage tool class for enhanced inter-agent communication
            load_threads_callback: Callable to load conversation threads from persistence
            save_threads_callback: Callable to save conversation threads to persistence
            user_context: Initial shared context accessible to all agents
            **kwargs: Additional parameters (deprecated ones will issue warnings)
        """

​
Key Attributes

  • agents (dict[str, Agent]): Dictionary mapping agent names to their instances
  • chart (AgencyChart): Structure defining agents and their communication paths
  • entry_points (list[Agent]): Agents designated as entry points for external interaction
  • thread_manager (ThreadManager): Manager responsible for handling conversation threads
  • persistence_hooks (PersistenceHooks | None): Optional hooks for loading/saving thread state
  • shared_instructions (str | None): Instructions prepended to every agent’s system prompt
  • user_context (dict[str, Any]): Shared user-defined context accessible within MasterContext
  • send_message_tool_class (type | None): Custom SendMessage tool class for all agents

​
Key Methods

async def get_response(self,
        message: str | list[TResponseInputItem],
        recipient_agent: str | Agent | None = None,
        context_override: dict[str, Any] | None = None,
        hooks_override: RunHooks | None = None,
        run_config: RunConfig | None = None,
        message_files: list[str] | None = None,
        file_ids: list[str] | None = None,
        additional_instructions: str | None = None,
        **kwargs: Any
    ) -> RunResult:
    """
    Initiate an interaction with a specified agent within the agency.

    Parameters:
        message: The input message for the agent
        recipient_agent: Target agent instance or name (defaults to first entry point)
        context_override: Additional context to pass to the agent run
        hooks_override: Specific hooks to use for this run, overriding agency defaults
        run_config: Configuration for the agent run
        message_files: Backward compatibility parameter for file attachments
        file_ids: Additional file IDs for the agent run
        additional_instructions: Additional instructions for this run only
        **kwargs: Additional arguments passed to the target agent's get_response

    Returns:
        RunResult: The result of the agent execution chain
    """

​
Deprecated Methods (Backward Compatibility)

def get_completion(self,
        message: str,
        message_files: list[str] | None = None,
        yield_messages: bool = False,
        recipient_agent: str | Agent | None = None,
        additional_instructions: str | None = None,
        attachments: list[dict] | None = None,
        tool_choice: dict | None = None,
        verbose: bool = False,
        response_format: dict | None = None,
        **kwargs: Any
    ) -> str:
    """
    [DEPRECATED] Use get_response instead. Returns final text output.

    This method exists only for backward compatibility and will be removed in a
    future release. Use get_response for new implementations.
    """

​
Agent Class

The Agent class extends the base agents.Agent with capabilities for multi-agent collaboration within an Agency. 
from agency_swarm import Agent, ModelSettings

class Agent(BaseAgent[MasterContext]):
    def __init__(self, **kwargs: Any):
        """
        Initialize an Agency Swarm Agent.

        Parameters:
            name (str): The agent's name (required)
            instructions (str): Agent instructions or path to markdown file
            model (str): OpenAI model to use
            model_settings (ModelSettings): Model configuration from agents SDK
            tools (list[Tool]): List of tools available to the agent
            files_folder (str | Path | None): Path to folder for file management and vector stores
            tools_folder (str | Path | None): Path to directory containing tool definitions
            description (str | None): Description of agent's role for inter-agent communication
            output_type (type[Any] | None): Type of the agent's final output
            send_message_tool_class (type | None): Custom SendMessage tool class
            input_guardrails (list): Input validation guardrails
            output_guardrails (list): Output validation guardrails
            hooks (RunHooks | None): Custom execution hooks
            **kwargs: Additional parameters (deprecated ones will issue warnings)
        """

​
Key Attributes

  • files_folder (str | Path | None): Local folder for file management and vector stores
  • tools_folder (str | Path | None): Directory for automatic tool discovery and loading
  • description (str | None): Agent role description for dynamic send_message tools
  • output_type (type[Any] | None): Type of the agent’s final output
  • send_message_tool_class (type | None): Custom SendMessage tool class for inter-agent communication

​
Core Execution Methods

async def get_response(self,
                      message: str | list[TResponseInputItem],
                      sender_name: str | None = None,
                      context_override: dict[str, Any] | None = None,
                      hooks_override: RunHooks | None = None,
                      run_config_override: RunConfig | None = None,
                      message_files: list[str] | None = None,
                      file_ids: list[str] | None = None,
                      additional_instructions: str | None = None,
                      **kwargs: Any) -> RunResult:
    """
    Run the agent's turn in the conversation loop.

    Parameters:
        message: Input message as string or structured input items list
        sender_name: Name of sending agent (None for user interactions)
        context_override: Optional context data to override default MasterContext values
        hooks_override: Optional hooks to override default agent hooks
        run_config: Optional run configuration settings
        message_files: DEPRECATED: Use file_ids instead
        file_ids: List of OpenAI file IDs to attach to the message
        additional_instructions: Additional instructions for this run only
        **kwargs: Additional keyword arguments including max_turns

    Returns:
        RunResult: The complete execution result from the agents SDK
    """

​
Tool Management

def add_tool(self, tool: Tool) -> None:
    """
    Add a Tool instance to the agent's list of tools.

    Parameters:
        tool: The agents.Tool instance to add

    Raises:
        TypeError: If tool is not an instance of agents.Tool
    """

​
File Management

def upload_file(self, file_path: str, include_in_vector_store: bool = True) -> str:
    """
    Upload a file using the agent's file manager.

    Parameters:
        file_path: Path to the file to upload
        include_in_vector_store: Whether to add file to vector store

    Returns:
        str: File ID of the uploaded file
    """
⌘I