[deepagents] Document when and why to use the cache parameter

[AdemBoukhris457]

Type of issue

request for content

Language

Python

Description

Summary

create_deep_agent / createDeepAgent expose a cache argument (see config snippet in Customize Deep Agents), but the Deep Agents docs do not explain what it is, how it differs from checkpointer / store, or when readers should set it.

Current state

• Snippet: create-deep-agent-config-options-py.mdx (and JS equivalent if present) lists cache: BaseCache | None = None with no surrounding prose.
• API: In deepagents graph.py, cache is described briefly as “The cache to use for the agent” and “Passed through to [create_agent][langchain.agents.create_agent].”

Gap

Readers need a short user-facing explanation:

1. cache is LangGraph-style graph / node cache backing (e.g. InMemoryCache, SqliteCache) used with node cache_policy, not conversation persistence.
2. Contrast with checkpointer (thread state / resume / HITL), store (cross-thread app storage, e.g. StoreBackend), and Anthropic prompt caching (middleware / message cache_control) so the names are not conflated.
3. When to leave it None: typical deep agent usage without custom node cache policies.
4. When to set it: advanced cases aligning with LangGraph node caching (deterministic expensive nodes, TTL, shared cache backend).
5. Caveat: mis-keyed or over-broad caching can serve stale results for non-deterministic work.

Suggested fix

Add a Note or small subsection on the Customization page (near the config-options snippet or a “Persistence and storage” callout) with 1–2 paragraphs + a link to LangGraph Node caching and, if applicable, LangChain create_agent docs for the same parameter.

Acceptance criteria

• User-facing Deep Agents docs describe cache purpose and how it differs from checkpointer and store.
• Docs state that default None is fine for common setups.
• Link out to LangGraph (and/or LangChain) authoritative docs for BaseCache / CachePolicy.