Document ToolCall.execute() availability from dspy 3.0.4b2

[Copilot]

Users on dspy 3.0.3 encounter AttributeError: 'ToolCall' object has no attribute 'execute' when following the tools documentation, as this method was added in 3.0.4b2.

Changes

• Added version requirement admonitions to docs/docs/learn/programming/tools.md at:
  • Start of "Approach 2: Manual Tool Handling" section
  • "Understanding dspy.ToolCalls" subsection
• Added code comments showing workaround for pre-3.0.4b2 versions using manual tool lookup: tools[call.name](**call.args)

The notes inform users that ToolCall.execute() requires dspy 3.0.4b2 or later.

!!! note "Version Requirement"
    The `ToolCall.execute()` method is available from **dspy 3.0.4b2** onwards. If you're using an earlier version, you'll need to upgrade to use this feature.

For users on earlier versions, code examples now include inline comments demonstrating the backward-compatible approach:

# For versions earlier than 3.0.4b2, use: result = tools[call.name](**call.args)

[!WARNING]

Original prompt

---

This section details on the original issue you should resolve

<filter_complete></filter_complete>

<issue_title>[Bug] Manual tool calling not working</issue_title>
<issue_description>### What happened?

The manual tool calling provided in the documentation is itself not working giving the error provided in the description.

Steps to reproduce

import dspy

class ToolSignature(dspy.Signature):
"""Signature for manual tool handling."""

question: str = dspy.InputField()
tools: list[dspy.Tool] = dspy.InputField()
outputs: dspy.ToolCalls = dspy.OutputField()

def weather(city: str) -> str:
"""Get weather information for a city."""
return f"The weather in {city} is sunny"

def calculator(expression: str) -> str:
"""Evaluate a mathematical expression."""
try:
result = eval(expression) # Note: Use safely in production
return f"The result is {result}"
except:
return "Invalid expression"

Create tool instances

tools = {"weather": dspy.Tool(weather), "calculator": dspy.Tool(calculator)}

Create predictor

predictor = dspy.Predict(ToolSignature)

Make a prediction

response = predictor(
question="What's the weather in New York?", tools=list(tools.values())
)

Execute the tool calls

for call in response.outputs.tool_calls:
# Execute the tool call
result = call.execute()
print(f"Tool: {call.name}")
print(f"Args: {call.args}")
# print(f"Result: {result}")

This is the code that is present in the documentation. It is itself not working, giving the below error.

---

AttributeError Traceback (most recent call last)
Cell In[44], line 40
37 # Execute the tool calls
38 for call in response.outputs.tool_calls:
39 # Execute the tool call

• ---> 40 result = call.execute()
  41 print(f"Tool: {call.name}")
  42 print(f"Args: {call.args}")

File ~/Mayank_python/personal_projects/data_science_monorepo/projects/agents/.venv/lib/python3.11/site-packages/pydantic/main.py:991, in BaseModel.getattr(self, item)
988 return super().getattribute(item) # Raises AttributeError if appropriate
989 else:
990 # this is the current error
---> 991 raise AttributeError(f'{type(self).name!r} object has no attribute {item!r}')

AttributeError: 'ToolCall' object has no attribute 'execute'

DSPy version

3.0.3</issue_description>

<agent_instructions>Can you document that ToolCall.execute is available from dspy 3.0.4b2?</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@TomeHirata Sorry for the confusion, currently the doc is based on the latest code. We'll change the policy from the next release.

• Fixes [Bug] Manual tool calling not working #8933

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug] Manual tool calling not working</issue_title>
<issue_description>### What happened?

The manual tool calling provided in the documentation is itself not working giving the error provided in the description.

Steps to reproduce

import dspy

class ToolSignature(dspy.Signature):
"""Signature for manual tool handling."""

question: str = dspy.InputField()
tools: list[dspy.Tool] = dspy.InputField()
outputs: dspy.ToolCalls = dspy.OutputField()

def weather(city: str) -> str:
"""Get weather information for a city."""
return f"The weather in {city} is sunny"

def calculator(expression: str) -> str:
"""Evaluate a mathematical expression."""
try:
result = eval(expression) # Note: Use safely in production
return f"The result is {result}"
except:
return "Invalid expression"

Create tool instances

tools = {"weather": dspy.Tool(weather), "calculator": dspy.Tool(calculator)}

Create predictor

predictor = dspy.Predict(ToolSignature)

Make a prediction

response = predictor(
question="What's the weather in New York?", tools=list(tools.values())
)

Execute the tool calls

for call in response.outputs.tool_calls:
# Execute the tool call
result = call.execute()
print(f"Tool: {call.name}")
print(f"Args: {call.args}")
# print(f"Result: {result}")

This is the code that is present in the documentation. It is itself not working, giving the below error.

---

AttributeError Traceback (most recent call last)
Cell In[44], line 40
37 # Execute the tool calls
38 for call in response.outputs.tool_calls:
39 # Execute the tool call
---> 40 result = call.execute()
41 print(f"Tool: {call.name}")
42 print(f"Args: {call.args}")

File ~/Mayank_python/personal_projects/data_science_monorepo/projects/agents/.venv/lib/python3.11/site-packages/pydantic/main.py:991, in BaseModel.getattr(self, item)
988 return super().getattribute(item) # Raises AttributeError if appropriate
989 else:
990 # this is the current error
--> 991 raise AttributeError(f'{type(self).name!r} object has no attribute {item!r}')

AttributeError: 'ToolCall' object has no attribute 'execute'

DSPy version

3.0.3</issue_description>

<agent_instructions>Can you document that ToolCall.execute is available from dspy 3.0.4b2?</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@TomeHirata Sorry for the confusion, currently the doc is based on the latest code. We'll change the policy from the next release.

• Fixes [Bug] Manual tool calling not working #8933

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[TomeHirata]

@copilot Can we also document that users need to call tools[call.name](**call.args) in the earlier versions? We can include this as a comment in the code example

[Copilot]

Added workaround documentation in commit 1723bc5.

The code examples now include:

1. In the Basic Setup section: an inline comment showing result = tools[call.name](**call.args) for pre-3.0.4b2 versions
2. In the Understanding ToolCalls section: an "Option 4" showing the manual tool lookup pattern for backward compatibility