Response Caching

from tempfile import TemporaryDirectory

from agno.agent import Agent
from agno.models.openai import OpenAIResponses

prompt = "Write a short story about a cat that solves problems."

with TemporaryDirectory() as cache_dir:
    agent = Agent(
        model=OpenAIResponses(
            id="gpt-5.4-mini",
            cache_response=True,
            cache_dir=cache_dir,
        )
    )
    first_response = agent.run(prompt)
    cached_response = agent.run(prompt)

print(first_response.content)
print(cached_response.content)

With an empty cache, the first model call uses the provider and writes the response to disk. A later call with the same cache key returns the stored ModelResponse without contacting the provider.

Install the OpenAI integration and set OPENAI_API_KEY before running the examples:

uv pip install "agno[openai]"
export OPENAI_API_KEY="your-api-key"

Response caching stores the complete model response locally. Context caching is a provider feature that reuses prompt prefixes while still making a model request.

Cache Key

Agno creates an MD5 cache key from these values:

Value	Included data
Model	Model `id`
Messages	Each message's `role` and `content`
Tools	Whether the request has any tools
Output format	The `response_format` value. Class objects contribute only their `__name__`.
Streaming	`stream=True` or `stream=False`

The key does not include the model provider or class, generation settings, message media, tool_choice, tool_call_limit, or tool definitions. Different non-empty tool lists therefore produce the same tool portion of the key. Two schema classes with the same __name__ also produce the same output-format portion.

Keep tools and model settings fixed while reusing a cache directory. A cache hit returns the stored response before tool execution, so tools are not called again. Disable response caching for tool calls with side effects. Use separate cache_dir values to isolate model instances that share an ID.

A cache hit does not reconstruct assistant or tool messages in the model's working message list. The cached content is returned, but later runs that depend on session history may not see that cached turn. Use response caching for isolated development requests and fixtures, not conversational history.

Configuration

from agno.agent import Agent
from agno.models.openai import OpenAIResponses

agent = Agent(
    model=OpenAIResponses(
        id="gpt-5.4-mini",
        cache_response=True,
        cache_ttl=3600,
        cache_dir=".cache/model-responses",
    )
)

Parameter	Default	Description
`cache_response`	`False`	Reads and writes cached model responses when enabled.
`cache_ttl`	`None`	Maximum entry age in seconds. `None` disables age-based expiration.
`cache_dir`	`None`	Directory for cache files. The default is `~/.agno/cache/model_responses`.

The default directory is shared by model instances and persists across process restarts. Each entry is a JSON file containing a timestamp and the serialized response.

Writes use ordinary JSON files without a locking or transactional storage layer. Do not share a writable cache directory across concurrent processes when cache integrity matters.

TTL is checked when an entry is read. An expired entry is treated as a cache miss, but its file is not deleted automatically. A successful request for the same key overwrites it with a new timestamp and response.

Agents and Teams

Response caching belongs to each model. Configure it on an agent's model, a team's leader model, or a member agent's model.

Use separate directories when team models need isolated caches:

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.team import Team

researcher = Agent(
    name="Researcher",
    model=OpenAIResponses(
        id="gpt-5.4-mini",
        cache_response=True,
        cache_dir=".cache/researcher",
    ),
)

team = Team(
    members=[researcher],
    model=OpenAIResponses(
        id="gpt-5.4-mini",
        cache_response=True,
        cache_dir=".cache/team-leader",
    ),
)

Streaming

from tempfile import TemporaryDirectory

from agno.agent import Agent
from agno.models.openai import OpenAIResponses

prompt = "Write a short story about a cat that solves problems."

with TemporaryDirectory() as cache_dir:
    agent = Agent(
        model=OpenAIResponses(
            id="gpt-5.4-mini",
            cache_response=True,
            cache_dir=cache_dir,
        )
    )
    agent.print_response(prompt, stream=True)
    agent.print_response(prompt, stream=True)

Streaming and non-streaming calls use different cache keys. For a completed stream, Agno stores the provider response chunks and replays them in order on a cache hit. Cache hits do not emit the ModelRequestStarted or ModelRequestCompleted lifecycle events. The stream must run to completion before Agno writes the entry. Stopping iteration early or encountering an error leaves that stream uncached.

When to Use Response Caching

Use it for	Disable it for
Repeated development and test requests	Requests that require current data
Stable prompts and model settings	Changing tools or model settings in one cache directory
Deterministic fixtures backed by model output	Tool calls with side effects
Reducing provider calls during iteration	Sensitive responses that should not be stored as local JSON