agency-swarm-cn-git/docs/core-framework/agents/advanced-configuration.mdx

---
title: "Advanced Configuration"
description: "Learn advanced configuration options for your agents in Agency Swarm."
icon: "gears"
---


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

### 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
from agency_swarm import Agent

agent = Agent(
    name="SupportAgent",
    instructions="You are helpful.",
    model="gpt-5.4-mini",
    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
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).