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 on every model call of each top-level user turn. It appears only in the model input and is not saved in the thread history. For a long autonomous run that may call many tools before it returns, add a checkpoint reminder:

from agency_swarm import Agent, EveryNToolCalls

agent = Agent(
    name="ResearchAgent",
    instructions="Complete the full research task before replying. Use tools as needed.",
    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) separately for each agent within one logical run. A logical run starts with a user request to an agency or a direct call to Runner imported from agency_swarm. Handoffs and resumed interruptions stay in that run. The count resets when the run completes, fails, or is cancelled. For each configured EveryNToolCalls, if parallel tool calls cross several of its thresholds before the next model call, Agency Swarm produces exactly one reminder for that model call. It keeps the modulo remainder—the calls left after dividing by n—toward the next 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.

The reminder boundary lives on agency_swarm.Runner — import Runner from agency_swarm, not agents, when you run an agent directly. It keeps reminders out of saved history just like an Agency does. Calling agents.Runner directly gives you stock SDK behavior with no reminder handling.

If you save a run state to resume an interrupted run later, serialize it with run_state_to_json and restore it with run_state_from_json:

from agency_swarm import Runner, run_state_from_json, run_state_to_json

result = await Runner.run(agent, "next")
state_json = run_state_to_json(result.to_state())

restored = await run_state_from_json(agent, state_json)
result = await Runner.run(agent, restored)

Use these instead of the SDK’s RunState.to_json() / RunState.from_json(). The plain SDK methods drop the reminder state, so reminder counts restart on resume.

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