Skip to content

armgit / dspy

Public Imported from GitHub
0

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

Python

feat(predict): add ReActV2 async execution and MCP end-to-end coverage (#10356)

Isaac Miller05728f6ad5db
diff --git a/docs/docs/learn/programming/mcp.md b/docs/docs/learn/programming/mcp.md
index a75d077b5..84339ce61 100644
--- a/docs/docs/learn/programming/mcp.md
+++ b/docs/docs/learn/programming/mcp.md
@@ -84,20 +84,48 @@ asyncio.run(main())
### 2. Stdio Server (Local Process)
-The most common way to use MCP is with a local server process communicating via stdio. This example works with both SDK versions:
+The most common way to use MCP is with a local server process communicating via stdio. This example connects ReActV2 to an arithmetic server and works with both SDK versions.
+
+Save the following as `mcp_server.py`:
+
+```python
+try:
+ from mcp.server.fastmcp import FastMCP as MCPServer
+except ImportError:
+ from mcp.server import MCPServer
+
+server = MCPServer("arithmetic")
+
+def add(a: int, b: int) -> int:
+ """Add two integers."""
+ return a + b
+
+if __name__ == "__main__":
+ server.run()
+```
+
+Save the client below as `agent.py` alongside it. Set `OPENAI_API_KEY` in your environment and run `python agent.py`. The client starts and stops the MCP server automatically. Native function calling requires a model that supports tools.
```python
import asyncio
+import sys
+from pathlib import Path
+
import dspy
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
+dspy.configure(
+ lm=dspy.LM("openai/gpt-4.1-mini"),
+ adapter=dspy.ChatAdapter(use_native_function_calling=True),
+)
+
async def main():
# Configure the stdio server
server_params = StdioServerParameters(
- command="python", # Command to run
- args=["path/to/your/mcp_server.py"], # Server script path
- env=None, # Optional environment variables
+ command=sys.executable,
+ args=[str(Path(__file__).with_name("mcp_server.py"))],
)
# Connect to the server
@@ -115,13 +143,13 @@ async def main():
for tool in response.tools
]
- # Create a ReAct agent with the tools
+ # Create a ReActV2 agent with the tools
class QuestionAnswer(dspy.Signature):
"""Answer questions using available tools."""
question: str = dspy.InputField()
- answer: str = dspy.OutputField()
+ answer: int = dspy.OutputField()
- react_agent = dspy.ReAct(
+ react_agent = dspy.ReActV2(
signature=QuestionAnswer,
tools=dspy_tools,
max_iters=5
@@ -129,7 +157,7 @@ async def main():
# Use the agent
result = await react_agent.acall(
- question="What is 25 + 17?"
+ question="Use the add tool to calculate 25 + 17."
)
print(result.answer)
@@ -137,6 +165,8 @@ async def main():
asyncio.run(main())
```
+Keep the agent call inside the open MCP session: converted tools use that session to execute requests. MCP tools are asynchronous, so use `await react_agent.acall(...)`.
+
## Tool Conversion
DSPy automatically handles the conversion from MCP tools to DSPy tools:
diff --git a/dspy/predict/react_v2.py b/dspy/predict/react_v2.py
index 5a0d029d4..548cbc86d 100644
--- a/dspy/predict/react_v2.py
+++ b/dspy/predict/react_v2.py
@@ -151,6 +151,46 @@ class ReActV2(Module):
return self._forced_submit(history, pending_inputs, break_reason, max_iters)
+ async def aforward(self, **input_args):
+ max_iters = input_args.pop("max_iters", self.max_iters)
+ history = _coerce_history(input_args.pop("history", None))
+ pending_inputs = {name: input_args[name] for name in self.signature.input_fields if name in input_args}
+
+ break_reason = "max_iters"
+ for turn_index in range(max_iters):
+ try:
+ pred = await self.react.acall(
+ history=history,
+ tools=list(self.tools.values()),
+ **pending_inputs,
+ )
+ tool_calls = _coerce_tool_calls(getattr(pred, "tool_calls", None))
+ except (AdapterParseError, ValueError) as err:
+ logger.warning("Ending ReActV2 loop after parse failure: %s", format_error_for_lm(err, traceback_frames=5))
+ break_reason = "parse_error"
+ break
+ except ContextWindowExceededError:
+ logger.warning("Ending ReActV2 loop after context window exceeded.")
+ break_reason = "context_window_exceeded"
+ break
+
+ if not tool_calls.tool_calls:
+ break_reason = "empty_tool_calls"
+ break
+
+ 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)
+ if final_outputs is not None:
+ event.update(final_outputs)
+ _append_history_event(history, event)
+ pending_inputs = {}
+
+ if final_outputs is not None:
+ return Prediction(**final_outputs, history=history, termination_reason="submit")
+
+ return await self._aforced_submit(history, pending_inputs, break_reason, max_iters)
+
def _execute_tool_calls(self, tool_calls: ToolCalls) -> tuple[ToolCallResults, dict[str, Any] | None]:
values = []
is_errors = []
@@ -174,6 +214,29 @@ class ReActV2(Module):
return ToolCallResults.from_tool_calls_and_values(tool_calls, values, is_errors), final_outputs
+ async def _aexecute_tool_calls(self, tool_calls: ToolCalls) -> tuple[ToolCallResults, dict[str, Any] | None]:
+ values = []
+ is_errors = []
+ final_outputs = None
+
+ for tool_call in tool_calls.tool_calls:
+ if tool_call.name not in self.tools:
+ values.append(f"Unknown tool: {tool_call.name}")
+ is_errors.append(True)
+ continue
+
+ try:
+ value = await self.tools[tool_call.name].acall(**(tool_call.args or {}))
+ values.append(value)
+ is_errors.append(False)
+ if tool_call.name == "submit" and isinstance(value, dict):
+ final_outputs = value
+ except Exception as err:
+ values.append(f"Execution error in {tool_call.name}: {format_error_for_lm(err, traceback_frames=5)}")
+ is_errors.append(True)
+
+ return ToolCallResults.from_tool_calls_and_values(tool_calls, values, is_errors), final_outputs
+
def _history_event(
self,
pending_inputs: dict[str, Any],
@@ -230,6 +293,46 @@ class ReActV2(Module):
f"ReActV2 failed to produce final outputs after {break_reason}: submit failed.\n{errors}"
)
+ async def _aforced_submit(
+ self,
+ history: dspy.History,
+ pending_inputs: dict[str, Any],
+ break_reason: str,
+ turn_index: int,
+ ) -> Prediction:
+ try:
+ pred = await self.react.acall(
+ history=history,
+ tools=list(self.tools.values()),
+ config={
+ "tool_choice": {"type": "function", "function": {"name": "submit"}},
+ "reasoning_effort": None,
+ },
+ **pending_inputs,
+ )
+ tool_calls = _ensure_tool_call_ids(_coerce_tool_calls(getattr(pred, "tool_calls", None)), turn_index)
+ except (AdapterParseError, ValueError, ContextWindowExceededError) as err:
+ logger.warning("Forced submit failed: %s", format_error_for_lm(err, traceback_frames=5))
+ raise
+
+ submit_calls = ToolCalls(tool_calls=[call for call in tool_calls.tool_calls if call.name == "submit"])
+ if not submit_calls.tool_calls:
+ 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)
+ if final_outputs is not None:
+ event.update(final_outputs)
+ _append_history_event(history, event)
+
+ if final_outputs is not None:
+ return Prediction(**final_outputs, history=history, termination_reason="forced_submit")
+
+ errors = "\n".join(str(result.value) for result in tool_call_results.tool_call_results if result.is_error)
+ raise ValueError(
+ f"ReActV2 failed to produce final outputs after {break_reason}: submit failed.\n{errors}"
+ )
+
def _json_schema_for_annotation(annotation: Any) -> dict[str, Any]:
try:
diff --git a/tests/predict/test_react_v2.py b/tests/predict/test_react_v2.py
index f3a83c736..d9195cbc7 100644
--- a/tests/predict/test_react_v2.py
+++ b/tests/predict/test_react_v2.py
@@ -1,3 +1,5 @@
+import asyncio
+
import pytest
import dspy
@@ -335,9 +337,11 @@ def test_react_v2_rejects_reserved_output_field_names(reserved):
dspy.ReActV2(f"question -> answer, {reserved}: str", tools=[])
[email protected]("use_async", [False, True])
@pytest.mark.parametrize("break_reason", ["max_iters", "empty_tool_calls", "parse_error", "context_window_exceeded"])
@pytest.mark.parametrize("forced_result", ["no_submit", "missing_field", "parse_error", "context_window_exceeded"])
-def test_react_v2_failed_termination_raises(mocker, break_reason, forced_result):
+async def test_react_v2_failed_termination_raises(mocker, break_reason, forced_result, use_async):
react = dspy.ReActV2("question -> answer: str, count: int", tools=[], max_iters=1)
empty = dspy.Prediction(tool_calls=dspy.ToolCalls(tool_calls=[]))
incomplete = dspy.Prediction(
@@ -351,12 +355,19 @@ def test_react_v2_failed_termination_raises(mocker, break_reason, forced_result)
"parse_error": ValueError("invalid tool calls"),
"context_window_exceeded": ContextWindowExceededError(message="too long"),
}
- mocker.patch.object(react.react, "forward", side_effect=[outcomes[break_reason], outcomes[forced_result]])
+ mocker.patch.object(
+ react.react,
+ "aforward" if use_async else "forward",
+ side_effect=[outcomes[break_reason], outcomes[forced_result]],
+ )
history = dspy.History(messages=[])
error_type = ContextWindowExceededError if forced_result == "context_window_exceeded" else ValueError
with pytest.raises(error_type) as exc:
- react(question="cats", history=history)
+ if use_async:
+ await react.acall(question="cats", history=history)
+ else:
+ react(question="cats", history=history)
if forced_result in {"parse_error", "context_window_exceeded"}:
assert exc.value is outcomes[forced_result]
@@ -388,3 +399,107 @@ def test_react_v2_evaluate_reports_submission_failure(caplog):
with pytest.raises(Exception, match="Execution cancelled due to errors"):
evaluate(dspy.ReActV2("question -> answer", tools=[]))
assert "failed to produce final outputs after empty_tool_calls: no submit call" in caplog.text
+
+
+async def test_react_v2_async_mixed_tools_run_sequentially_and_recover():
+ executed = []
+
+ async def lookup(query: str) -> str:
+ await asyncio.sleep(0)
+ executed.append(query)
+ return f"found {query}"
+
+ def fail() -> str:
+ executed.append("fail")
+ raise ValueError("lookup unavailable")
+
+ lm = dspy.utils.DummyLM(
+ [
+ {
+ "next_thought": "Look up both.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [
+ {"name": "lookup", "args": {"query": "cats"}},
+ {"name": "missing", "args": {}},
+ {"name": "fail", "args": {}},
+ {"name": "lookup", "args": {"query": "dogs"}},
+ ]
+ ),
+ },
+ {
+ "next_thought": "Done.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [
+ {"name": "submit", "args": {"answer": "cats and dogs", "count": 2}},
+ ]
+ ),
+ },
+ ]
+ )
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):
+ pred = await dspy.ReActV2("question -> answer: str, count: int", tools=[lookup, fail]).acall(
+ question="pets",
+ history={"messages": [{"question": "old"}]},
+ )
+
+ assert (pred.answer, pred.count, pred.termination_reason) == ("cats and dogs", 2, "submit")
+ assert executed == ["cats", "fail", "dogs"]
+ assert pred.history.messages[0] == {"question": "old"}
+ assert pred.history.messages[1]["question"] == "pets"
+ assert "question" not in pred.history.messages[2]
+ results = pred.history.messages[1]["tool_calls"].tool_call_results.tool_call_results
+ assert [r.call_id for r in results] == ["call_0_0", "call_0_1", "call_0_2", "call_0_3"]
+ assert [r.is_error for r in results] == [False, True, True, False]
+ assert results[0].value == "found cats"
+ assert results[1].value == "Unknown tool: missing"
+ assert "lookup unavailable" in results[2].value
+ assert results[3].value == "found dogs"
+
+
[email protected]("max_iters", [0, 1])
+async def test_react_v2_async_forced_submit_filters_other_tools(mocker, max_iters):
+ def forbidden() -> str:
+ pytest.fail("Forced submit must not execute other tools")
+
+ react = dspy.ReActV2("question -> answer", tools=[forbidden], max_iters=20)
+ empty = dspy.Prediction(tool_calls=dspy.ToolCalls(tool_calls=[]))
+ final = dspy.Prediction(
+ tool_calls=dspy.ToolCalls.from_dict_list(
+ [
+ {"name": "forbidden", "args": {}},
+ {"name": "submit", "args": {"answer": "forced"}},
+ ]
+ )
+ )
+ predictor = mocker.patch.object(react.react, "aforward", side_effect=[empty] * max_iters + [final])
+
+ pred = await react.acall(question="cats", max_iters=max_iters)
+
+ assert pred.answer == "forced"
+ assert pred.termination_reason == "forced_submit"
+ assert pred.history.messages[0]["question"] == "cats"
+ assert pred.history.messages[0]["tool_calls"].tool_calls[0].id == f"call_{max_iters}_1"
+ assert predictor.call_args.kwargs["config"] == {
+ "tool_choice": {"type": "function", "function": {"name": "submit"}},
+ "reasoning_effort": None,
+ }
+
+
+async def test_react_v2_async_tool_cancellation_propagates(mocker):
+ async def cancel() -> str:
+ raise asyncio.CancelledError
+
+ react = dspy.ReActV2("question -> answer", tools=[cancel])
+ predictor = mocker.patch.object(
+ react.react,
+ "aforward",
+ return_value=dspy.Prediction(
+ tool_calls=dspy.ToolCalls.from_dict_list([{"name": "cancel", "args": {}}]),
+ ),
+ )
+ with pytest.raises(asyncio.CancelledError):
+ await react.acall(question="cats")
+ assert predictor.await_count == 1
diff --git a/tests/utils/test_mcp.py b/tests/utils/test_mcp.py
index 1108ae8ca..a6b748540 100644
--- a/tests/utils/test_mcp.py
+++ b/tests/utils/test_mcp.py
@@ -1,12 +1,16 @@
import asyncio
import importlib
+import json
import sys
from importlib.metadata import version
+from pathlib import Path
from types import SimpleNamespace
import pytest
+import dspy
from dspy import Tool
+from dspy.dsp.utils.utils import dotdict
from dspy.utils.mcp import _convert_mcp_tool_result, convert_mcp_tool
if importlib.util.find_spec("mcp") is None:
@@ -220,3 +224,80 @@ async def test_convert_mcp_tool():
assert current_datetime_tool.arg_types == {}
assert current_datetime_tool.arg_desc == {}
assert await current_datetime_tool.acall() == "2025-07-23T09:10:10.0+00:00"
+
+
+async def test_react_v2_native_mcp_end_to_end():
+ """Exercise native messages and a real stdio MCP server without an API key."""
+ from mcp import ClientSession, StdioServerParameters
+ from mcp.client.stdio import stdio_client
+
+ class NativeMCPLM(dspy.BaseLM):
+ def __init__(self):
+ super().__init__("native-mcp-test")
+ self.requests = []
+
+ @property
+ def supports_function_calling(self):
+ return True
+
+ def forward(self, *args, **kwargs):
+ pytest.fail("ReActV2 must use the async LM path")
+
+ async def aforward(self, prompt=None, messages=None, **kwargs):
+ self.requests.append({"messages": messages, "kwargs": kwargs})
+ if len(self.requests) == 1:
+ calls = [
+ ("mcp_error", "wrong_tool", {}),
+ ("mcp_add", "add", {"a": 25, "b": 17}),
+ ]
+ else:
+ observations = {m["tool_call_id"]: m["content"] for m in messages if m["role"] == "tool"}
+ assert "error!" in observations["mcp_error"]
+ assert observations["mcp_add"] == "42"
+ calls = [("final", "submit", {"answer": int(observations["mcp_add"])})]
+ return dotdict(
+ choices=[
+ dotdict(
+ message=dotdict(
+ content=None,
+ tool_calls=[
+ dotdict(
+ id=call_id, type="function", function=dotdict(name=name, arguments=json.dumps(args))
+ )
+ for call_id, name, args in calls
+ ],
+ ),
+ finish_reason="tool_calls",
+ )
+ ],
+ usage=dotdict(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ model=self.model,
+ )
+
+ server_params = StdioServerParameters(
+ command=sys.executable,
+ args=[str(Path(__file__).parent / "resources" / "mcp_server.py")],
+ )
+ lm = NativeMCPLM()
+ async with stdio_client(server_params) as (read, write):
+ async with ClientSession(read, write) as session:
+ await asyncio.wait_for(session.initialize(), timeout=5)
+ response = await session.list_tools()
+ tools = [Tool.from_mcp_tool(session, tool) for tool in response.tools]
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter(use_native_function_calling=True)):
+ pred = await asyncio.wait_for(
+ dspy.ReActV2("question -> answer: int", tools=tools).acall(question="What is 25 + 17?"),
+ timeout=15,
+ )
+
+ assert pred.answer == 42
+ assert pred.termination_reason == "submit"
+ assert len(lm.requests) == 2
+ assert {t["function"]["name"] for t in lm.requests[0]["kwargs"]["tools"]} == {tool.name for tool in tools} | {
+ "submit"
+ }
+ results = pred.history.messages[0]["tool_calls"].tool_call_results.tool_call_results
+ assert [(r.call_id, r.is_error) for r in results] == [("mcp_error", True), ("mcp_add", False)]
+ assert results[1].value == "42"