tool_components_api.md
1 --- 2 title: Tool Components 3 id: tool-components-api 4 description: Components related to Tool Calling. 5 slug: "/tool-components-api" 6 --- 7 8 <a id="tool_invoker"></a> 9 10 # Module tool\_invoker 11 12 <a id="tool_invoker.ToolInvokerError"></a> 13 14 ## ToolInvokerError 15 16 Base exception class for ToolInvoker errors. 17 18 <a id="tool_invoker.ToolNotFoundException"></a> 19 20 ## ToolNotFoundException 21 22 Exception raised when a tool is not found in the list of available tools. 23 24 <a id="tool_invoker.StringConversionError"></a> 25 26 ## StringConversionError 27 28 Exception raised when the conversion of a tool result to a string fails. 29 30 <a id="tool_invoker.ToolOutputMergeError"></a> 31 32 ## ToolOutputMergeError 33 34 Exception raised when merging tool outputs into state fails. 35 36 <a id="tool_invoker.ToolOutputMergeError.from_exception"></a> 37 38 #### ToolOutputMergeError.from\_exception 39 40 ```python 41 @classmethod 42 def from_exception(cls, tool_name: str, 43 error: Exception) -> "ToolOutputMergeError" 44 ``` 45 46 Create a ToolOutputMergeError from an exception. 47 48 <a id="tool_invoker.ToolInvoker"></a> 49 50 ## ToolInvoker 51 52 Invokes tools based on prepared tool calls and returns the results as a list of ChatMessage objects. 53 54 Also handles reading/writing from a shared `State`. 55 At initialization, the ToolInvoker component is provided with a list of available tools. 56 At runtime, the component processes a list of ChatMessage object containing tool calls 57 and invokes the corresponding tools. 58 The results of the tool invocations are returned as a list of ChatMessage objects with tool role. 59 60 Usage example: 61 ```python 62 from haystack.dataclasses import ChatMessage, ToolCall 63 from haystack.tools import Tool 64 from haystack.components.tools import ToolInvoker 65 66 # Tool definition 67 def dummy_weather_function(city: str): 68 return f"The weather in {city} is 20 degrees." 69 70 parameters = {"type": "object", 71 "properties": {"city": {"type": "string"}}, 72 "required": ["city"]} 73 74 tool = Tool(name="weather_tool", 75 description="A tool to get the weather", 76 function=dummy_weather_function, 77 parameters=parameters) 78 79 # Usually, the ChatMessage with tool_calls is generated by a Language Model 80 # Here, we create it manually for demonstration purposes 81 tool_call = ToolCall( 82 tool_name="weather_tool", 83 arguments={"city": "Berlin"} 84 ) 85 message = ChatMessage.from_assistant(tool_calls=[tool_call]) 86 87 # ToolInvoker initialization and run 88 invoker = ToolInvoker(tools=[tool]) 89 result = invoker.run(messages=[message]) 90 91 print(result) 92 ``` 93 94 ``` 95 >> { 96 >> 'tool_messages': [ 97 >> ChatMessage( 98 >> _role=<ChatRole.TOOL: 'tool'>, 99 >> _content=[ 100 >> ToolCallResult( 101 >> result='"The weather in Berlin is 20 degrees."', 102 >> origin=ToolCall( 103 >> tool_name='weather_tool', 104 >> arguments={'city': 'Berlin'}, 105 >> id=None 106 >> ) 107 >> ) 108 >> ], 109 >> _meta={} 110 >> ) 111 >> ] 112 >> } 113 ``` 114 115 Usage example with a Toolset: 116 ```python 117 from haystack.dataclasses import ChatMessage, ToolCall 118 from haystack.tools import Tool, Toolset 119 from haystack.components.tools import ToolInvoker 120 121 # Tool definition 122 def dummy_weather_function(city: str): 123 return f"The weather in {city} is 20 degrees." 124 125 parameters = {"type": "object", 126 "properties": {"city": {"type": "string"}}, 127 "required": ["city"]} 128 129 tool = Tool(name="weather_tool", 130 description="A tool to get the weather", 131 function=dummy_weather_function, 132 parameters=parameters) 133 134 # Create a Toolset 135 toolset = Toolset([tool]) 136 137 # Usually, the ChatMessage with tool_calls is generated by a Language Model 138 # Here, we create it manually for demonstration purposes 139 tool_call = ToolCall( 140 tool_name="weather_tool", 141 arguments={"city": "Berlin"} 142 ) 143 message = ChatMessage.from_assistant(tool_calls=[tool_call]) 144 145 # ToolInvoker initialization and run with Toolset 146 invoker = ToolInvoker(tools=toolset) 147 result = invoker.run(messages=[message]) 148 149 print(result) 150 151 <a id="tool_invoker.ToolInvoker.__init__"></a> 152 153 #### ToolInvoker.\_\_init\_\_ 154 155 ```python 156 def __init__(tools: Union[list[Tool], Toolset], 157 raise_on_failure: bool = True, 158 convert_result_to_json_string: bool = False, 159 streaming_callback: Optional[StreamingCallbackT] = None, 160 *, 161 enable_streaming_callback_passthrough: bool = False, 162 max_workers: int = 4) 163 ``` 164 165 Initialize the ToolInvoker component. 166 167 **Arguments**: 168 169 - `tools`: A list of tools that can be invoked or a Toolset instance that can resolve tools. 170 - `raise_on_failure`: If True, the component will raise an exception in case of errors 171 (tool not found, tool invocation errors, tool result conversion errors). 172 If False, the component will return a ChatMessage object with `error=True` 173 and a description of the error in `result`. 174 - `convert_result_to_json_string`: If True, the tool invocation result will be converted to a string using `json.dumps`. 175 If False, the tool invocation result will be converted to a string using `str`. 176 - `streaming_callback`: A callback function that will be called to emit tool results. 177 Note that the result is only emitted once it becomes available — it is not 178 streamed incrementally in real time. 179 - `enable_streaming_callback_passthrough`: If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. 180 This allows tools to stream their results back to the client. 181 Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. 182 If False, the `streaming_callback` will not be passed to the tool invocation. 183 - `max_workers`: The maximum number of workers to use in the thread pool executor. 184 This also decides the maximum number of concurrent tool invocations. 185 186 **Raises**: 187 188 - `ValueError`: If no tools are provided or if duplicate tool names are found. 189 190 <a id="tool_invoker.ToolInvoker.run"></a> 191 192 #### ToolInvoker.run 193 194 ```python 195 @component.output_types(tool_messages=list[ChatMessage], state=State) 196 def run(messages: list[ChatMessage], 197 state: Optional[State] = None, 198 streaming_callback: Optional[StreamingCallbackT] = None, 199 *, 200 enable_streaming_callback_passthrough: Optional[bool] = None, 201 tools: Optional[Union[list[Tool], Toolset]] = None) -> dict[str, Any] 202 ``` 203 204 Processes ChatMessage objects containing tool calls and invokes the corresponding tools, if available. 205 206 **Arguments**: 207 208 - `messages`: A list of ChatMessage objects. 209 - `state`: The runtime state that should be used by the tools. 210 - `streaming_callback`: A callback function that will be called to emit tool results. 211 Note that the result is only emitted once it becomes available — it is not 212 streamed incrementally in real time. 213 - `enable_streaming_callback_passthrough`: If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. 214 This allows tools to stream their results back to the client. 215 Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. 216 If False, the `streaming_callback` will not be passed to the tool invocation. 217 If None, the value from the constructor will be used. 218 - `tools`: A list of tools to use for the tool invoker. If set, overrides the tools set in the constructor. 219 220 **Raises**: 221 222 - `ToolNotFoundException`: If the tool is not found in the list of available tools and `raise_on_failure` is True. 223 - `ToolInvocationError`: If the tool invocation fails and `raise_on_failure` is True. 224 - `StringConversionError`: If the conversion of the tool result to a string fails and `raise_on_failure` is True. 225 - `ToolOutputMergeError`: If merging tool outputs into state fails and `raise_on_failure` is True. 226 227 **Returns**: 228 229 A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role. 230 Each ChatMessage objects wraps the result of a tool invocation. 231 232 <a id="tool_invoker.ToolInvoker.run_async"></a> 233 234 #### ToolInvoker.run\_async 235 236 ```python 237 @component.output_types(tool_messages=list[ChatMessage], state=State) 238 async def run_async( 239 messages: list[ChatMessage], 240 state: Optional[State] = None, 241 streaming_callback: Optional[StreamingCallbackT] = None, 242 *, 243 enable_streaming_callback_passthrough: Optional[bool] = None, 244 tools: Optional[Union[list[Tool], Toolset]] = None) -> dict[str, Any] 245 ``` 246 247 Asynchronously processes ChatMessage objects containing tool calls. 248 249 Multiple tool calls are performed concurrently. 250 251 **Arguments**: 252 253 - `messages`: A list of ChatMessage objects. 254 - `state`: The runtime state that should be used by the tools. 255 - `streaming_callback`: An asynchronous callback function that will be called to emit tool results. 256 Note that the result is only emitted once it becomes available — it is not 257 streamed incrementally in real time. 258 - `enable_streaming_callback_passthrough`: If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. 259 This allows tools to stream their results back to the client. 260 Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. 261 If False, the `streaming_callback` will not be passed to the tool invocation. 262 If None, the value from the constructor will be used. 263 - `tools`: A list of tools to use for the tool invoker. If set, overrides the tools set in the constructor. 264 265 **Raises**: 266 267 - `ToolNotFoundException`: If the tool is not found in the list of available tools and `raise_on_failure` is True. 268 - `ToolInvocationError`: If the tool invocation fails and `raise_on_failure` is True. 269 - `StringConversionError`: If the conversion of the tool result to a string fails and `raise_on_failure` is True. 270 - `ToolOutputMergeError`: If merging tool outputs into state fails and `raise_on_failure` is True. 271 272 **Returns**: 273 274 A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role. 275 Each ChatMessage objects wraps the result of a tool invocation. 276 277 <a id="tool_invoker.ToolInvoker.to_dict"></a> 278 279 #### ToolInvoker.to\_dict 280 281 ```python 282 def to_dict() -> dict[str, Any] 283 ``` 284 285 Serializes the component to a dictionary. 286 287 **Returns**: 288 289 Dictionary with serialized data. 290 291 <a id="tool_invoker.ToolInvoker.from_dict"></a> 292 293 #### ToolInvoker.from\_dict 294 295 ```python 296 @classmethod 297 def from_dict(cls, data: dict[str, Any]) -> "ToolInvoker" 298 ``` 299 300 Deserializes the component from a dictionary. 301 302 **Arguments**: 303 304 - `data`: The dictionary to deserialize from. 305 306 **Returns**: 307 308 The deserialized component.