[jamesbxwu]

Agent Bricks templates omit Claude cache controls, so repeated context can be billed as fresh input. Add a shared provider adapter in databricks_agentkit.claude and enable it in all four templates. Generic Databricks OpenAI/LangChain clients forward controls and normalize cache/streaming usage; they have no caching policy flags.

Behavior and configuration

• Verified Sonnet 4.6 endpoint names use native automatic conversation placement plus a fixed system breakpoint. Older Claude names use explicit breakpoints because they reject top-level controls. The templates retain their model defaults.
• DATABRICKS_CLAUDE_PROMPT_CACHING=auto is the template default; set off in .env or the deployed environment to disable template placement. Other providers and unknown aliases keep their requests unchanged. Caller controls take precedence; transcripts are preserved.
• Streaming ChatDatabricks emits usage once, preserving inclusive gateway input totals and cache-read/write details. Chat Completions requests usage by default while honoring explicit stream options and opt-outs. Chat Completions and Responses retain cache_write_tokens; native and unified cache counters merge independently, including explicit zero values.
• Existing generated projects need dependency/template updates. CLI upgrades do not rewrite them; migration and release order are documented in the Agent Bricks caching guide.

Tracks ML-70508 and ML-70509. This consolidates #746's remaining accounting fixes and regressions. #638 independently covers the streaming deduplication portion; the template adapter, cache placement, and normalization remain part of this PR.

Verification

• Review update c032ef3 is documentation only: moved the template caching guide under Agent Bricks and updated references. All five guide links resolve, all four templates use DATABRICKS_CLAUDE_PROMPT_CACHING, and git diff --check passes. No runtime or live tests were rerun for this documentation change.
• 177 LangChain tests passed, 2 skipped, including HTTP-mocked sync/async transport and LangGraph aggregation regressions at 3963189. LangChain source is unchanged by the final test-only follow-up. 15 OpenAI cache-normalization tests passed at prior code head a20ce48; Ruff, formatting, focused types, and diff checks pass. The follow-up uses getattr in the SDK extension-field assertion to fix CI compatibility. No new live/model calls were run for this consolidation. Public CI is separate.
• At prior head 8258bc8: 288 focused SDK/adapter/template tests passed, plus 1,736 AgentKit tests, 45 generated OpenAI template tests, 44 wheel-backed functional tests, lint/type checks, and adapter compatibility tests with OpenAI 1.99.9 and 2.54. Its 54 green public checks belong to that earlier head.
• Historical 20 live cache checks covered Gateway/FMAPI forwarding and usage, native 4.6 and explicit 4.5 template placement, both frameworks, streaming, tool turns, and actual cache reads. A later combined-source run passed all 20 cache tests; its rerun was partly blocked by the shared Gateway budget. These runs predate the consolidation and are not fresh acceptance of this head. No budgets were changed.

When adopting alongside #750, compose the cache and Gemini-signature normalizers in each shared OpenAI response hook. The historical combined test branch records this integration; it must not be merged into main.

CI on the preceding consolidation head failed only the corrected SDK-field assertion and the six memory-backed parallel-history ordering cases already reproduced on main. #582's new framework job has the same six baseline failures. No skips or forced passes were added. GitHub currently reports merge conflicts with main; the documentation revision does not resolve them.

[jamesbxwu]

is this file necessary? the other docs in this folder are pretty generic. While I agree that we should have documentation on this prompt caching feature, I'm not sure if this is the right place, especially when I see you mention things like the AgentBricks template. That is specific to the integration AgentBricks folder. I should not be at the top level here.

[jamesbxwu]

why mention claude here when the env var is named in a generic way DATABRICKS_PROMPT_CACHING?

[jamesbxwu]

It feels weird that the Databricks prompt caching flag is only for Claude. If this is really specific to Claude, perhaps we need to rethink the name of the environment variable so we can avoid confusion?

[jamesbxwu]

+1 on above