DSPy: The framework for programming—not prompting—language models
Python
Async ReAct (#8139)
Chen Qian43a8a53acc19
diff --git a/dspy/predict/react.py b/dspy/predict/react.pyindex 0580a7f7b..4b369c0ba 100644--- a/dspy/predict/react.py+++ b/dspy/predict/react.py@@ -98,6 +98,31 @@ class ReAct(Module):extract = self._call_with_potential_trajectory_truncation(self.extract, trajectory, **input_args)return dspy.Prediction(trajectory=trajectory, **extract)+ async def aforward(self, **input_args):+ trajectory = {}+ max_iters = input_args.pop("max_iters", self.max_iters)+ for idx in range(max_iters):+ try:+ pred = await self._async_call_with_potential_trajectory_truncation(self.react, trajectory, **input_args)+ except ValueError as err:+ logger.warning(f"Ending the trajectory: Agent failed to select a valid tool: {_fmt_exc(err)}")+ break++ trajectory[f"thought_{idx}"] = pred.next_thought+ trajectory[f"tool_name_{idx}"] = pred.next_tool_name+ trajectory[f"tool_args_{idx}"] = pred.next_tool_args++ try:+ trajectory[f"observation_{idx}"] = await self.tools[pred.next_tool_name].acall(**pred.next_tool_args)+ except Exception as err:+ trajectory[f"observation_{idx}"] = f"Execution error in {pred.next_tool_name}: {_fmt_exc(err)}"++ if pred.next_tool_name == "finish":+ break++ extract = await self._async_call_with_potential_trajectory_truncation(self.extract, trajectory, **input_args)+ return dspy.Prediction(trajectory=trajectory, **extract)+def _call_with_potential_trajectory_truncation(self, module, trajectory, **input_args):for _ in range(3):try:@@ -109,6 +134,17 @@ class ReAct(Module):logger.warning("Trajectory exceeded the context window, truncating the oldest tool call information.")trajectory = self.truncate_trajectory(trajectory)+ async def _async_call_with_potential_trajectory_truncation(self, module, trajectory, **input_args):+ for _ in range(3):+ try:+ return await module.acall(+ **input_args,+ trajectory=self._format_trajectory(trajectory),+ )+ except ContextWindowExceededError:+ logger.warning("Trajectory exceeded the context window, truncating the oldest tool call information.")+ trajectory = self.truncate_trajectory(trajectory)+def truncate_trajectory(self, trajectory):"""Truncates the trajectory so that it fits in the context window.diff --git a/dspy/primitives/tool.py b/dspy/primitives/tool.pyindex 1ad2a40d2..215e6b6b2 100644--- a/dspy/primitives/tool.py+++ b/dspy/primitives/tool.py@@ -1,6 +1,6 @@import asyncioimport inspect-from typing import Any, Callable, Optional, get_origin, get_type_hints, TYPE_CHECKING+from typing import TYPE_CHECKING, Any, Callable, Optional, get_origin, get_type_hintsfrom jsonschema import ValidationError, validatefrom pydantic import BaseModel, TypeAdapter, create_model@@ -10,6 +10,7 @@ from dspy.utils.callback import with_callbacksif TYPE_CHECKING:import mcp+class Tool:"""Tool class.@@ -175,10 +176,12 @@ class Tool:async def acall(self, **kwargs):parsed_kwargs = self._validate_and_parse_args(**kwargs)result = self.func(**parsed_kwargs)- if not asyncio.iscoroutine(result):- raise ValueError("You are calling `acall` on a non-async tool, please use `__call__` instead.")- return await result-+ if asyncio.iscoroutine(result):+ return await result+ else:+ # We should allow calling a sync tool in the async path.+ return result+@classmethoddef from_mcp_tool(cls, session: "mcp.client.session.ClientSession", tool: "mcp.types.Tool") -> "Tool":"""@@ -192,4 +195,5 @@ class Tool:A Tool object."""from dspy.utils.mcp import convert_mcp_tool+return convert_mcp_tool(session, tool)diff --git a/tests/predict/test_react.py b/tests/predict/test_react.pyindex 3a39b09b7..680028aad 100644--- a/tests/predict/test_react.py+++ b/tests/predict/test_react.py@@ -5,125 +5,7 @@ import dspyimport litellmfrom dspy.utils.dummies import DummyLM--# def test_example_no_tools():-# # Create a simple dataset which the model will use with the Retrieve tool.-# lm = DummyLM(-# [-# {"Thought_1": "Initial thoughts", "Action_1": "Finish[blue]"},-# ]-# )-# dspy.settings.configure(lm=lm, rm=dummy_rm())--# program = dspy.ReAct("question -> answer")--# # Check default tools-# assert isinstance(program.tools["Finish"], dspy.Example)--# # Call the ReAct module on a particular input-# question = "What is the color of the sky?"-# result = program(question=question)-# assert result.answer == "blue"---# def test_example_search():-# # Create a simple dataset which the model will use with the Retrieve tool.-# lm = DummyLM(-# [-# {"Thought_1": "Initial thoughts", "Action_1": "Search[the color of the sky]"},-# {"Thought_2": "More thoughts", "Action_2": "Finish[blue]\n\n"},-# ]-# )-# rm = dummy_rm(-# [-# "We all know the color of the sky is blue.",-# "Something about the sky colors",-# "This sentence is completely irellevant to answer the question.",-# "Let's add some more sentences to act as summy passages.",-# "Let's add some more sentences to act as summy passages.",-# "Let's add some more sentences to act as summy passages.",-# ]-# )-# dspy.settings.configure(lm=lm, rm=rm)--# program = dspy.ReAct("question -> answer")--# # Check default tools-# assert len(program.tools) == 2-# assert isinstance(program.tools["Search"], dspy.Retrieve)-# assert isinstance(program.tools["Finish"], dspy.Example)--# # Call the ReAct module on a particular input-# question = "What is the color of the sky?"-# result = program(question=question)-# assert result.answer == "blue"---# class DummyTool1:-# name = "Tool1"-# input_variable = "query"-# desc = ""-# num_calls = 0--# def __call__(self, *args, **kwargs):-# # test case with no passages attribute-# assert args[0] == "foo"-# self.num_calls += 1-# return "tool 1 output"---# @dataclass-# class DummyOutput:-# passages: str---# class DummyTool2:-# name = "Tool2"-# input_variable = "query"-# desc = ""-# num_calls = 0--# def __call__(self, *args, **kwargs):-# # test case with passages attribute-# assert args[0] == "bar"-# self.num_calls += 1-# return DummyOutput(passages="tool 2 output")---# def test_custom_tools():-# lm = DummyLM(-# [-# {"Thought_1": "Initial thoughts", "Action_1": "Tool1[foo]"},-# {"Thought_2": "More thoughts", "Action_2": "Tool2[bar]"},-# {"Thought_3": "Even more thoughts", "Action_3": "Finish[baz]"},-# ]-# )-# dspy.settings.configure(lm=lm)--# tool1 = DummyTool1()-# tool2 = DummyTool2()-# program = dspy.ReAct("question -> answer", tools=[tool1, tool2])--# question = "What is the color of the sky?"-# result = program(question=question)-# assert result.answer == "baz"--# # each tool should be called only once-# assert tool1.num_calls == 1-# assert tool2.num_calls == 1---# def test_signature_instructions():-# class ExampleSignature(dspy.Signature):-# """You are going to generate output based on input."""--# input = dspy.InputField()-# output = dspy.OutputField()--# react = dspy.ReAct(ExampleSignature)--# assert react.react[0].signature.instructions is not None-# assert react.react[0].signature.instructions.startswith("You are going to generate output based on input.")+import pytestdef test_tool_calling_with_pydantic_args():@@ -323,3 +205,130 @@ def test_error_retry():for i in range(2):obs = traj[f"observation_{i}"]assert re.search(r"\btool error\b", obs), f"unexpected observation_{i!r}: {obs}"+++async def test_async_tool_calling_with_pydantic_args():+ class CalendarEvent(BaseModel):+ name: str+ date: str+ participants: dict[str, str]++ async def write_invitation_letter(participant_name: str, event_info: CalendarEvent):+ if participant_name not in event_info.participants:+ return None+ return f"It's my honor to invite {participant_name} to event {event_info.name} on {event_info.date}"++ class InvitationSignature(dspy.Signature):+ participant_name: str = dspy.InputField(desc="The name of the participant to invite")+ event_info: CalendarEvent = dspy.InputField(desc="The information about the event")+ invitation_letter: str = dspy.OutputField(desc="The invitation letter to be sent to the participant")++ react = dspy.ReAct(InvitationSignature, tools=[write_invitation_letter])++ lm = DummyLM(+ [+ {+ "next_thought": "I need to write an invitation letter for Alice to the Science Fair event.",+ "next_tool_name": "write_invitation_letter",+ "next_tool_args": {+ "participant_name": "Alice",+ "event_info": {+ "name": "Science Fair",+ "date": "Friday",+ "participants": {"Alice": "female", "Bob": "male"},+ },+ },+ },+ {+ "next_thought": (+ "I have successfully written the invitation letter for Alice to the Science Fair. Now "+ "I can finish the task."+ ),+ "next_tool_name": "finish",+ "next_tool_args": {},+ },+ {+ "reasoning": "This is a very rigorous reasoning process, trust me bro!",+ "invitation_letter": "It's my honor to invite Alice to the Science Fair event on Friday.",+ },+ ]+ )+ dspy.settings.configure(lm=lm)++ outputs = await react.acall(+ participant_name="Alice",+ event_info=CalendarEvent(+ name="Science Fair",+ date="Friday",+ participants={"Alice": "female", "Bob": "male"},+ ),+ )+ assert outputs.invitation_letter == "It's my honor to invite Alice to the Science Fair event on Friday."++ expected_trajectory = {+ "thought_0": "I need to write an invitation letter for Alice to the Science Fair event.",+ "tool_name_0": "write_invitation_letter",+ "tool_args_0": {+ "participant_name": "Alice",+ "event_info": {+ "name": "Science Fair",+ "date": "Friday",+ "participants": {"Alice": "female", "Bob": "male"},+ },+ },+ "observation_0": "It's my honor to invite Alice to event Science Fair on Friday",+ "thought_1": "I have successfully written the invitation letter for Alice to the Science Fair. Now I can finish the task.",+ "tool_name_1": "finish",+ "tool_args_1": {},+ "observation_1": "Completed.",+ }+ assert outputs.trajectory == expected_trajectory+++async def test_async_error_retry():+ # A tiny tool that always fails+ async def foo(a, b): # noqa: D401, ANN001+ raise Exception("tool error")++ react = dspy.ReAct("a, b -> c:int", tools=[foo])+ lm = DummyLM(+ [+ {+ "next_thought": "I need to add two numbers.",+ "next_tool_name": "foo",+ "next_tool_args": {"a": 1, "b": 2},+ },+ {+ "next_thought": "I need to add two numbers.",+ "next_tool_name": "foo",+ "next_tool_args": {"a": 1, "b": 2},+ },+ # (The model *would* succeed on the 3rd turn, but max_iters=2 stops earlier.)+ {"reasoning": "I added the numbers successfully", "c": 3},+ ]+ )+ dspy.settings.configure(lm=lm)++ outputs = await react.acall(a=1, b=2, max_iters=2)+ traj = outputs.trajectory++ # Exact-match checks (thoughts + tool calls)+ control_expected = {+ "thought_0": "I need to add two numbers.",+ "tool_name_0": "foo",+ "tool_args_0": {"a": 1, "b": 2},+ "thought_1": "I need to add two numbers.",+ "tool_name_1": "foo",+ "tool_args_1": {"a": 1, "b": 2},+ }+ for k, v in control_expected.items():+ assert traj[k] == v, f"{k} mismatch"++ # Flexible checks for observations+ # We only care that each observation mentions our error string; we ignore+ # any extra traceback detail or differing prefixes.+ for i in range(2):+ obs = traj[f"observation_{i}"]+ assert re.search(r"\btool error\b", obs), f"unexpected observation_{i!r}: {obs}"