Agents are the core building blocks of the Agency Swarm framework. Each agent is specialized for a specific role and is designed to perform a specific set of processes within an agency.

​
Key Characteristics of Agents

Autonomous

Agents can determine the next best actions by themselves.

Adaptive

Agents adapt their course of action based on real-time feedback.

Interactive

Agents can manipulate their environment by using tools.
In the latest version, agents are built on top of the agents SDK to support multi-agent collaboration within an Agency. The agent class provides context management, async execution, and streamlined tool integration.

​
Agent Parameters

The new Agent class extends the base agents.Agent with Agency Swarm-specific capabilities:

​
Agency Swarm Specific Parameters

NameParameterDescription
Files Folder (optional)files_folderPath to a local folder for managing files associated with this agent. If the folder name follows the pattern *_vs_<vector_store_id>, files uploaded via upload_file will also be added to the specified OpenAI Vector Store, and a FileSearchTool will be automatically added. Default: None
Tools Folder (optional)tools_folderPath to a directory containing tool definitions. Tools are automatically discovered and loaded from this directory. Supports both BaseTool subclasses and modern FunctionTool instances. Default: None
Schemas Folder (optional)schemas_folderPath to a directory containing openapi schema files in .json format. Schemas are automatically converted into FunctionTools. Default: None
API headers (optional)
API params (optional)		api_headers

api_params		Additional parameters to include into tools converted from OpenAPI schemas. Default: None
Description (optional)descriptionA description of the agent’s role or purpose, used to convey agent’s role to other agents. Default: None
Send Message Tool Class (optional)send_message_tool_classCustom SendMessage tool class to use for inter-agent communication. If None, uses the default SendMessage class. Default: None
Include Search Results (optional)include_search_resultsInclude search results in FileSearchTool output for citation extraction. Default: False
Validation Attempts (optional)validation_attemptsNumber of retries when an output guardrail trips. Default: 1
Return Input Guardrail Errors (optional)return_input_guardrail_errorsIf set to True, input guardrail errors will be returned as agent’s response. If set to False, will return a corresponding error. Default: None

​
Core Agent Parameters

NameParameterDescription
Name (required)nameThe name of the agent.
Instructions (optional)instructionsThe instructions for the agent. Will be used as the “system prompt” when this agent is invoked. Can be a string or a function that dynamically generates instructions. Default: None
Model (optional)modelThe model implementation to use when invoking the LLM. By default, uses the default model configured in openai_provider.DEFAULT_MODEL. Default: None
Model Settings (optional)model_settingsConfigures model-specific tuning parameters (e.g. temperature, top_p). Default: ModelSettings()
Tools (optional)toolsA list of tools that the agent can use. Default: []
MCP Servers (optional)mcp_serversA list of Model Context Protocol servers that the agent can use. Every time the agent runs, it will include tools from these servers in the list of available tools. Default: []
MCP Config (optional)mcp_configConfiguration for MCP servers. Default: MCPConfig()
Input Guardrails (optional)input_guardrailsA list of checks that run in parallel to the agent’s execution, before generating a response. Default: []
Output Guardrails (optional)output_guardrailsA list of checks that run on the final output of the agent, after generating a response. Default: []
Output Type (optional)output_typeThe type of the output object. If not provided, the output will be str. In most cases, you should pass a regular Python type (e.g. a dataclass, Pydantic model, TypedDict, etc). Default: None
To see a full list of agent parameters, refer to OpenAI documentation.Please note that agent handoff parameters are not supported. To enable handoffs, add the SendMessageHandoff tool class to the agent as shown here

​
Agent Template

Create a new agent by instantiating the Agent class:
from agency_swarm import Agent, ModelSettings

example_agent = Agent(
    name="agent_name",
    description="agent_description",
    instructions="./agent_name/instructions.md",
    files_folder="./agent_name/files",
    tools_folder="./agent_name/tools",
    tools=[],
    model_settings=ModelSettings(
        temperature=0.3,
    ),
)
You can adjust the parameters to fit the agent to your use case.