Skip to content

armgit / dspy

Public Imported from GitHub
0

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.py
index 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.py
index 1ad2a40d2..215e6b6b2 100644
--- a/dspy/primitives/tool.py
+++ b/dspy/primitives/tool.py
@@ -1,6 +1,6 @@
import asyncio
import 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_hints
from jsonschema import ValidationError, validate
from pydantic import BaseModel, TypeAdapter, create_model
@@ -10,6 +10,7 @@ from dspy.utils.callback import with_callbacks
if 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
+
@classmethod
def 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.py
index 3a39b09b7..680028aad 100644
--- a/tests/predict/test_react.py
+++ b/tests/predict/test_react.py
@@ -5,125 +5,7 @@ import dspy
import litellm
from 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 pytest
def 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}"