Skip to content

armgit / dspy

Public Imported from GitHub
0

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.md
index 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 th
Unlike 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 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.
diff --git a/dspy/predict/react_v2.py b/dspy/predict/react_v2.py
index 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.py
index 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.py
index 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_s
assert context.endswith("```")
assert LONG_TOOL_OUTPUT in context
assert "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):