Skip to main content
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 decide the next best action to achieve a goal autonomously within the guardrails.

Perceptual

Agents sense the environment, interpret observations, and self-correct based on feedback.

Proactive

Agents can take initiative (monitor, plan, act) and surprise you with the results, or escalate when needed.

​
Defining AI agents

An AI agent is an autonomous, goal-driven system that perceives its environment, dynamically uses tools and APIs to take actions, adapts proactively within guardrails, and can collaborate with other agents or humans.
Now, let’s breakdown this definition:
  • Autonomous - Agents define their own execution flow independently without hardcoded logic, unlike traditional workflows
  • Goal-driven - Agents are focused on outcomes, rather than on invididual steps
  • Perceives environment - Agents observe the real-world and use the feedback to validate its own actions (e.g., a coding agent testing its code)
  • Dynamic tool use - Agents generate value through actions rather than just responses (most critical characteristic)
  • Adapts within guardrails - Agents balance autonomy with safety constraints for enterprise reliability
  • Collaboration - Agents can work seamlessly with other agents or humans in multi-agent systems

​
Agent Parameters

In agency swarm, to create an agent, you need to instantiate the Agent class.
  • Core Parameters
  • Additional 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
Description (optional)descriptionA description of the agent’s role or purpose, used to convey agent’s role to other agents. Default: None
Model (optional)modelThe model implementation to use when invoking the LLM. If not provided, uses agents SDK default model. Current default model can be found here. Default: None
Model Settings (optional)model_settingsConfigures model-specific tuning parameters (e.g. temperature, top_p). See ModelSettings documentation for details. Default: ModelSettings()
Tools (optional)toolsA list of tools that the agent can use. Default: []
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
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
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: []
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, use communication_flows with the SendMessageHandoff tool class as shown here
To start receiving reasoning events for reasoning models, you need to explicitly specify reasoning parameter inside ModelSettings

​
Agent Template

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

example_agent = Agent(
    name="agent_name",
    description="agent_description",
    model="gpt-5.1",
    instructions="./instructions.md",
    files_folder="./files",
    tools_folder="./tools",
    tools=[],
    model_settings=ModelSettings(
        reasoning=Reasoning(effort="medium"),
    ),
)
You can adjust the parameters to fit the agent to your use case.