PR #2907: feat(sdk): add fork mode to subagents for prompt-cache reuse

• Repository: langchain-ai/deepagents
• Author: ramon-langchain
• State: open | merged: False
• Link: https://github.com/langchain-ai/deepagents/pull/2907

Description (problem / solution / changelog)

Summary

Adds an opt-in fork: bool field to SubAgent. When true, the subagent inherits the parent's composed system prompt and full message history as its prefix, seeds the task description as an additional HumanMessage, and defaults its model to the parent's (mismatch raises at build time).

The prefix alignment is what unlocks prompt-cache reuse on every supported provider — Anthropic via cache_control markers, OpenAI via the automatic Responses-API cache, Gemini 2.5 via implicit caching, and OpenRouter via pass-through. Isolation semantics are unchanged: only the fork's final message is surfaced back to the parent as a ToolMessage, and fork intermediate state is not written back.

To keep the main agent from wasting tokens re-stating context the fork already has, the task tool description annotates forked subagents with [forked — inherits full conversation context] and appends a usage-guidance block instructing the caller to pass only the task delta. Fork invocations are tagged ls_agent_type="fork-subagent" so LangSmith can filter them separately (needed to measure cache-read savings in production).

CompiledSubAgent + fork=True is rejected at build time — compiled subagents own their own system prompt and graph, so splicing in the parent prefix would be ambiguous.

Provider coverage

Fork itself is provider-neutral; each provider's existing cache path realizes the savings once the prefix aligns:

Explicit Gemini caching is skipped (incompatible with LangChain tool binding per langchain-google#1528). Anthropic-via-OpenRouter cache_control passthrough is a pre-existing deepagents limitation (AnthropicPromptCachingMiddleware no-ops on ChatOpenRouter) and is out of scope here.

Usage

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    system_prompt="<large shared instructions>",
    tools=[...],
    subagents=[
        {
            "name": "reviewer",
            "description": "Review a single artifact.",
            "system_prompt": "You review one artifact at a time.",
            "tools": [...],
            "fork": True,  # inherits parent prefix for cache reuse
        },
    ],
)

Test results

Unit tests — libs/deepagents/tests/unit_tests/test_fork_subagents.py (9 new, all pass):

• test_fork_prepends_parent_messages_when_seeding_state — fork's state["messages"] is parent history + HumanMessage(description); non-fork is just the description.
• test_fork_sets_ls_agent_type_to_fork_subagent — telemetry tag is "fork-subagent" for forks, "subagent" otherwise.
• test_forked_subagent_rendered_with_marker_and_guidance — task tool description shows [forked — inherits full conversation context] and appends the usage-guidance block.
• test_no_fork_no_marker_or_guidance — zero forks → no marker, no guidance.
• test_fork_composes_parent_prefix_and_inherits_message_history — captures the actual SystemMessage the fork's model receives; asserts it contains parent prefix + fork suffix and that parent HumanMessage is in the fork's message list.
• test_fork_without_model_inherits_parent_model — no model → defaults to parent.
• test_fork_with_mismatched_model_raises — different model class → ValueError.
• test_compiled_subagent_with_fork_raises — guards compiled + fork combo.
• test_subagent_intermediate_messages_do_not_leak_to_parent — isolation guarantee.

Full suite: 1186 passed, 84 skipped, 4 xfailed (uv run --group test pytest tests/unit_tests/ --no-cov --disable-socket --allow-unix-socket).

Live integration test — libs/deepagents/tests/integration_tests/test_fork_caching_anthropic.py (2 tests against Claude Haiku 4.5 claude-haiku-4-5-20251001):

Numbers captured via on_chat_model_start / on_llm_end callbacks, classifying each LLM call by system-message content (ls_agent_type propagates through the LangSmith tracer, not the callback metadata channel). The fork positive case reads ~80% of its input from cache on both runs; the non-fork negative control shows zero cache activity — isolating the fork flag as the cause of the savings.

Uses shared system prompt sized above Haiku's 2048-token minimum cacheable-block floor. Reads raw Anthropic cache_creation_input_tokens / cache_read_input_tokens directly because LangChain's normalized input_token_details.cache_creation is zeroed when the ephemeral TTL breakdown is present — see langchain-ai/langchain#36991.

Test Plan

• uv run --group test pytest tests/unit_tests/ — 1186 passed
• uv run --group test pytest tests/integration_tests/test_fork_caching_anthropic.py — 2 passed (live Haiku 4.5)
• uv run --all-groups ruff check deepagents tests/
• uv run --all-groups ruff format --diff
• uv run --all-groups ty check deepagents

Changed files

• libs/cli/deepagents_cli/_env_vars.py (modified, +3/-0)
• libs/cli/deepagents_cli/agent.py (modified, +12/-3)
• libs/cli/tests/unit_tests/test_agent.py (modified, +56/-0)
• libs/deepagents/deepagents/graph.py (modified, +196/-51)
• libs/deepagents/deepagents/middleware/async_subagents.py (modified, +12/-5)
• libs/deepagents/deepagents/middleware/subagents.py (modified, +283/-28)
• libs/deepagents/tests/integration_tests/fork_cache_utils.py (added, +191/-0)
• libs/deepagents/tests/integration_tests/test_fork_caching_anthropic.py (added, +38/-0)
• libs/deepagents/tests/integration_tests/test_fork_caching_openai.py (added, +35/-0)
• libs/deepagents/tests/unit_tests/test_fork_subagents.py (added, +761/-0)