> ## Documentation Index
> Fetch the complete documentation index at: https://agency-swarm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Understanding Agents in Agency Swarm.

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 theme={null}
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.