Skip to main content

Carry working state across steps

Agents are stateless between calls — each tool call starts fresh. When a task runs over several steps, the cache tools give the agent a small scratchpad to stash progress and pick it up again, keyed to your credential.

info

The cache is short-lived — entries expire an hour after they're written. It's for working state within a task, not durable memory. For knowledge that must persist, keep a resource instead.

What it's good for​

  • Resuming a multi-step task. Save progress after each step; if the run is interrupted, read it back and continue where it left off instead of starting over.
  • Avoiding recomputation. Cache an expensive intermediate result — a parsed document, a computed table — and reuse it across the next few steps.
  • Passing state between tool calls in a workflow, without threading it through every prompt.

How it works​

  • cache_set stores a string under a key. Serialize structured state to JSON first.
  • cache_get reads it back, returning null if the key is missing or has expired.
  • cache_delete removes it when you're done.
{ "key": "invoice-run", "value": "{\"step\":3,\"processed\":[\"a\",\"b\"]}" }

Reading invoice-run later returns that string; the agent parses it and resumes at step 3.

Good to know​

  • One-hour expiry. Entries expire an hour after the last write, and writing to a key resets its clock. Design for state that's fine to lose — treat a null from cache_get as "start fresh".
  • Scoped to your credential. A personal credential's cache is private to you; an organization credential shares one cache across the organization. Keys never cross that boundary.
  • Strings up to 256 KB. Store text; JSON-serialize anything structured, and split larger state across keys. Keys can't contain :.
  • Authenticated only. The cache tools require an API key or OAuth token — the cache is scoped to your credential.

Instruct your agent​

For a multi-step task, checkpoint your progress with cache_set under a stable key after each step, and cache_get it at the start so you can resume if interrupted. Treat a null result as a fresh start, and cache_delete the key when the task is done. Remember the cache is only kept for an hour.