Overview

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

Name	Parameter	Description
Name (required)	`name`	The name of the agent.
Instructions (optional)	`instructions`	The 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)	`description`	A description of the agent’s role or purpose, used to convey agent’s role to other agents. Default: `None`
Model (optional)	`model`	The model implementation to use when invoking the LLM. Omitting it or passing `model=None` selects Agency Swarm’s `gpt-5.6-luna` default. To use a different supported model, pass its name or model object explicitly.
Model Settings (optional)	`model_settings`	Configures model-specific tuning parameters (e.g. temperature, top_p). See ModelSettings documentation for details. Agency Swarm applies the model-specific SDK defaults, then fills unset fields with `truncation="auto"` and `include_usage=True`. The default `gpt-5.6-luna` reasoning effort is `"none"`.
Tools (optional)	`tools`	A list of tools that the agent can use. Default: `[]`
Tools Folder (optional)	`tools_folder`	Path 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_folder`	Path 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_servers`	A list of Model Context Protocol servers that the agent can use. Non-OAuth servers are converted into tools on run. OAuth servers are deferred behind `authenticate_mcp_server(server_name)` so auth is only triggered when the model explicitly requests it. Default: `[]`
Input Guardrails (optional)	`input_guardrails`	A list of checks that run in parallel to the agent’s execution, before generating a response. Default: `[]`
Output Guardrails (optional)	`output_guardrails`	A list of checks that run on the final output of the agent, after generating a response. Default: `[]`
Output Type (optional)	`output_type`	The 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`

Name	Parameter	Description
MCP Config (optional)	`mcp_config`	Configuration for MCP servers. Default: `MCPConfig()`
API headers (optional) API params (optional)	`api_headers` `api_params`	Additional parameters to include into tools converted from OpenAPI schemas. Default: `None`
Schemas Folder (optional)	`schemas_folder`	Path to a directory containing openapi schema files in .json format. Schemas are automatically converted into FunctionTools. Default: `None`
Validation Attempts (optional)	`validation_attempts`	Number of retries when an output guardrail trips. Default: `1`
Raise Input Guardrail Error (optional)	`raise_input_guardrail_error`	If set to `True`, input guardrail errors raise an exception. If set to `False`, the guardrail message is returned as the agent’s response. Default: `False`
System Reminders (optional)	`system_reminders`	Transient reminders shown to the model at supported triggers. A string runs before the first model call of each top-level user turn; use `EveryNToolCalls(...)` for tool checkpoints. Default: `None`
Handoff Reminder (optional)	`handoff_reminder`	Replaces the default handoff reminder system message with a given string. Default: “Transfer completed. You are [recipient_agent_name]. Please continue the task.”
Include Search Results (optional)	`include_search_results`	Include search results in FileSearchTool output for citation extraction. Default: `False`
Include Web Search Sources (optional)	`include_web_search_sources`	Include source URLs from WebSearchTool calls. Default: `True`
Conversation Starters (optional)	`conversation_starters`	List of short user prompts for UIs. Each starter must be a non-empty string. Default: `None`
Quick Replies (optional)	`quick_replies`	First-turn user phrases used for cached responses. These phrases are not shown as `conversation_starters` in the UI. Each value must be a non-empty string. Default: `None`.
Starter Cache (optional)	`cache_conversation_starters`	Enables caching for `conversation_starters`. When `True`, a first-turn message that matches a `conversation_starter` can return a cached response instead of calling the model. This setting does not affect `quick_replies`. See Advanced Configuration. Default: `False`.

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 Handoff tool class as shown here

Agency Swarm runs the default gpt-5.6-luna model with reasoning effort set to "none". To enable reasoning and receive reasoning events, pass reasoning=Reasoning(effort="low") (or another supported effort) 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.6-luna",
    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.

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

Key Characteristics of Agents

Autonomous

Perceptual

Proactive

Defining AI agents

Agent Parameters

Agent Template

​Key Characteristics of Agents

Autonomous

Perceptual

Proactive

​Defining AI agents

​Agent Parameters

​Agent Template

Key Characteristics of Agents

Defining AI agents

Agent Parameters

Agent Template