Prompt Caching

Repeat Agent calls resend the same large system prompt every time. Set prompt_caching=True and Swarms marks the stable prefix so the provider reuses it — you pay full price once, then a discount on every call after.

When to use it

A large, reusable system prompt (persona, policies, examples) sent on every call.
The same agent runs many times or holds a multi-turn conversation.
Tool-heavy agents whose tool schemas stay constant across calls.
Long context (docs, transcripts) reused turn after turn.

Basic usage

Flip on prompt_caching. On Anthropic, Swarms adds cache_control breakpoints to the stable prefix; on OpenAI, caching is automatic and the flag leaves messages untouched. Caching only kicks in above the provider’s token minimum (see the table in the guide), so the system prompt must be large — here we repeat a string to cross that bar.

from swarms import Agent

# A large, stable system prompt is what gets cached.
system_prompt = "You are a senior financial analyst. " * 400

agent = Agent(
    agent_name="CachedAnalyst",
    model_name="claude-sonnet-4-6",
    system_prompt=system_prompt,
    prompt_caching=True,  # the on-switch
    max_loops=1,
)

# First call writes the cache.
agent.run("Summarize the risks of rising interest rates.")

# Second call reuses the cached prefix at a discount.
agent.run("Now summarize the opportunities.")

prompt_caching=True marks the system prompt (plus the last message) as cacheable.
The first run pays to write the cache.
Every later run reads the cached prefix instead of re-billing it.

Tune it with cache_config

Pass a cache_config dict to control caching. The common knob is ttl — Anthropic supports a 1-hour cache:

from swarms import Agent

agent = Agent(
    agent_name="CachedAnalyst",
    model_name="claude-sonnet-4-6",
    system_prompt="You are a senior financial analyst. " * 400,
    prompt_caching=True,
    cache_config={"ttl": "1h"},   # keep the cache warm for an hour
    max_loops=1,
)

agent.run("Give me a market outlook for Q3.")

cache_config also accepts cache_system_prompt, cache_messages, cache_tools, override, and OpenAI’s prompt_cache_key / prompt_cache_retention. See the full Prompt Caching guide under Agent Development for the complete list.

Verify it worked

agent.usage adds up the provider’s token counts for every call the agent makes. Its cached_tokens key is the part of input_tokens served from the cache. Snapshot it around the second run:

from swarms import Agent

agent = Agent(
    agent_name="CachedAnalyst",
    model_name="claude-sonnet-4-6",
    system_prompt="You are a senior financial analyst. " * 400,
    prompt_caching=True,
    max_loops=1,
)

agent.run("First question to write the cache.")

before = agent.usage
agent.run("Second question to read the cache.")
after = agent.usage

print("input tokens:", after["input_tokens"] - before["input_tokens"])
print("served from cache:", after["cached_tokens"] - before["cached_tokens"])

A non-zero cached count on the second run confirms the cached prefix was reused. See Token usage for the full set of fields.

Index

Basic Examples

Model Providers

Single Agent

Tree of Thoughts

Multi-Agent Examples

Auto Agent Builder

Scheduled Agents

Applications

Research

Technical Analysis

Use Cases

Finance

Voice Agents

Integrations

MCP Tool Integrations

Deployment

CLI

Prompt Caching

When to use it

Basic usage

Tune it with cache_config

Verify it worked

See also

​When to use it

​Basic usage

​Tune it with cache_config

​Verify it worked

​See also

When to use it

Basic usage

Tune it with cache_config

Verify it worked

See also