Diese Seite erscheint auf Englisch und Ukrainisch; unten steht die englische Fassung.

Caching tool responses with Cache-Control

For developers, in code: your Cache-Control header decides whether a tool's response is reused — max-age honoured, Age subtracted, GET and 2xx only, private per user, ten minutes at most.

The runtime calls your endpoint live on every turn that needs it — unless your own response says it may be reused. There is no freshness setting on the tool form, on purpose: you know when your data changes and we do not, so a window we invented would only ever be wrong in your name.

The rule

What we honour is the standard header.

Your response says	We do
`Cache-Control: max-age=300`	reuse it for the next five minutes instead of calling you again
`Cache-Control: max-age=300` with `Age: 290`	reuse it for ten seconds — `Age` is subtracted, so a response your CDN already held is not held again for a full window
no header, `no-store`, `no-cache`	call you every time
`max-age=86400`	reuse it for ten minutes — the ceiling, whatever the header says

s-maxage and private are ignored (we are a private cache either way); a malformed Age counts as zero.

What is cached, and when

GET only. A POST tool is always called — skipping a call that files a lead or opens a ticket would lose it.
2xx only, and never a body that was truncated at the size cap. An error is called again next time.
Only the two read paths: a model-made call and the proactive fetch. The panel’s Test button and lead delivery always go live.
Keyed on the whole resolved request — method, URL, headers, query, body — hashed, so the key covers the secret and the visitor’s {{user}} token: a response fetched for one signed-in user is never reused for another. We are a private cache, which is the only correct kind for a response fetched with an Authorization header, and Vary needs no handling. The raw request is never stored.
The raw body is stored and response_path is applied on read, so editing that field takes effect at once.

A cache hit still counts against the calls-per-turn cap, still marks the turn as answered by a tool, and still fires a bound event.

What to cache

A price list, a plan catalogue, a set of categories, store opening hours: send a max-age — it saves your server and makes the assistant answer sooner. A balance, an order status, a seat availability: leave it off.

Setting the header is worth doing even where your own layer already caches: it states your intent in a form any client can honour.

Not this: «Cache answers»

The tool form’s Advanced → Cache answers is a different switch. It governs whether a repeated opening question may be served from the runtime’s first-turn answer cache when a live tool took part in the answer. It does not cache your endpoint’s response and will not save your API a single call. Turn it on only for data that rarely changes.

The timeout is real

A slow endpoint delays an answer someone is waiting for, and a call that runs past the cap — your timeout_ms, at most ten seconds — is dropped; the assistant then answers without it. Caching the slow-but-stable parts is the cheapest way to stay under it.