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.mdindex 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.```pythonimport asyncio+import sys+from pathlib import Path+import dspyfrom mcp import ClientSession, StdioServerParametersfrom 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 serverserver_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 toolsclass 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 agentresult = 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 ConversionDSPy automatically handles the conversion from MCP tools to DSPy tools:diff --git a/dspy/predict/react_v2.py b/dspy/predict/react_v2.pyindex 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.pyindex f3a83c736..d9195cbc7 100644--- a/tests/predict/test_react_v2.py+++ b/tests/predict/test_react_v2.py@@ -1,3 +1,5 @@+import asyncio+import pytestimport 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 ValueErrorwith 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 == 1diff --git a/tests/utils/test_mcp.py b/tests/utils/test_mcp.pyindex 1108ae8ca..a6b748540 100644--- a/tests/utils/test_mcp.py+++ b/tests/utils/test_mcp.py@@ -1,12 +1,16 @@import asyncioimport importlib+import jsonimport sysfrom importlib.metadata import version+from pathlib import Pathfrom types import SimpleNamespaceimport pytest+import dspyfrom dspy import Tool+from dspy.dsp.utils.utils import dotdictfrom dspy.utils.mcp import _convert_mcp_tool_result, convert_mcp_toolif 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"