Rename HandleResponseNode to CallToolsNode (#1020)

Author: dmontagu

docs/agents.md

@@ -133,7 +133,7 @@ async def main():
                 kind='request',
             )
         ),
-        HandleResponseNode(
+        CallToolsNode(
             model_response=ModelResponse(
                 parts=[TextPart(content='Paris', part_kind='text')],
                 model_name='gpt-4o',
@@ -194,7 +194,7 @@ async def main():
                     kind='request',
                 )
             ),
-            HandleResponseNode(
+            CallToolsNode(
                 model_response=ModelResponse(
                     parts=[TextPart(content='Paris', part_kind='text')],
                     model_name='gpt-4o',
@@ -311,10 +311,10 @@ async def main():
                             output_messages.append(
                                 f'[Result] The model produced a final result (tool_name={event.tool_name})'
                             )
-            elif Agent.is_handle_response_node(node):
+            elif Agent.is_call_tools_node(node):
                 # A handle-response node => The model returned some data, potentially calls a tool
                 output_messages.append(
-                    '=== HandleResponseNode: streaming partial response & tool usage ==='
+                    '=== CallToolsNode: streaming partial response & tool usage ==='
                 )
                 async with node.stream(run.ctx) as handle_stream:
                     async for event in handle_stream:
@@ -343,7 +343,7 @@ if __name__ == '__main__':
         '[Request] Part 0 args_delta=ris","forecast_',
         '[Request] Part 0 args_delta=date":"2030-01-',
         '[Request] Part 0 args_delta=01"}',
-        '=== HandleResponseNode: streaming partial response & tool usage ===',
+        '=== CallToolsNode: streaming partial response & tool usage ===',
         '[Tools] The LLM calls tool=\'weather_forecast\' with args={"location":"Paris","forecast_date":"2030-01-01"} (tool_call_id=\'0001\')',
         "[Tools] Tool call '0001' returned => The forecast in Paris on 2030-01-01 is 24°C and sunny.",
         '=== ModelRequestNode: streaming partial request tokens ===',
@@ -352,7 +352,7 @@ if __name__ == '__main__':
         "[Request] Part 0 text delta: 'warm and sunny '",
         "[Request] Part 0 text delta: 'in Paris on '",
         "[Request] Part 0 text delta: 'Tuesday.'",
-        '=== HandleResponseNode: streaming partial response & tool usage ===',
+        '=== CallToolsNode: streaming partial response & tool usage ===',
         '=== Final Agent Output: It will be warm and sunny in Paris on Tuesday. ===',
     ]
     """

pydantic_ai_slim/pydantic_ai/__init__.py

@@ -1,6 +1,6 @@
 from importlib.metadata import version
 
-from .agent import Agent, EndStrategy, HandleResponseNode, ModelRequestNode, UserPromptNode, capture_run_messages
+from .agent import Agent, CallToolsNode, EndStrategy, ModelRequestNode, UserPromptNode, capture_run_messages
 from .exceptions import (
     AgentRunError,
     FallbackExceptionGroup,
@@ -18,7 +18,7 @@
     # agent
     'Agent',
     'EndStrategy',
-    'HandleResponseNode',
+    'CallToolsNode',
     'ModelRequestNode',
     'UserPromptNode',
     'capture_run_messages',

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -36,7 +36,7 @@
     'GraphAgentDeps',
     'UserPromptNode',
     'ModelRequestNode',
-    'HandleResponseNode',
+    'CallToolsNode',
     'build_run_context',
     'capture_run_messages',
 )
@@ -243,12 +243,12 @@ class ModelRequestNode(AgentNode[DepsT, NodeRunEndT]):
 
     request: _messages.ModelRequest
 
-    _result: HandleResponseNode[DepsT, NodeRunEndT] | None = field(default=None, repr=False)
+    _result: CallToolsNode[DepsT, NodeRunEndT] | None = field(default=None, repr=False)
     _did_stream: bool = field(default=False, repr=False)
 
     async def run(
         self, ctx: GraphRunContext[GraphAgentState, GraphAgentDeps[DepsT, NodeRunEndT]]
-    ) -> HandleResponseNode[DepsT, NodeRunEndT]:
+    ) -> CallToolsNode[DepsT, NodeRunEndT]:
         if self._result is not None:
             return self._result
 
@@ -307,7 +307,7 @@ async def _stream(
 
     async def _make_request(
         self, ctx: GraphRunContext[GraphAgentState, GraphAgentDeps[DepsT, NodeRunEndT]]
-    ) -> HandleResponseNode[DepsT, NodeRunEndT]:
+    ) -> CallToolsNode[DepsT, NodeRunEndT]:
         if self._result is not None:
             return self._result
 
@@ -344,7 +344,7 @@ def _finish_handling(
         ctx: GraphRunContext[GraphAgentState, GraphAgentDeps[DepsT, NodeRunEndT]],
         response: _messages.ModelResponse,
         usage: _usage.Usage,
-    ) -> HandleResponseNode[DepsT, NodeRunEndT]:
+    ) -> CallToolsNode[DepsT, NodeRunEndT]:
         # Update usage
         ctx.state.usage.incr(usage, requests=0)
         if ctx.deps.usage_limits:
@@ -354,13 +354,13 @@ def _finish_handling(
         ctx.state.message_history.append(response)
 
         # Set the `_result` attribute since we can't use `return` in an async iterator
-        self._result = HandleResponseNode(response)
+        self._result = CallToolsNode(response)
 
         return self._result
 
 
 @dataclasses.dataclass
-class HandleResponseNode(AgentNode[DepsT, NodeRunEndT]):
+class CallToolsNode(AgentNode[DepsT, NodeRunEndT]):
     """Process a model response, and decide whether to end the run or make a new request."""
 
     model_response: _messages.ModelResponse
@@ -716,7 +716,7 @@ def build_agent_graph(
     nodes = (
         UserPromptNode[DepsT],
         ModelRequestNode[DepsT],
-        HandleResponseNode[DepsT],
+        CallToolsNode[DepsT],
     )
     graph = Graph[GraphAgentState, GraphAgentDeps[DepsT, Any], result.FinalResult[ResultT]](
         nodes=nodes,

pydantic_ai_slim/pydantic_ai/agent.py

@@ -42,7 +42,7 @@
 # Re-exporting like this improves auto-import behavior in PyCharm
 capture_run_messages = _agent_graph.capture_run_messages
 EndStrategy = _agent_graph.EndStrategy
-HandleResponseNode = _agent_graph.HandleResponseNode
+CallToolsNode = _agent_graph.CallToolsNode
 ModelRequestNode = _agent_graph.ModelRequestNode
 UserPromptNode = _agent_graph.UserPromptNode
 
@@ -52,7 +52,7 @@
     'AgentRunResult',
     'capture_run_messages',
     'EndStrategy',
-    'HandleResponseNode',
+    'CallToolsNode',
     'ModelRequestNode',
     'UserPromptNode',
 )
@@ -362,7 +362,7 @@ async def main():
                         kind='request',
                     )
                 ),
-                HandleResponseNode(
+                CallToolsNode(
                     model_response=ModelResponse(
                         parts=[TextPart(content='Paris', part_kind='text')],
                         model_name='gpt-4o',
@@ -1183,14 +1183,14 @@ def is_model_request_node(
         return isinstance(node, _agent_graph.ModelRequestNode)
 
     @staticmethod
-    def is_handle_response_node(
+    def is_call_tools_node(
         node: _agent_graph.AgentNode[T, S] | End[result.FinalResult[S]],
-    ) -> TypeGuard[_agent_graph.HandleResponseNode[T, S]]:
-        """Check if the node is a `HandleResponseNode`, narrowing the type if it is.
+    ) -> TypeGuard[_agent_graph.CallToolsNode[T, S]]:
+        """Check if the node is a `CallToolsNode`, narrowing the type if it is.
 
         This method preserves the generic parameters while narrowing the type, unlike a direct call to `isinstance`.
         """
-        return isinstance(node, _agent_graph.HandleResponseNode)
+        return isinstance(node, _agent_graph.CallToolsNode)
 
     @staticmethod
     def is_user_prompt_node(
@@ -1250,7 +1250,7 @@ async def main():
                     kind='request',
                 )
             ),
-            HandleResponseNode(
+            CallToolsNode(
                 model_response=ModelResponse(
                     parts=[TextPart(content='Paris', part_kind='text')],
                     model_name='gpt-4o',
@@ -1374,7 +1374,7 @@ async def main():
                             kind='request',
                         )
                     ),
-                    HandleResponseNode(
+                    CallToolsNode(
                         model_response=ModelResponse(
                             parts=[TextPart(content='Paris', part_kind='text')],
                             model_name='gpt-4o',