> ## 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.

# Advanced Configuration

> Learn advanced configuration options for your agents in Agency Swarm.

All parameters inside the `Agent` class follow the same structure as the OpenAI Agents SDK [`Agent`](https://openai.github.io/openai-agents-python/ref/agent/#agents.agent.Agent). However, there are a few advanced parameters that require more explanation.

### Parallel Tool Calls

Controls whether tools execute in parallel or sequentially for a given agent.

```python theme={null}
from agency_swarm import Agent, ModelSettings

agent = Agent(
    name="MyAgent",
    instructions="...",
    model_settings=ModelSettings(parallel_tool_calls=False),
)
```

To force sequential execution for a specific tool regardless of that setting, set `one_call_at_a_time = True` in the tool’s `ToolConfig`. See [Advanced Tool Configuration](/core-framework/tools/custom-tools/configuration).

### File Search

If your `files_folder` ends with `_vs_<vector_store_id>`, Agency Swarm automatically associates files with that Vector Store and adds `FileSearchTool` to the Agent. The `include_search_results` behavior can be toggled via the Agent’s `include_search_results` flag.

### Web Search Sources

```python theme={null}
from agency_swarm import Agent, WebSearchTool

agent = Agent(
    name="Researcher",
    instructions="Search the web and summarize findings.",
    tools=[WebSearchTool()],
    include_web_search_sources=True,  # default
)
```

With `include_web_search_sources=True` (default), `WebSearchTool` calls include source URLs.
Set `include_web_search_sources=False` to skip this.

### System Reminders

Use `system_reminders` when you want the agent to see a short reminder at a supported trigger, without writing hooks.

```python theme={null}
from agency_swarm import Agent

agent = Agent(
    name="SupportAgent",
    instructions="Answer clearly and keep the user moving forward.",
    system_reminders="Before replying, end with one clear next step.",
)
```

A plain string or callable is added before the first model call of each top-level user turn. It appears only in the model input and is **not saved** in the thread history.

For tool-heavy agents, add a checkpoint reminder:

```python theme={null}
from agency_swarm import Agent, EveryNToolCalls

agent = Agent(
    name="SupportAgent",
    instructions="Answer clearly and keep the user moving forward.",
    system_reminders=[
        "Before replying, end with one clear next step.",
        EveryNToolCalls(15, "Pause and summarize progress before using more tools."),
    ],
)
```

`EveryNToolCalls` counts local function tools and hosted tools (such as `WebSearchTool` and `FileSearchTool`) toward the same threshold.

If the reminder needs agency context, pass a callable:

```python theme={null}
from agency_swarm import Agent, MasterContext, RunContextWrapper

def build_reminder(ctx: RunContextWrapper[MasterContext], _agent: Agent) -> str:
    customer_name = ctx.context.user_context.get("customer_name", "the user")
    return f"Greet {customer_name} by name and end with one next step."

agent = Agent(
    name="SupportAgent",
    instructions="Answer clearly and keep the user moving forward.",
    system_reminders=build_reminder,
)
```

<Note>
  Use `system_reminders` for normal reminders. Use `hooks` only when you need custom lifecycle behavior beyond these built-in triggers.
</Note>

<Note>
  Creating your first agent with `system_reminders` installs a process-wide boundary around `Runner.run`, `Runner.run_sync`, `Runner.run_streamed`, and `RunState` serialization. That boundary is what keeps reminders out of saved history when you call `Runner` directly instead of going through an `Agency`. It stays in place for the rest of the process and applies to every agent in it, including SDK agents without reminders. Agents that never use `system_reminders` leave the SDK `Runner` untouched.
</Note>

### Conversation starters cache

Conversation starters are the suggested prompts you see in the chat UI.
When enabled, cache can instantly replay the first reply without calling the LLM.

```python theme={null}
from agency_swarm import Agent

agent = Agent(
    name="SupportAgent",
    instructions="You are helpful.",
    model="gpt-5.6-luna",
    conversation_starters=["Support: I need help with billing"],
    cache_conversation_starters=True,
)
```

In this example:

* The UI shows the starter prompt “Support: I need help with billing”.
* The FastAPI `/get_metadata` response exposes starters as `conversationStarters`.
* With `cache_conversation_starters=True`, the first plain-text user message can replay a saved reply when it exactly matches a configured starter.

<Info>
  Streaming the cached reply includes events for text, tool calls, reasoning, and handoffs.
</Info>

If you change key agent settings (like instructions, tools, or model), the cache for first-turn responses is rebuilt.
Per-run overrides like `additional_instructions`, `context_override`, or `hooks_override` skip replay and call the LLM.

<Note>
  Cache files live under `AGENCY_SWARM_CHATS_DIR` (defaults to `.agency_swarm`) in `starter_cache/`.
  In production, point `AGENCY_SWARM_CHATS_DIR` at persistent storage to keep instant replies across restarts.
</Note>

See also: [Agent Overview](/core-framework/agents/overview), [FastAPI Integration](/additional-features/fastapi-integration).

### Output Validation

Use `output_guardrails` on the `Agent` to validate outputs. See the detailed guide: [Guardrails](/additional-features/guardrails/overview).

### Few‑Shot Examples

You can include few‑shot examples in `instructions` as plain text or pass message history to `get_response` / `get_response_stream`.

```python theme={null}
from agency_swarm import Agent

agent = Agent(name="MyAgent", instructions="You are a helpful assistant.")

examples = [
    {"role": "user", "content": "Hi!"},
    {"role": "assistant", "content": "Hello!"},
]
new_message = {"role": "user", "content": "Can you help me write a short summary?"}

response = await agent.get_response(examples + [new_message])
```

See also: [Few‑Shot Examples](/additional-features/few-shot-examples).