Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

docs(dspy): document ReActV2 transition and tools (#10229)

Isaac Miller429af9125f92
diff --git a/docs/docs/api/modules/ReActV2.md b/docs/docs/api/modules/ReActV2.md
new file mode 100644
index 000000000..c0332b82b
--- /dev/null
+++ b/docs/docs/api/modules/ReActV2.md
@@ -0,0 +1,39 @@
+# dspy.ReActV2
+
+`ReActV2` is the experimental, native-tool-aware replacement for the current `dspy.ReAct` implementation. It will become `dspy.ReAct` in DSPy 3.5. The `dspy.ReActV2` name will remain as a deprecated compatibility alias throughout the 3.5 release line and will be removed in DSPy 3.6. It stores calls and results in structured `dspy.History`, supports multiple tool calls in one turn, and submits the signature's typed output fields through an internal tool.
+
+For benefits, configuration, differences from ReAct, and the plan to merge the implementation back into the canonical `dspy.ReAct` API, see [ReAct and ReActV2](../../diving-deeper/react.md).
+
+<!-- START_API_REF -->
+::: dspy.ReActV2
+ handler: python
+ options:
+ members:
+ - __call__
+ - acall
+ - batch
+ - deepcopy
+ - dump_state
+ - forward
+ - get_lm
+ - inspect_history
+ - load
+ - load_state
+ - map_named_predictors
+ - named_parameters
+ - named_predictors
+ - named_sub_modules
+ - parameters
+ - predictors
+ - reset_copy
+ - save
+ - set_lm
+ show_source: true
+ show_root_heading: true
+ heading_level: 2
+ docstring_style: google
+ show_root_full_path: true
+ show_object_full_path: false
+ separate_signature: false
+ inherited_members: true
+<!-- END_API_REF -->
diff --git a/docs/docs/api/modules/index.md b/docs/docs/api/modules/index.md
index abb0e34b5..2cb85c438 100644
--- a/docs/docs/api/modules/index.md
+++ b/docs/docs/api/modules/index.md
@@ -13,6 +13,7 @@ API reference for DSPy modules. Select a page below.
- [Predict](Predict.md)
- [ProgramOfThought](ProgramOfThought.md)
- [ReAct](ReAct.md)
+- [ReActV2](ReActV2.md)
- [Refine](Refine.md)
- [RLM](RLM.md)
<!-- END_API_INDEX -->
diff --git a/docs/docs/diving-deeper/adapters.md b/docs/docs/diving-deeper/adapters.md
index 4d03c909c..552595d27 100644
--- a/docs/docs/diving-deeper/adapters.md
+++ b/docs/docs/diving-deeper/adapters.md
@@ -182,4 +182,5 @@ Safe in-memory inputs such as data URIs, bytes, PIL images, audio arrays, and st
- [Signatures in depth](signatures-in-depth.md) — what the adapter consumes.
- [Settings and context()](settings-and-context.md) — how `configure` and `context` propagate the adapter choice.
-- Tools, ReAct, and MCP DD page — `Tool` and `ToolCalls` are adapter-formatted but module-driven.
+- [Tools and MCP](tools.md) — `Tool` and `ToolCalls` are adapter-formatted but module-driven.
+- [ReAct and ReActV2](react.md) — how the two agent loops present history and tool calls to adapters.
diff --git a/docs/docs/diving-deeper/built-in-module-variants.md b/docs/docs/diving-deeper/built-in-module-variants.md
index e42d3fc40..dd836a303 100644
--- a/docs/docs/diving-deeper/built-in-module-variants.md
+++ b/docs/docs/diving-deeper/built-in-module-variants.md
@@ -98,12 +98,13 @@ Wraps `ParallelExecutor` and submits each `(module, example)` pair to a thread p
**`dspy.KNN`** is a retrieval helper, not a generation module — see the Retrievers reference page.
-**`dspy.ReAct`** is the canonical tool-using loop and has its own page: [Tools, ReAct, and MCP](tools-react-and-mcp.md). The wrapping machinery there is what `CodeAct` and `RLM` reuse.
+**`dspy.ReAct`** is the canonical tool-using loop and has its own page: [ReAct and ReActV2](react.md). The shared [tool-wrapping machinery](tools.md) is also used by `CodeAct` and `RLM`.
## Cross-links
- [Modules: composing your own](modules.md) — every variant here is a `dspy.Module` (except `Parallel` and `majority`), so the composition rules apply.
-- [Tools, ReAct, and MCP](tools-react-and-mcp.md) — `CodeAct` and `RLM` use the same tool-wrapping machinery as `ReAct`.
+- [Tools and MCP](tools.md) — `CodeAct`, `RLM`, and ReAct use the same tool-wrapping machinery.
+- [ReAct and ReActV2](react.md) — the dedicated agent-loop comparison and migration plan.
- [RLM: exploring large contexts with code](rlm.md) — the deep dive on the experimental REPL-driven module summarized above.
- [Flex: Optimizable module code](flex.md) — the deep dive on the code-optimizable Flex module summarized above.
- [Settings and `context()`](settings-and-context.md) — how `Parallel` and `Module.batch` snapshot the active overrides into each worker.
diff --git a/docs/docs/diving-deeper/react.md b/docs/docs/diving-deeper/react.md
new file mode 100644
index 000000000..072cf6ba4
--- /dev/null
+++ b/docs/docs/diving-deeper/react.md
@@ -0,0 +1,215 @@
+# ReAct and ReActV2
+
+## Intent
+
+ReAct is DSPy's general-purpose tool-using agent loop: the language model reasons about a task, chooses tools, observes their results, and repeats until it can produce the signature's outputs.
+
+DSPy is transitioning between two implementations. `dspy.ReAct` is the current implementation. `dspy.ReActV2` is its experimental, structured-history replacement and will become the implementation behind the canonical `dspy.ReAct` name in DSPy 3.5. The `dspy.ReActV2` name will remain as a deprecated compatibility alias throughout the 3.5 release line and will be removed in DSPy 3.6.
+
+Read this page to prepare for that transition and understand what is changing: how each implementation stores and formats history, calls tools, finishes a run, and interacts with provider prompt caching. For defining tools or importing them from MCP, see [Tools and MCP](tools.md).
+
+## The transition from ReAct to ReActV2
+
+Both modules accept the same task signature, tool list, and iteration limit:
+
+```python
+import dspy
+
+def lookup(query: str) -> str:
+ """Look up information relevant to a query."""
+ return search_index(query)
+
+agent = dspy.ReActV2("question -> answer", tools=[lookup], max_iters=10)
+result = agent(question="What is DSPy?")
+```
+
+The execution models differ:
+
+| | `dspy.ReAct` | `dspy.ReActV2` |
+| --- | --- | --- |
+| Status | Current implementation through DSPy 3.4; adopts the ReActV2 implementation in 3.5 | Experimental name; becomes a deprecated alias for `dspy.ReAct` throughout 3.5 and is removed in 3.6 |
+| Stored history | Flat `trajectory` dictionary | Structured `dspy.History` events |
+| Model-facing history | Entire trajectory formatted into the current input | Prior user, assistant, and tool messages replayed as separate turns |
+| Tool selection | `next_tool_name` plus `next_tool_args` | `dspy.ToolCalls` |
+| Calls per model turn | One | One or more |
+| Completion | `finish`, then a separate extraction LM call | `submit` carries final typed outputs directly |
+| Returned diagnostics | `prediction.trajectory` | `prediction.history` and `prediction.termination_reason` |
+| Prompt caching | The changing trajectory is resent as one field | Stable prior messages remain a reusable prefix |
+
+For new agent work, use `dspy.ReActV2` now if you can accept an experimental API; it provides an early path to the execution model that will become `dspy.ReAct` in 3.5. Existing `dspy.ReAct` programs can remain on the current implementation until the upgrade, but should prepare for the history and output changes summarized below. Pin the DSPy version while using the experimental `ReActV2` name.
+
+## ReAct: trajectory-based execution
+
+### How history is stored
+
+ReAct builds one insertion-ordered `trajectory` dictionary. Every iteration appends four keys:
+
+```python
+{
+ "thought_0": "I should look up the release notes.",
+ "tool_name_0": "lookup",
+ "tool_args_0": {"query": "DSPy release notes"},
+ "observation_0": "...",
+}
+```
+
+The dictionary is returned as `prediction.trajectory`. It is execution state for this invocation, not a conversation object intended to be passed into a later invocation.
+
+### How history is formatted for the model
+
+Before every LM call, `ReAct._format_trajectory` creates a temporary signature from the trajectory keys and asks the active adapter to format it. `ChatAdapter` uses field markers, `JSONAdapter` uses JSON, and `XMLAdapter` uses tags. ReAct then supplies that formatted value as the `trajectory` input to its internal predictor.
+
+The trajectory is therefore stored structurally inside the loop but becomes one formatted input value at the model boundary. On every iteration the complete, now-longer trajectory is formatted again and sent with the original task inputs.
+
+If the request exceeds the context window, ReAct drops the oldest complete thought/tool/args/observation group and retries, up to three times. Override `truncate_trajectory` to implement another retention policy.
+
+### How tools are called
+
+The internal `dspy.Predict` produces `next_thought`, a `next_tool_name` constrained to the registered tool names, and a `next_tool_args` dictionary. ReAct executes exactly one selected `dspy.Tool` per iteration with keyword arguments.
+
+Tool exceptions are caught and stored as the next observation, allowing the model to recover on the following iteration. ReAct also registers a no-argument `finish` tool; selecting it ends the loop. `max_iters` provides a hard stop when the model never selects `finish`.
+
+### What happens after the loop
+
+Selecting `finish`, reaching `max_iters`, or encountering an unrecoverable model/context error ends navigation but does not directly produce the declared outputs. ReAct runs a separate `dspy.ChainOfThought` extractor over the original task inputs and formatted trajectory. The extractor synthesizes and types the signature's output fields. The returned prediction combines those fields with `trajectory`.
+
+This means a normal ReAct run has at least one additional LM call after its tool loop.
+
+### Prompt-caching behavior
+
+ReAct resends the growing trajectory as one newly formatted input on each iteration. The instructions and original task inputs may still form a cacheable prefix, but the trajectory-bearing user content changes each turn rather than being represented as appended assistant/tool messages. Providers cannot reuse the changing portion as effectively, and the separate extraction request has a different signature and prompt shape.
+
+## ReActV2: structured-history execution
+
+### How history is stored
+
+ReActV2 owns a `dspy.History`, whose `messages` list contains one structured event per loop turn. An event can contain:
+
+- Original signature inputs, included on the first new turn only.
+- `next_thought`, when the model returns one.
+- A `dspy.ToolCalls` object containing every requested call and its call ID.
+- Attached `ToolCallResults`, pairing each ID with the tool name, value, and error status.
+- The signature's final output fields when the turn successfully calls `submit`.
+
+Conceptually, a turn looks like:
+
+```python
+{
+ "question": "What is DSPy?", # first new turn only
+ "next_thought": "I should look it up.",
+ "tool_calls": dspy.ToolCalls(
+ tool_calls=[
+ dspy.ToolCalls.ToolCall(
+ id="call_123",
+ name="lookup",
+ args={"query": "DSPy"},
+ )
+ ],
+ tool_call_results=...,
+ ),
+}
+```
+
+The returned prediction exposes this object as `prediction.history`. Pass that `dspy.History`, or its serialized representation, back as `history=` to continue from an earlier run.
+
+### How history is formatted for the model
+
+The adapter turns each history event into multiple model messages rather than flattening all prior activity into one trajectory field.
+
+With native function calling enabled, a completed turn is replayed as:
+
+```text
+user original input fields, when present
+assistant next_thought plus native tool_calls
+tool one result message per call, matched by tool_call_id
+```
+
+Call IDs are preserved from the provider. ReActV2 generates deterministic IDs when non-native model output does not supply them.
+
+With native function calling disabled, history remains structured inside DSPy, but the adapter renders the assistant fields in its normal text/JSON/XML format and renders tool results as a following user message. This lets ReActV2 work with models that do not expose a native tool API while retaining one internal history representation.
+
+Native calling is an adapter setting:
+
+```python
+adapter = dspy.ChatAdapter(
+ use_native_function_calling=True,
+ parallel_tool_calls=True,
+)
+
+with dspy.context(adapter=adapter):
+ result = agent(question="Compare two releases.")
+```
+
+Provider support varies. `JSONAdapter` enables native function calling by default; `ChatAdapter` requires the explicit setting shown above.
+
+### How tools are called
+
+The internal predictor returns `dspy.ToolCalls`, so one model turn can request multiple tools. ReActV2 preserves each requested call/result pair by ID. The `parallel_tool_calls` adapter option asks a capable provider to generate multiple independent calls in the same turn; ReActV2 currently executes the returned calls one after another in Python.
+
+Callables supplied to the constructor are converted to `dspy.Tool`. Unknown tool names and execution exceptions become error results in history so the next model turn can respond to them.
+
+ReActV2 reserves `submit` as an internal tool. Its argument schema is generated from the original signature's output fields, so final values travel through the same structured calling path as every other action.
+
+### What happens after each turn and at termination
+
+After executing all calls in a turn, ReActV2 attaches their results to `ToolCalls`, appends the event to history, and invokes the model again with no duplicate copy of the original inputs. If one of the calls successfully invokes `submit`, ReActV2 returns its typed fields immediately with `termination_reason="submit"`; there is no separate extraction module.
+
+If the loop reaches `max_iters`, returns no calls, fails to parse, or exceeds the context window, ReActV2 makes one final LM call requesting `submit`. With native function calling enabled, it sets `tool_choice` to `submit`, so the provider enforces that choice. In non-native mode, the adapter removes `tool_choice` and requests `submit` through the formatted prompt instead, so structured submission is not guaranteed. A successful fallback returns `termination_reason="forced_submit"`. If that attempt fails, the prediction still returns its history and a termination reason describing why the normal loop stopped, but it may not contain the declared output fields.
+
+Unlike ReAct, ReActV2 does not currently truncate old history events on context overflow.
+
+### Prompt-caching behavior
+
+Structured history makes each completed turn an append-only message group. On the next request, the system instructions and all earlier user/assistant/tool messages remain a stable prefix; only the newest result and request are appended. Providers with prompt caching can therefore reuse more of the prior request instead of reprocessing one ever-growing, newly formatted trajectory value.
+
+For Anthropic models, enable provider-side prompt caching on the LM with LiteLLM's cache-control injection points:
+
+```python
+lm = dspy.LM(
+ "anthropic/claude-sonnet-4-5-20250929",
+ cache_control_injection_points=[
+ {"location": "message", "role": "system"},
+ {"location": "message", "index": -1},
+ ],
+)
+
+with dspy.context(lm=lm):
+ result = agent(question="What is DSPy?")
+```
+
+The first injection point caches the stable system instructions. The second places a checkpoint on the trailing turn, allowing Anthropic to reuse the preceding conversation prefix as ReActV2 appends history. Anthropic only caches prefixes that meet the model's minimum token count, and its default ephemeral cache has a limited lifetime. See [Using Provider-Side Prompt Caching](../tutorials/cache/index.md#using-provider-side-prompt-caching) for the general DSPy setup and the [LiteLLM prompt-caching documentation](https://docs.litellm.ai/docs/tutorials/prompt_caching#configuration) for provider details.
+
+Native tool replay gives the cleanest provider-visible structure, but non-native mode still benefits from stable multi-turn history. Internal testing has seen cost reductions of up to 50% on some tasks. Actual savings depend on the provider's cache policy, model, request shape, and the size of tool results; they are not guaranteed for every workload.
+
+## Replacement and migration plan
+
+ReActV2 is a temporary experimental name, not the start of two permanent ReAct APIs. Its structured-history implementation will replace the current `dspy.ReAct` implementation in DSPy 3.5. The canonical public name will remain `dspy.ReAct`.
+
+To avoid forcing users of the experimental name to rename immediately, `dspy.ReActV2` will remain available as a deprecated compatibility alias throughout the DSPy 3.5 release line. Using the alias will warn users to migrate to `dspy.ReAct`; the alias will be removed in DSPy 3.6. In other words, code can move from `dspy.ReActV2(...)` to `dspy.ReAct(...)` any time after upgrading to 3.5, and should do so before upgrading to 3.6.
+
+Existing `dspy.ReAct` programs do not need to change before upgrading to DSPy 3.5. Before that upgrade, review code that depends on `prediction.trajectory`, a separate extractor predictor, one tool call per turn, or custom trajectory truncation. Those behaviors are replaced by `prediction.history`, direct `submit` outputs, multiple calls per turn, and structured message replay.
+
+## API summary
+
+**`dspy.ReAct(signature, tools, max_iters=20)`**
+Runs the stable trajectory-based loop and a final extraction pass.
+
+**`ReAct.forward(**inputs)` / `ReAct.aforward(**inputs)`**
+Runs the synchronous or asynchronous loop and returns output fields plus `trajectory`.
+
+**`ReAct.truncate_trajectory(trajectory)`**
+Drops the oldest complete tool-call group after a context-window error. Override to change the policy.
+
+**`dspy.ReActV2(signature, tools, max_iters=20)`**
+Runs the experimental structured-history loop and reserves `submit` for final outputs.
+
+**`ReActV2.forward(history=None, max_iters=None, **inputs)`**
+Accepts optional continuation history and a per-call iteration override. Returns `history` and `termination_reason` alongside outputs when submission succeeds.
+
+## Cross-links
+
+- [Tools and MCP](tools.md) — defining, wrapping, validating, and importing the tools these agents call.
+- [Adapters: how signatures become prompts](adapters.md) — the formatting boundary for `History`, `ToolCalls`, and native function calling.
+- [Modules: composing your own](modules.md) — tracing, state, and composition shared by both implementations.
+- [`dspy.ReAct` API reference](../api/modules/ReAct.md)
+- [`dspy.ReActV2` API reference](../api/modules/ReActV2.md)
diff --git a/docs/docs/diving-deeper/rlm.md b/docs/docs/diving-deeper/rlm.md
index e1ca0bcf5..ceb0d96a6 100644
--- a/docs/docs/diving-deeper/rlm.md
+++ b/docs/docs/diving-deeper/rlm.md
@@ -109,5 +109,5 @@ A property returning the user-provided tools as a name-to-`Tool` dict, excluding
## Cross-links
- [Built-in module variants](built-in-module-variants.md) — where RLM sits among the other non-`Predict` modules.
-- [Tools, ReAct, and MCP](tools-react-and-mcp.md) — the tool-wrapping machinery RLM reuses.
+- [Tools and MCP](tools.md) — the tool-wrapping machinery RLM reuses.
- [`dspy.RLM` API reference](../api/modules/RLM.md) — full parameter table, built-in tool list, and worked examples.
diff --git a/docs/docs/diving-deeper/tools-react-and-mcp.md b/docs/docs/diving-deeper/tools-react-and-mcp.md
deleted file mode 100644
index 42a8cfe32..000000000
--- a/docs/docs/diving-deeper/tools-react-and-mcp.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Tools, ReAct, and MCP
-
-## Intent
-
-A DSPy program “uses a tool” when an LM picks a named Python function from a list, supplies arguments to it, sees the result, and reasons over the result on the next turn. `dspy.Tool` is the wrapper that makes a plain callable usable this way; `dspy.ReAct` is the module that runs the thought / tool / observation loop; and `dspy.utils.mcp` (with `Tool.from_mcp_tool`) bridges remote MCP servers into the same interface.
-
-Read this when you want to give your program tools, when you want to understand the ReAct loop’s mechanics (trajectory, finish step, truncation), or when you want to attach an MCP server’s tools to a DSPy program.
-
-## Design decisions
-
-### 1. A `Tool` is a Pydantic model over a callable, not a wrapper class
-
-`Tool` is a `dspy.Type` (which is itself a `pydantic.BaseModel`), and `func`, `name`, `desc`, `args`, `arg_types`, and `arg_desc` are model fields. This matters because the same `Tool` instance is what adapters read to render the prompt, what `ToolCall.execute` resolves by name, and what serializes when a program with tools is saved. Being a Pydantic model plugs into all of that without bespoke code.
-
-### 2. Schema, types, and description are introspected by default
-
-The constructor walks `inspect.signature(func)` and `get_type_hints(func)` to build the JSON schema (`args`), the type-hint dict (`arg_types`), and the description (from the docstring). Pydantic models in the type hints are inlined: their JSON schemas replace the `$ref` paths so the LM sees a flat schema. Explicit values you pass to the constructor override inference, field by field — hand-tune one and the rest stay inferred.
-
-### 3. Async vs sync is detected at call time, not at construction
-
-`Tool.__call__` invokes `func(**kwargs)` and checks the result with `asyncio.iscoroutine`. The check lives at call time because the same `func` could be wrapped, decorated, or be a generic callable whose async-ness isn’t visible from the outside. A runtime check is the only signal that always works.
-
-### 4. `allow_tool_async_sync_conversion` is the opt-in bridge
-
-An async tool called from a sync entry point raises by default. Setting `settings.allow_tool_async_sync_conversion=True` (or scoping it via `dspy.context`) makes `__call__` run the coroutine through `asyncio.run` or the active loop’s `run_until_complete`. Opt-in matters because sync-from-async conversion is a deadlock risk inside many runtime environments; consent is explicit.
-
-### 5. ReAct’s loop is thought → tool name → tool args → observation
-
-On each iteration the LM produces three output fields: `next_thought` (free text), `next_tool_name` (a `Literal` over the registered tools), and `next_tool_args` (a `dict`). ReAct looks up the tool, calls it with `next_tool_args` as kwargs, appends four trajectory entries (`thought_i`, `tool_name_i`, `tool_args_i`, `observation_i`), and loops. The `Literal` type on `next_tool_name` means the adapter constrains the LM to known tool names, not free-text guesses.
-
-### 6. The `finish` tool is auto-added and is how the loop terminates
-
-ReAct registers an extra `finish` tool — a no-arg callable — and the loop exits when the LM selects it. Making termination a tool rather than a special-cased flag keeps the LM’s choice uniform: pick from the same list every turn, no extra parsing logic. A separate `max_iters` cap is the hard upper bound for cases where the LM never selects `finish`.
-
-### 7. The trajectory is a dict; the adapter decides how it’s rendered
-
-`ReAct._format_trajectory` builds a throwaway signature with one field per trajectory key, then asks the active adapter to render it via `format_user_message_content`. With `ChatAdapter` the trajectory comes out with `[[ ## thought_i ## ]]` markers; with `JSONAdapter` it comes out as a JSON object; with `XMLAdapter` it comes out as tags. ReAct never hand-formats — the adapter does, and the format stays consistent with the rest of the prompt.
-
-### 8. Tool execution errors become observations, not crashes
-
-A raised exception from a tool is caught inside `forward` and recorded as `observation_i = "Execution error in <tool>: <traceback>"`. The LM sees the error text on the next iteration and can react to it. Surfacing failures into the LM’s reasoning loop, rather than terminating the program, is the default an agent expects — the model is supposed to recover.
-
-### 9. A separate extractor module produces the declared outputs
-
-After the loop ends, ReAct hands the trajectory to a `dspy.ChainOfThought` over a fallback signature that includes the original output fields plus a `trajectory` input. The extractor’s job is to read the trajectory and produce the signature’s declared outputs in their correct types. Decoupling navigation (the loop) from extraction (the typed answer) makes both halves easier to optimize and easier to debug.
-
-### 10. Trajectory truncation drops the oldest tool call on context overflow
-
-When `_call_with_potential_trajectory_truncation` catches a `ContextWindowExceededError`, it calls `truncate_trajectory`, which removes the first four keys (one full tool-call’s worth) and retries — up to three rounds. The heuristic: recent observations are most informative for the next step, older context can go. Override `truncate_trajectory` in a subclass to keep summaries, slide a window, or anything else.
-
-### 11. MCP tools are always async; `Tool.from_mcp_tool` is the canonical bridge
-
-`convert_mcp_tool` builds an async `func` that awaits `session.call_tool(name, args)`. Sync access goes through `acall` or the `allow_tool_async_sync_conversion` switch. MCP is async-only because the underlying `mcp.ClientSession` is built on `anyio` task groups and exposes an async API; bridging it sync would block the I/O loop.
-
-### 12. Native function calling is opt-in on adapters, not on tools
-
-Whether the LM gets a `tools=` payload (OpenAI-style function calling) or a text-rendered prompt is the adapter’s decision, not the tool’s. `Tool.format_as_litellm_function_call()` produces the function-calling descriptor; `ChatAdapter`‘s `use_native_function_calling=True` constructor flag opts in. The split exists because the same `Tool` object should work whether or not the LM supports native tool calling — only the wire format changes.
-
-## API walkthrough
-
-Grouped by what you’re trying to do.
-
-### Wrapping a callable as a tool
-
-**`dspy.Tool(func, name=None, desc=None, args=None, arg_types=None, arg_desc=None)`**
-A Pydantic model with `func` as its primary field. The constructor calls `_parse_function`, which walks the callable’s signature with `inspect.signature` and `get_type_hints`, derives the JSON schema with `pydantic.TypeAdapter`, and resolves `$ref` paths into inline schemas via `_resolve_json_schema_reference`. Explicit kwargs take precedence: pass `args={...}` and the inference for `args` is skipped, but `arg_types` and `desc` still come from inspection.
-
-**`Tool.__call__(**kwargs)` / `Tool.acall(**kwargs)`**
-Both go through `_validate_and_parse_args`, which JSON-schema-validates each kwarg then wraps it in a one-field Pydantic model to coerce nested types like `list[list[MyModel]]`. `__call__` runs the function and inspects the return: if it’s a coroutine, behavior depends on `settings.allow_tool_async_sync_conversion`. `acall` awaits a coroutine return or returns the synchronous value directly — so the async path tolerates sync tools.
-
-**`Tool.format_as_litellm_function_call()`** → `dict`
-Returns the OpenAI/LiteLLM tool descriptor: `{"type": "function", "function": {"name", "description", "parameters": {"type": "object", "properties": args, "required": list(args)}}}`. Every declared arg is marked `required` — Pydantic-level defaults aren’t surfaced as optional in the function descriptor.
-
-**`Tool.from_mcp_tool(session, tool)`** → `Tool`
-Class method. Delegates to `dspy.utils.mcp.convert_mcp_tool`. Takes a live `mcp.ClientSession` and an `mcp.types.Tool` and returns an async DSPy tool wired to that session.
-
-**`Tool.from_langchain(tool)`** → `Tool`
-Class method. Wraps a LangChain `BaseTool` so it can be passed to DSPy modules that accept a `tools=` list. Implementation lives in `dspy.utils.langchain_tool`.
-
-### The ReAct module
-
-**`dspy.ReAct(signature, tools, max_iters=20)`**
-On construction, ReAct coerces every entry in `tools` to a `dspy.Tool`, registers the auto-generated `finish` tool, and builds two internal modules: a `dspy.Predict` over a signature whose outputs are `next_thought`, `next_tool_name` (a `Literal` over the tool names), and `next_tool_args` (a `dict`); and a `dspy.ChainOfThought` extractor whose signature contains the original output fields plus a `trajectory` input. The system instructions are assembled with a numbered tool list and embedded into the predict’s signature.
-
-**`ReAct.forward(**inputs)` / `ReAct.aforward(**inputs)`**
-Runs the loop described above. Each iteration formats the trajectory through the current adapter and passes it as the `trajectory` input to the predict; tool exceptions are caught and stringified into the trajectory; the loop exits when the LM picks `finish` or `max_iters` is reached. The extractor then reads the final trajectory and produces the declared outputs. Returns a `dspy.Prediction` carrying both the trajectory and the extracted fields.
-
-**`ReAct.truncate_trajectory(trajectory)`**
-Removes the first four keys of the trajectory dict — one complete tool call. Called from `_call_with_potential_trajectory_truncation` after a `ContextWindowExceededError`, with up to three rounds before the module raises. Override to keep summaries, slide a window, or implement any other policy.
-
-### Tool calls in the LM response
-
-When an adapter supports native function calling, the LM’s output contains structured tool-call objects rather than text markers. These types model that surface.
-
-**`dspy.ToolCalls(tool_calls: list[ToolCall])`**
-A `pydantic.BaseModel` whose single field is a list of `ToolCall` items. A validator accepts several input shapes — a list of dicts, a `{"tool_calls": [...]}` dict, or a single `{"name", "args"}` dict — so adapters parsing from different providers can route through the same constructor.
-
-**`ToolCalls.ToolCall(name, args)`**
-A single named function call with its arguments. Nested class, accessible as `dspy.ToolCalls.ToolCall`.
-
-**`ToolCall.execute(functions=None)`** → `Any`
-Looks up the named function in a `{name: func}` dict, a list of `Tool` objects, or — when `functions=None` — the caller’s locals and globals (resolved via `inspect.currentframe().f_back`). Raises `ValueError` when the name isn’t found and `RuntimeError` when the underlying function throws.
-
-**`ToolCalls.from_dict_list(tool_calls_dicts)`** → `ToolCalls`
-Constructor helper. Builds a `ToolCalls` from a list of `{"name", "args"}` dicts — the shape adapters produce from a provider’s native response.
-
-### MCP bridge
-
-**`dspy.utils.mcp.convert_mcp_tool(session, tool)`** → `Tool`
-Builds a `Tool` whose `func` is an `async def` closure: it awaits `session.call_tool(tool.name, arguments=kwargs)` and unpacks the result. The bridge supports the camelCase fields in mcp SDK v1 and their snake_case replacements in v2. An error result raises `RuntimeError`; text and non-text content retain their existing behavior. The tool’s input schema is mapped to DSPy’s `args`/`arg_types`/`arg_desc` via `convert_input_schema_to_tool_args`.
-
-**`dspy.utils.mcp.convert_input_schema_to_tool_args(schema)`** → `(args, arg_types, arg_desc)`
-Walks an MCP-style JSON schema and produces the three dicts a `Tool` needs. Resolves `$defs`, picks up `description` fields as `arg_desc`, and translates JSON-schema types to Python types via a `_TYPE_MAPPING` table. Exported in case callers want to write their own bridge against a non-MCP protocol with similar JSON-schema arguments.
-
-## Cross-links
-
-- [Adapters: how signatures become prompts](adapters.md) — where `Tool` and `ToolCalls` are formatted onto the wire, and where native function calling is opted into.
-- [Built-in module variants](built-in-module-variants.md) — `CodeAct` and `RLM` use the same tool-wrapping machinery in a code-execution context.
-- [RLM: exploring large contexts with code](rlm.md) — how RLM exposes built-in `llm_query` tools and your own tools inside its sandbox.
-- [Modules: composing your own](modules.md) — `ReAct` is a `Module`, so trace, history, and `set_lm` all apply.
diff --git a/docs/docs/diving-deeper/tools.md b/docs/docs/diving-deeper/tools.md
new file mode 100644
index 000000000..574e8082b
--- /dev/null
+++ b/docs/docs/diving-deeper/tools.md
@@ -0,0 +1,135 @@
+# Tools and MCP
+
+## Intent
+
+A tool lets a DSPy program call Python code chosen by a language model. The model sees a name, description, and argument schema; it selects the tool and supplies arguments; DSPy executes the callable and makes the result available to the program.
+
+Tools are a shared DSPy primitive, not a ReAct-specific feature. `dspy.ReAct` and `dspy.ReActV2` use them in agent loops, `dspy.RLM` exposes them inside its interpreter, `dspy.Flex` can wire them into optimized programs, and adapters use the same tool schemas for native provider function calling. `dspy.utils.mcp` bridges remote MCP tools into this interface.
+
+Read this page when you want to define, wrap, validate, or import tools. For the agent loop that decides when to call them, see [ReAct and ReActV2](react.md).
+
+## Defining a tool
+
+A DSPy tool can start as an ordinary typed Python function:
+
+```python
+def search(query: str, limit: int = 5) -> list[str]:
+ """Search the knowledge base for relevant passages."""
+ return index.search(query, limit=limit)
+```
+
+Modules that accept `tools=` convert callables to `dspy.Tool` automatically:
+
+```python
+agent = dspy.ReAct("question -> answer", tools=[search])
+```
+
+Wrap the function explicitly when you need to inspect or override its metadata:
+
+```python
+search_tool = dspy.Tool(
+ search,
+ name="search_docs",
+ desc="Search the product documentation.",
+)
+```
+
+Good names, descriptions, parameter names, and type hints matter: they are the interface the model uses to decide whether and how to call the function.
+
+## How `dspy.Tool` works
+
+### Schema and metadata are inferred
+
+`dspy.Tool` stores the callable in `func` and derives `name`, `desc`, `args`, `arg_types`, and `arg_desc` from the function signature, type hints, and docstring. Pydantic annotations are converted to JSON schema and local `$ref` paths are resolved so the model receives a complete argument shape. Explicit constructor values override inference field by field.
+
+### Arguments are validated before execution
+
+`Tool.__call__(**kwargs)` and `Tool.acall(**kwargs)` validate arguments against the JSON schema and use Pydantic to coerce nested annotated values. The synchronous path calls the function directly. The asynchronous path awaits coroutine results and also accepts ordinary synchronous functions.
+
+Calling an asynchronous tool from synchronous code raises by default. Opt into conversion only when your runtime permits it:
+
+```python
+async_search_tool = dspy.Tool(async_search)
+
+with dspy.context(allow_tool_async_sync_conversion=True):
+ result = async_search_tool(query="DSPy")
+```
+
+The conversion is explicit because driving an async tool from an existing event loop can deadlock in some environments.
+
+### Adapters choose text or native formatting
+
+The tool itself is provider-neutral. An adapter decides whether to render its schema into text or send it through a provider's native function-calling API. For example:
+
+```python
+adapter = dspy.ChatAdapter(use_native_function_calling=True)
+
+with dspy.context(adapter=adapter):
+ result = agent(question="What changed in DSPy 3.3?")
+```
+
+When native calling is active and the LM supports it, the adapter converts each tool with `Tool.format_as_litellm_function_call()` and sends the resulting descriptors in the LM request. Otherwise, it keeps tool selection in DSPy's normal adapter-formatted fields. The same `Tool` works in either mode.
+
+## Structured tool calls and results
+
+`dspy.ToolCalls` represents model-requested calls independently of any provider's wire format. Each `ToolCalls.ToolCall` carries an optional provider call ID, a tool name, and an argument dictionary:
+
+```python
+calls = dspy.ToolCalls.from_dict_list([
+ {"name": "search", "args": {"query": "DSPy tools"}},
+])
+```
+
+The validator accepts DSPy's `{name, args}` shape and common provider-style function-call shapes. Adapters handle conversion at the provider boundary; application code can keep using the DSPy representation.
+
+Tool results are paired to calls by ID, name, value, and an error flag in `ToolCallResults`. This pairing lets adapters replay a native assistant tool call followed by the matching provider `tool` message. It also lets an agent report an unknown tool or execution exception to the model as a result instead of losing the failed turn.
+
+## MCP tools
+
+MCP servers publish tools with JSON schemas. `dspy.Tool.from_mcp_tool(session, tool)` is the canonical bridge from a live `mcp.ClientSession` and an MCP tool definition to a DSPy tool:
+
+```python
+dspy_tool = dspy.Tool.from_mcp_tool(session, mcp_tool)
+```
+
+The bridge:
+
+1. Converts the MCP input schema into DSPy's `args`, `arg_types`, and `arg_desc`.
+2. Creates an async callable that invokes `session.call_tool(...)`.
+3. Unpacks MCP text content into a string or list and preserves non-text content.
+4. Raises an execution error when the MCP response has `isError=True`.
+
+The bridge supports both the camelCase result fields in MCP SDK v1 and their snake_case replacements in v2 without changing text or non-text result behavior.
+
+MCP tools are asynchronous because `mcp.ClientSession` is asynchronous. Use a module's async entry point, such as `acall`, or explicitly enable async-to-sync conversion when appropriate.
+
+`Tool.from_langchain(tool)` provides the equivalent bridge for LangChain `BaseTool` objects.
+
+## API walkthrough
+
+**`dspy.Tool(func, name=None, desc=None, args=None, arg_types=None, arg_desc=None)`**
+Wraps a callable and infers any metadata not supplied explicitly.
+
+**`Tool.__call__(**kwargs)` / `Tool.acall(**kwargs)`**
+Validates, coerces, and executes tool arguments through synchronous or asynchronous entry points.
+
+**`Tool.format_as_litellm_function_call()`** → `dict`
+Returns the OpenAI/LiteLLM-style function descriptor used by adapters for native calling.
+
+**`Tool.from_mcp_tool(session, tool)`** → `Tool`
+Wraps a remote MCP tool as an asynchronous DSPy tool.
+
+**`Tool.from_langchain(tool)`** → `Tool`
+Wraps a LangChain tool in the same DSPy interface.
+
+**`dspy.ToolCalls(tool_calls=[...])`**
+Stores one or more requested calls in a provider-neutral form.
+
+## Cross-links
+
+- [ReAct and ReActV2](react.md) — how DSPy's agent modules choose, execute, record, and replay tools.
+- [Adapters: how signatures become prompts](adapters.md) — where tool schemas and `ToolCalls` become provider requests and responses.
+- [RLM: exploring large contexts with code](rlm.md) — how RLM makes supplied tools callable inside its sandbox.
+- [Built-in module variants](built-in-module-variants.md) — other modules that consume tools.
+- [`dspy.Tool` API reference](../api/primitives/Tool.md)
+- [`dspy.ToolCalls` API reference](../api/primitives/ToolCalls.md)
diff --git a/docs/docs/getting-started/composing-modules.md b/docs/docs/getting-started/composing-modules.md
index b2d080c33..ef5e568be 100644
--- a/docs/docs/getting-started/composing-modules.md
+++ b/docs/docs/getting-started/composing-modules.md
@@ -2,7 +2,7 @@
Switching to `dspy.ReAct` turned our single-step program into a multi-step agent. It’s a significant change, but `ReAct` itself is simple to understand.
-Inside [`dspy.ReAct`](../diving-deeper/tools-react-and-mcp.md), other DSPy modules are composed together. Each step where the model considers its inputs and picks the next tool is a `dspy.Predict` module. A bit of code manages the control flow, looping through `Predict` calls until the model calls `finish` or hits `max_iters`. The synthesis step that follows, where the model assembles the answer from everything it’s learned, is a `ChainOfThought` module.
+Inside [`dspy.ReAct`](../diving-deeper/react.md), other DSPy modules are composed together. Each step where the model considers its inputs and picks the next tool is a `dspy.Predict` module. A bit of code manages the control flow, looping through `Predict` calls until the model calls `finish` or hits `max_iters`. The synthesis step that follows, where the model assembles the answer from everything it’s learned, is a `ChainOfThought` module.
Modules are modular. We can compose them together and they just *work*.
diff --git a/docs/docs/getting-started/react-and-tools.md b/docs/docs/getting-started/react-and-tools.md
index 3e7f60919..e72df9301 100644
--- a/docs/docs/getting-started/react-and-tools.md
+++ b/docs/docs/getting-started/react-and-tools.md
@@ -92,7 +92,10 @@ for step, value in result.trajectory.items():
print(f"{step}: {value}")
```
-For tool authoring patterns, MCP integration, and trajectory debugging, see [Tools, ReAct, and MCP](../diving-deeper/tools-react-and-mcp.md).
+For tool authoring patterns and MCP integration, see [Tools and MCP](../diving-deeper/tools.md). For the ReAct loop's execution model and trajectory debugging, see [ReAct and ReActV2](../diving-deeper/react.md).
+
+!!! note "Experimental: ReActV2"
+ `dspy.ReActV2` is the experimental, structured-history replacement for the current ReAct implementation. It will become `dspy.ReAct` in DSPy 3.5, bringing native multi-turn and parallel tool calls and improved prompt-cache reuse. The `dspy.ReActV2` name will remain as a deprecated compatibility alias throughout 3.5 and will be removed in 3.6. See [The transition from ReAct to ReActV2](../diving-deeper/react.md#the-transition-from-react-to-reactv2).
---
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 9b20f9c42..e05869553 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -29,7 +29,8 @@ nav:
- Built-in module variants: diving-deeper/built-in-module-variants.md
- "RLM: exploring large contexts with code": diving-deeper/rlm.md
- "Flex: optimizable module code": diving-deeper/flex.md
- - "Tools, ReAct, and MCP": diving-deeper/tools-react-and-mcp.md
+ - Tools and MCP: diving-deeper/tools.md
+ - ReAct and ReActV2: diving-deeper/react.md
- Metrics and evaluation: diving-deeper/metrics-and-evaluation.md
- "Optimizers: choosing one": diving-deeper/choosing-an-optimizer.md
- GEPA in depth: diving-deeper/gepa-in-depth.md
@@ -136,6 +137,7 @@ nav:
- Predict: api/modules/Predict.md
- ProgramOfThought: api/modules/ProgramOfThought.md
- ReAct: api/modules/ReAct.md
+ - ReActV2: api/modules/ReActV2.md
- Refine: api/modules/Refine.md
- RLM: api/modules/RLM.md
- Optimizers:
@@ -283,6 +285,8 @@ plugins:
"deep-dive/optimizers/miprov2.md": "api/optimizers/MIPROv2.md"
"api/optimizers/GEPA/index.md": "api/optimizers/GEPA/overview.md"
+ "diving-deeper/tools-react-and-mcp.md": "diving-deeper/react.md"
+
"docs/quick-start/getting-started-01.md": "tutorials/rag/index.ipynb"
"docs/quick-start/getting-started-02.md": "tutorials/rag/index.ipynb"
"quick-start/getting-started-01.md": "tutorials/rag/index.ipynb"
@@ -384,4 +388,4 @@ markdown_extensions:
emoji_generator: !!python/name:material.extensions.emoji.to_svg
copyright: |
- &copy; 2026 <a href="https://github.com/stanfordnlp" target="_blank" rel="noopener">DSPy</a>
\ No newline at end of file
+ &copy; 2026 <a href="https://github.com/stanfordnlp" target="_blank" rel="noopener">DSPy</a>
diff --git a/docs/scripts/generate_api_docs.py b/docs/scripts/generate_api_docs.py
index de2e88365..f9c085201 100644
--- a/docs/scripts/generate_api_docs.py
+++ b/docs/scripts/generate_api_docs.py
@@ -37,6 +37,7 @@ API_MAPPING = {
dspy.Predict,
dspy.ChainOfThought,
dspy.ReAct,
+ dspy.ReActV2,
dspy.ProgramOfThought,
dspy.MultiChainComparison,
dspy.Parallel,