> ## Documentation Index
> Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Cache Agent Starter

> A runnable starter for agent runtime cost controls, prompt caching boundaries, and cold-versus-warm usage checks.

<div className="not-prose my-4 rounded-md border border-gray-200 bg-gray-50 p-2 text-sm dark:border-gray-800 dark:bg-gray-900/40">
  <div className="mb-2 px-1 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">Need help?</div>

  <div className="flex flex-wrap gap-2">
    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://discord.gg/sDE2HhGTg4" target="_blank" rel="noreferrer">
      <Icon icon="discord" iconType="brands" size={14} />

      <span>Ask in Discord</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/issues/new/choose" target="_blank" rel="noreferrer">
      <Icon icon="github" iconType="brands" size={14} />

      <span>Open a GitHub issue</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/SUPPORT.md" target="_blank" rel="noreferrer">
      <Icon icon="life-ring" size={14} />

      <span>Support guide</span>
    </a>
  </div>
</div>

## Summary

This starter shows a small prompt-cache-aware agent loop for agent runtime cost
controls: stable prompt layers first, dynamic memory later, and a tiny
benchmark surface for comparing cold and warm run metadata.

## Status

`starter`

Source code: [patterns/examples/prompt-cache-agent-starter](https://github.com/Prompthon-IO/agent-systems-handbook/tree/main/patterns/examples/prompt-cache-agent-starter)

## Why It Exists

Prompt caching is easy to describe and easy to misuse. Builders often place
retrieved memory, user-specific facts, or current-turn inputs inside the same
long prefix they expect the provider to cache. That makes cache behavior harder
to reason about.

This starter keeps the boundary visible. It treats tool manifests, system
instructions, and stable reference context as cacheable layers, while durable
memory summaries and current tasks stay outside the cached prefix unless the
builder intentionally promotes them.

## Agent Runtime Cost Controls

Recent agent SDK changes are a reminder that provider billing rules and pricing
tables can move faster than a handbook page. The durable lesson is to keep the
runtime cost boundary inspectable:

* treat tools, system instructions, and shared reference context as the stable
  prefix
* move user-specific memory, current-turn tasks, and volatile tool outputs
  later in the request
* track cache writes and cache reads separately so a warm rerun is verifiably
  cheaper instead of only shorter
* compare SDK-side estimates with provider-side usage reporting before turning
  token math into budgets or customer billing

This starter stays provider-agnostic, but current Anthropic and OpenAI docs now
reinforce the same pattern: stable prefixes improve cache reuse, runtime usage
fields reveal whether cache hits actually happened, and explicit cost controls
belong in the operator loop instead of guesswork.

## Related Lab Pages

* [Agent Memory And Retrieval](/patterns/agent-memory-and-retrieval)
* [Agent Runtime Building Blocks](/patterns/agent-runtime-building-blocks)
* [Patterns Overview](/patterns)
* [Contribution Workflow](/contributor-kit/contribution-workflow)

## Folder Structure

```text theme={null}
prompt-cache-agent-starter/
├── README.md
├── SOURCE_NOTES.md
├── index.mdx
├── src/
│   └── prompt_cache_agent_starter.py
└── tests/
    └── test_prompt_cache_agent_starter.py
```

## Included Sample Files

* `src/prompt_cache_agent_starter.py`: typed helpers for prompt layers, cache
  boundary detection, usage summaries, and cold/warm comparisons
* `tests/test_prompt_cache_agent_starter.py`: executable smoke test for the
  starter behavior
* `SOURCE_NOTES.md`: source lineage and attribution boundary

## Flow Boundaries

The starter may:

* model prompt layers as cacheable or dynamic
* calculate where the stable prefix ends
* compare cache-read and cache-write shares
* estimate input cost when current pricing values are supplied

When you map it to a real runtime, preserve three separate checks:

* a stop condition or budget control before the loop runs too far
* cache-specific usage fields that show whether repeated prefixes were reused
* an authoritative usage export or admin API outside local estimates

The starter must not:

* call a real API
* store raw transcripts
* hardcode provider prices
* collapse durable memory into the cached prefix by default

## Quick Start

From the repository root:

```bash theme={null}
python3 patterns/examples/prompt-cache-agent-starter/tests/test_prompt_cache_agent_starter.py
python3 scripts/verify_example_projects.py
```

## Next Steps

* Add a provider adapter that consumes redacted Claude usage metadata.
* Add a small JSONL fixture for documentation-only report examples.
* Add a companion notebook if the benchmark flow becomes more exploratory.