---
title: "Overview"
description: "Understanding Agents in Agency Swarm."
icon: "globe"
---

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

<CardGroup cols={3}>
  <Card
    title="Autonomous"
    icon="robot"
  >
    Agents can decide the next best action to achieve a goal autonomously within the guardrails.
  </Card>

  <Card
    title="Perceptual"
    icon="eye"
  >
    Agents sense the environment, interpret observations, and self-correct based on feedback.
  </Card>

  <Card
    title="Proactive"
    icon="lightbulb"
  >
    Agents can take initiative (monitor, plan, act) and surprise you with the results, or escalate when needed.
  </Card>
</CardGroup>

## Defining AI agents

<Callout type="info" icon="robot" title="What is an AI Agent?">
**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.**
</Callout>

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. 

<Tabs>
  <Tab title="Core 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. If not provided, uses agents SDK default model. Current default model can be [found here](https://openai.github.io/openai-agents-python/models). Default: `None` |
| Model Settings *(optional)* | `model_settings` | Configures model-specific tuning parameters (e.g. temperature, top_p). See [ModelSettings documentation](https://openai.github.io/openai-agents-python/ref/model_settings/) for details. Default: SDK defaults with Agency Swarm applying `truncation="auto"` when unset. |
| 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. Every time the agent runs, it will include tools from these servers in the list of available tools. 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` |

  </Tab>
  <Tab title="Additional Parameters">
| Name | Parameter | Description |
|------|-----------|-------------|
| MCP Config *(optional)* | `mcp_config` | Configuration for MCP servers. Default: `MCPConfig()` |
| API headers *(optional)*<br/>API params *(optional)*| `api_headers`<br/><br/>`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` |
| 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](/core-framework/agents/advanced-configuration#conversation-starters-cache). Default: `False`. |

  </Tab>
</Tabs>

<Note>
To see a full list of agent parameters, refer to [OpenAI documentation]( https://openai.github.io/openai-agents-python/ref/agent/#agents.agent.Agent).

Please note that agent handoff parameters are not supported. To enable handoffs, use `communication_flows` with the `Handoff` tool class as [shown here](/additional-features/custom-communication-flows/overview)
</Note>

<Warning>
To start receiving reasoning events for reasoning models, you need to explicitly specify `reasoning` parameter inside `ModelSettings`
</Warning>

## Agent Template

Create a new agent by instantiating the Agent class:

```python
from agency_swarm import Agent, ModelSettings, Reasoning

example_agent = Agent(
    name="agent_name",
    description="agent_description",
    model="gpt-5.4-mini",
    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.