> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-docs-scavio-google-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Caching

> Cache model responses locally to reduce costs during development and testing.

<Badge icon="code-branch" color="orange">
  <Tooltip tip="Introduced in v2.2.2" cta="View release notes" href="https://github.com/agno-agi/agno/releases/tag/v2.2.2">v2.2.2</Tooltip>
</Badge>

```python theme={null}
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:

```bash theme={null}
uv pip install "agno[openai]"
export OPENAI_API_KEY="your-api-key"
```

<Note>
  Response caching stores the complete model response locally. [Context caching](/context/overview#context-caching) is a provider feature that reuses prompt prefixes while still making a model request.
</Note>

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

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

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

## Configuration

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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 |

## Developer Resources

* [OpenAI response caching example](/models/providers/native/openai/completion/usage/cache-response)
* [Anthropic response caching example](/models/providers/native/anthropic/usage/cache-response)
* [Model base class reference](/reference/models/model)