DSPy: The framework for programming—not prompting—language models
Python
feat(dspy): ReActV2 show the agent its remaining turn budget each turn (#10662)
Drew Breunigc7e9752debcc
diff --git a/docs/docs/diving-deeper/react.md b/docs/docs/diving-deeper/react.mdindex 072cf6ba4..8bcabe92b 100644--- a/docs/docs/diving-deeper/react.md+++ b/docs/docs/diving-deeper/react.md@@ -158,6 +158,12 @@ If the loop reaches `max_iters`, returns no calls, fails to parse, or exceeds thUnlike ReAct, ReActV2 does not currently truncate old history events on context overflow.+### Turn budget++ReActV2 always tells the model how many turns it has. Every LM call contains a `turn_budget` input that details the current turn and how many turns remain before the model must submit. Its value reads, for example, `Turn 3 of 10 (7 more after this one).`. The count follows the effective `max_iters`, including a per-call override. The forced final call shows ``No turns remain. Call `submit` now with your final outputs.``++Showing an agent its remaining budget follows [Budget-Aware Tool-Use Enables Effective Agent Scaling](https://arxiv.org/abs/2511.17006), where a per-step budget status let ReAct agents keep improving with larger tool budgets at lower cost.+### Prompt-caching behaviorStructured 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.diff --git a/dspy/predict/react_v2.py b/dspy/predict/react_v2.pyindex eb5cecbad..2888e4dbd 100644--- a/dspy/predict/react_v2.py+++ b/dspy/predict/react_v2.py@@ -22,8 +22,14 @@ _RESERVED_PREDICTION_KEYS = frozenset({"history", "termination_reason"})# Internal input field names ReActV2 injects into its inner Predict signature. A user# input with one of these names would be silently overwritten by `_make_react_signature`-# and popped out of the caller's kwargs by `forward`/`aforward`, so it must be rejected.-_RESERVED_INPUT_KEYS = frozenset({"history", "tools"})+# and replaced or popped out of the caller's kwargs by `forward`/`aforward`, so it must be rejected.+_RESERVED_INPUT_KEYS = frozenset({"history", "tools", "turn_budget"})++# Per-turn input that tells the model where it is in its turn budget. Each turn's value is+# stored in that turn's history event, so replay rebuilds the exact request that was sent and+# every request stays a prefix of the next one for provider prompt caching.+_TURN_BUDGET_FIELD = "turn_budget"+_FINAL_TURN_BUDGET = "No turns remain. Call `submit` now with your final outputs."if TYPE_CHECKING:from dspy.signatures.signature import Signature@@ -41,7 +47,8 @@ class ReActV2(Module):Args:signature: The signature defining the agent's inputs and outputs.tools: Functions, callable objects, or ``dspy.Tool`` instances available to the agent.- max_iters: Maximum number of tool-calling turns before a final submit attempt.+ max_iters: Maximum number of tool-calling turns before a final submit attempt. Every call+ shows the model its current turn and how many remain."""def __init__(self, signature: type[Signature], tools: list[Callable | Tool], max_iters: int = 20):@@ -62,7 +69,7 @@ class ReActV2(Module):names = ", ".join(f"`{name}`" for name in sorted(reserved_inputs))raise ValueError(f"Input field name(s) {names} are reserved by ReActV2 for its internal "- "conversation history and tool list. Rename these input fields on your signature."+ "conversation history, tool list, and turn budget. Rename these input fields on your signature.")user_tools = [tool if isinstance(tool, Tool) else Tool(tool) for tool in tools]@@ -106,6 +113,10 @@ class ReActV2(Module):fields["history"] = (dspy.History, dspy.InputField())fields["tools"] = (list[dspy.Tool], dspy.InputField())+ fields[_TURN_BUDGET_FIELD] = (+ str,+ dspy.InputField(desc="Your current turn and how many turns remain before you must submit."),+ )fields["next_thought"] = (dspy.Reasoning, dspy.OutputField())fields["tool_calls"] = (dspy.ToolCalls, dspy.OutputField())@@ -131,11 +142,12 @@ class ReActV2(Module):break_reason = "max_iters"for turn_index in range(max_iters):+ turn_inputs = {**pending_inputs, **self._turn_budget_inputs(turn_index, max_iters)}try:pred = self.react(history=history,tools=list(self.tools.values()),- **pending_inputs,+ **turn_inputs,)tool_calls = _coerce_tool_calls(getattr(pred, "tool_calls", None))except (AdapterParseError, ValueError) as err:@@ -153,7 +165,7 @@ class ReActV2(Module):tool_calls = _ensure_tool_call_ids(tool_calls, turn_index)tool_call_results, final_outputs = self._execute_tool_calls(tool_calls)- event = self._history_event(pending_inputs, pred, tool_calls, tool_call_results)+ event = self._history_event(turn_inputs, pred, tool_calls, tool_call_results)if final_outputs is not None:event.update(final_outputs)_append_history_event(history, event)@@ -171,11 +183,12 @@ class ReActV2(Module):break_reason = "max_iters"for turn_index in range(max_iters):+ turn_inputs = {**pending_inputs, **self._turn_budget_inputs(turn_index, max_iters)}try:pred = await self.react.acall(history=history,tools=list(self.tools.values()),- **pending_inputs,+ **turn_inputs,)tool_calls = _coerce_tool_calls(getattr(pred, "tool_calls", None))except (AdapterParseError, ValueError) as err:@@ -193,7 +206,7 @@ class ReActV2(Module):tool_calls = _ensure_tool_call_ids(tool_calls, turn_index)tool_call_results, final_outputs = await self._aexecute_tool_calls(tool_calls)- event = self._history_event(pending_inputs, pred, tool_calls, tool_call_results)+ event = self._history_event(turn_inputs, pred, tool_calls, tool_call_results)if final_outputs is not None:event.update(final_outputs)_append_history_event(history, event)@@ -204,6 +217,18 @@ class ReActV2(Module):return await self._aforced_submit(history, pending_inputs, break_reason, max_iters)+ def _turn_budget_inputs(self, turn_index: int | None, max_iters: int | None) -> dict[str, str]:+ """Build the per-call turn budget input; ``turn_index=None`` marks the forced final submit."""+ # Agents pickled before this field existed skip `__init__` and keep their old signature.+ if _TURN_BUDGET_FIELD not in self.react.signature.input_fields:+ return {}+ if turn_index is None:+ return {_TURN_BUDGET_FIELD: _FINAL_TURN_BUDGET}+ turn = turn_index + 1+ remaining = max_iters - turn+ after = "this is your last turn" if remaining == 0 else f"{remaining} more after this one"+ return {_TURN_BUDGET_FIELD: f"Turn {turn} of {max_iters} ({after})."}+def _execute_tool_calls(self, tool_calls: ToolCalls) -> tuple[ToolCallResults, dict[str, Any] | None]:values = []is_errors = []@@ -273,6 +298,7 @@ class ReActV2(Module):break_reason: str,turn_index: int,) -> Prediction:+ turn_inputs = {**pending_inputs, **self._turn_budget_inputs(None, None)}try:pred = self.react(history=history,@@ -281,7 +307,7 @@ class ReActV2(Module):"tool_choice": {"type": "function", "function": {"name": "submit"}},"reasoning_effort": None,},- **pending_inputs,+ **turn_inputs,)tool_calls = _ensure_tool_call_ids(_coerce_tool_calls(getattr(pred, "tool_calls", None)), turn_index)except (AdapterParseError, ValueError, ContextWindowExceededError) as err:@@ -293,7 +319,7 @@ class ReActV2(Module):raise ValueError(f"ReActV2 failed to produce final outputs after {break_reason}: no submit call.")tool_call_results, final_outputs = self._execute_tool_calls(submit_calls)- event = self._history_event(pending_inputs, pred, submit_calls, tool_call_results)+ event = self._history_event(turn_inputs, pred, submit_calls, tool_call_results)if final_outputs is not None:event.update(final_outputs)_append_history_event(history, event)@@ -313,6 +339,7 @@ class ReActV2(Module):break_reason: str,turn_index: int,) -> Prediction:+ turn_inputs = {**pending_inputs, **self._turn_budget_inputs(None, None)}try:pred = await self.react.acall(history=history,@@ -321,7 +348,7 @@ class ReActV2(Module):"tool_choice": {"type": "function", "function": {"name": "submit"}},"reasoning_effort": None,},- **pending_inputs,+ **turn_inputs,)tool_calls = _ensure_tool_call_ids(_coerce_tool_calls(getattr(pred, "tool_calls", None)), turn_index)except (AdapterParseError, ValueError, ContextWindowExceededError) as err:@@ -333,7 +360,7 @@ class ReActV2(Module):raise ValueError(f"ReActV2 failed to produce final outputs after {break_reason}: no submit call.")tool_call_results, final_outputs = await self._aexecute_tool_calls(submit_calls)- event = self._history_event(pending_inputs, pred, submit_calls, tool_call_results)+ event = self._history_event(turn_inputs, pred, submit_calls, tool_call_results)if final_outputs is not None:event.update(final_outputs)_append_history_event(history, event)diff --git a/tests/predict/test_react_v2.py b/tests/predict/test_react_v2.pyindex f640f9a85..852949006 100644--- a/tests/predict/test_react_v2.py+++ b/tests/predict/test_react_v2.py@@ -362,12 +362,91 @@ def test_react_v2_rejects_reserved_output_field_names(reserved):dspy.ReActV2(f"question -> answer, {reserved}: str", tools=[])[email protected]("reserved", ["history", "tools"])[email protected]("reserved", ["history", "tools", "turn_budget"])def test_react_v2_rejects_reserved_input_field_names(reserved):with pytest.raises(ValueError, match=reserved):dspy.ReActV2(f"{reserved}: str -> answer: str", tools=[])+def _lookup_turn(query):+ return {+ "next_thought": f"Look up {query}.",+ "tool_calls": dspy.ToolCalls.from_dict_list([{"name": "lookup", "args": {"query": query}}]),+ }++[email protected]("use_async", [False, True])+async def test_react_v2_shows_current_turn_budget_each_call(use_async):+ def lookup(query: str) -> str:+ return f"found {query}"++ lm = dspy.utils.DummyLM(+ [+ _lookup_turn("cats"),+ _lookup_turn("dogs"),+ {+ "next_thought": "Out of turns.",+ "tool_calls": dspy.ToolCalls.from_dict_list([{"name": "submit", "args": {"answer": "pets"}}]),+ },+ ]+ )+ react = dspy.ReActV2("question -> answer", tools=[lookup], max_iters=20)++ with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):+ if use_async:+ pred = await react.acall(question="pets", max_iters=2)+ else:+ pred = react(question="pets", max_iters=2)++ assert pred.termination_reason == "forced_submit"+ assert "how many turns remain before you must submit" in lm.history[0]["messages"][0]["content"]+ expected = [+ "Turn 1 of 2 (1 more after this one).",+ "Turn 2 of 2 (this is your last turn).",+ "No turns remain. Call `submit` now with your final outputs.",+ ]+ for call, budget in zip(lm.history, expected, strict=True):+ assert f"[[ ## turn_budget ## ]]\n{budget}" in call["messages"][-1]["content"]+ # Each turn's budget is stored with that turn so replay rebuilds the exact request.+ assert [event["turn_budget"] for event in pred.history.messages] == expected+++def test_react_v2_native_requests_are_prefixes_for_prompt_caching():+ def lookup(query: str) -> str:+ return f"found {query}"++ lm = NativeToolLM()+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter(use_native_function_calling=True)):+ pred = dspy.ReActV2("question -> answer", tools=[lookup])(question="cats")++ assert pred.answer == "found cats"+ first, second = (call["messages"] for call in lm.calls)+ assert second[: len(first)] == first+ assert "[[ ## turn_budget ## ]]\nTurn 2 of 20" in second[-1]["content"]+++def test_react_v2_agent_pickled_before_turn_budget_keeps_old_behavior():+ lm = dspy.utils.DummyLM(+ [+ {+ "next_thought": "Done.",+ "tool_calls": dspy.ToolCalls.from_dict_list([{"name": "submit", "args": {"answer": "done"}}]),+ }+ ]+ )+ react = dspy.ReActV2("question -> answer", tools=[])+ # An agent pickled before this field existed restores its old inner signature without `__init__`.+ react.react.signature = react.react.signature.delete("turn_budget")++ with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):+ pred = react(question="cats")++ assert pred.answer == "done"+ assert all("turn_budget" not in message["content"] for message in lm.history[0]["messages"][1:])+ assert all("turn_budget" not in event for event in pred.history.messages)++@pytest.mark.asyncio@pytest.mark.parametrize("use_async", [False, True])@pytest.mark.parametrize("break_reason", ["max_iters", "empty_tool_calls", "parse_error", "context_window_exceeded"])diff --git a/tests/teleprompt/test_gepa_builtin_instruction_proposer.py b/tests/teleprompt/test_gepa_builtin_instruction_proposer.pyindex e8248562d..82e2f2fa0 100644--- a/tests/teleprompt/test_gepa_builtin_instruction_proposer.py+++ b/tests/teleprompt/test_gepa_builtin_instruction_proposer.py@@ -550,8 +550,9 @@ def test_gepa_truncate_history_outputs_on_a_react_program_and_custom_proposers_sassert context.endswith("```")assert LONG_TOOL_OUTPUT in contextassert "characters cut" not in context- assert list(example["Inputs"]) == ["Context", "tools"]+ assert list(example["Inputs"]) == ["Context", "tools", "turn_budget"]assert isinstance(example["Inputs"]["tools"], str)+ assert example["Inputs"]["turn_budget"].startswith("Turn ")def test_explicit_builtin_proposer_with_a_flex_submodule_logs_no_custom_proposer_warning(caplog):