Advanced Configuration

All parameters inside the Agent class follow the same structure as the OpenAI Agents SDK 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.

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.

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

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.

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:

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:

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,
)

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

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.

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.

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.

Streaming the cached reply includes events for text, tool calls, reasoning, and handoffs.

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.

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.

See also: Agent Overview, FastAPI Integration.

Output Validation

Use output_guardrails on the Agent to validate outputs. See the detailed guide: Guardrails.

Few‑Shot Examples

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

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])

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

Parallel Tool Calls

File Search

Web Search Sources

System Reminders

Conversation starters cache

Output Validation

Few‑Shot Examples

​Parallel Tool Calls

​File Search

​Web Search Sources

​System Reminders

​Conversation starters cache

​Output Validation

​Few‑Shot Examples

Parallel Tool Calls

File Search

Web Search Sources

System Reminders

Conversation starters cache

Output Validation

Few‑Shot Examples