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 9 ## tool_invoker 10 11 ### ToolInvokerError 12 13 Bases: <code>Exception</code> 14 15 Base exception class for ToolInvoker errors. 16 17 ### ToolNotFoundException 18 19 Bases: <code>ToolInvokerError</code> 20 21 Exception raised when a tool is not found in the list of available tools. 22 23 ### StringConversionError 24 25 Bases: <code>ToolInvokerError</code> 26 27 Exception raised when the conversion of a tool result to a string fails. 28 29 ### ResultConversionError 30 31 Bases: <code>ToolInvokerError</code> 32 33 Exception raised when the conversion of a tool output to a result fails. 34 35 ### ToolOutputMergeError 36 37 Bases: <code>ToolInvokerError</code> 38 39 Exception raised when merging tool outputs into state fails. 40 41 #### from_exception 42 43 ```python 44 from_exception(tool_name: str, error: Exception) -> ToolOutputMergeError 45 ``` 46 47 Create a ToolOutputMergeError from an exception. 48 49 ### ToolInvoker 50 51 Invokes tools based on prepared tool calls and returns the results as a list of ChatMessage objects. 52 53 Also handles reading/writing from a shared `State`. 54 At initialization, the ToolInvoker component is provided with a list of available tools. 55 At runtime, the component processes a list of ChatMessage object containing tool calls 56 and invokes the corresponding tools. 57 The results of the tool invocations are returned as a list of ChatMessage objects with tool role. 58 59 Usage example: 60 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 117 ````python 118 from haystack.dataclasses import ChatMessage, ToolCall 119 from haystack.tools import Tool, Toolset 120 from haystack.components.tools import ToolInvoker 121 122 # Tool definition 123 def dummy_weather_function(city: str): 124 return f"The weather in {city} is 20 degrees." 125 126 parameters = {"type": "object", 127 "properties": {"city": {"type": "string"}}, 128 "required": ["city"]} 129 130 tool = Tool(name="weather_tool", 131 description="A tool to get the weather", 132 function=dummy_weather_function, 133 parameters=parameters) 134 135 # Create a Toolset 136 toolset = Toolset([tool]) 137 138 # Usually, the ChatMessage with tool_calls is generated by a Language Model 139 # Here, we create it manually for demonstration purposes 140 tool_call = ToolCall( 141 tool_name="weather_tool", 142 arguments={"city": "Berlin"} 143 ) 144 message = ChatMessage.from_assistant(tool_calls=[tool_call]) 145 146 # ToolInvoker initialization and run with Toolset 147 invoker = ToolInvoker(tools=toolset) 148 result = invoker.run(messages=[message]) 149 150 print(result) 151 152 153 154 155 156 157 158 159 160 161 162 163 #### __init__ 164 165 ```python 166 __init__( 167 tools: ToolsType, 168 raise_on_failure: bool = True, 169 convert_result_to_json_string: bool = False, 170 streaming_callback: StreamingCallbackT | None = None, 171 *, 172 enable_streaming_callback_passthrough: bool = False, 173 max_workers: int = 4 174 ) 175 ```` 176 177 Initialize the ToolInvoker component. 178 179 **Parameters:** 180 181 - **tools** (<code>ToolsType</code>) – A list of Tool and/or Toolset objects, or a Toolset instance that can resolve tools. 182 - **raise_on_failure** (<code>bool</code>) – If True, the component will raise an exception in case of errors 183 (tool not found, tool invocation errors, tool result conversion errors). 184 If False, the component will return a ChatMessage object with `error=True` 185 and a description of the error in `result`. 186 - **convert_result_to_json_string** (<code>bool</code>) – If True, the tool invocation result will be converted to a string using `json.dumps`. 187 If False, the tool invocation result will be converted to a string using `str`. 188 - **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that will be called to emit tool results. 189 Note that the result is only emitted once it becomes available — it is not 190 streamed incrementally in real time. 191 - **enable_streaming_callback_passthrough** (<code>bool</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. 192 This allows tools to stream their results back to the client. 193 Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. 194 If False, the `streaming_callback` will not be passed to the tool invocation. 195 - **max_workers** (<code>int</code>) – The maximum number of workers to use in the thread pool executor. 196 This also decides the maximum number of concurrent tool invocations. 197 198 **Raises:** 199 200 - <code>ValueError</code> – If no tools are provided or if duplicate tool names are found. 201 202 #### warm_up 203 204 ```python 205 warm_up() 206 ``` 207 208 Warm up the tool invoker. 209 210 This will warm up the tools registered in the tool invoker. 211 This method is idempotent and will only warm up the tools once. 212 213 #### run 214 215 ```python 216 run( 217 messages: list[ChatMessage], 218 state: State | None = None, 219 streaming_callback: StreamingCallbackT | None = None, 220 *, 221 enable_streaming_callback_passthrough: bool | None = None, 222 tools: ToolsType | None = None 223 ) -> dict[str, Any] 224 ``` 225 226 Processes ChatMessage objects containing tool calls and invokes the corresponding tools, if available. 227 228 **Parameters:** 229 230 - **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects. 231 - **state** (<code>State | None</code>) – The runtime state that should be used by the tools. 232 - **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that will be called to emit tool results. 233 Note that the result is only emitted once it becomes available — it is not 234 streamed incrementally in real time. 235 - **enable_streaming_callback_passthrough** (<code>bool | None</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. 236 This allows tools to stream their results back to the client. 237 Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. 238 If False, the `streaming_callback` will not be passed to the tool invocation. 239 If None, the value from the constructor will be used. 240 - **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. 241 If set, it will override the `tools` parameter provided during initialization. 242 243 **Returns:** 244 245 - <code>dict\[str, Any\]</code> – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role. 246 Each ChatMessage objects wraps the result of a tool invocation. 247 248 **Raises:** 249 250 - <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True. 251 - <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True. 252 - <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True. 253 - <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True. 254 255 #### run_async 256 257 ```python 258 run_async( 259 messages: list[ChatMessage], 260 state: State | None = None, 261 streaming_callback: StreamingCallbackT | None = None, 262 *, 263 enable_streaming_callback_passthrough: bool | None = None, 264 tools: ToolsType | None = None 265 ) -> dict[str, Any] 266 ``` 267 268 Asynchronously processes ChatMessage objects containing tool calls. 269 270 Multiple tool calls are performed concurrently. 271 272 **Parameters:** 273 274 - **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects. 275 - **state** (<code>State | None</code>) – The runtime state that should be used by the tools. 276 - **streaming_callback** (<code>StreamingCallbackT | None</code>) – An asynchronous callback function that will be called to emit tool results. 277 Note that the result is only emitted once it becomes available — it is not 278 streamed incrementally in real time. 279 - **enable_streaming_callback_passthrough** (<code>bool | None</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. 280 This allows tools to stream their results back to the client. 281 Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. 282 If False, the `streaming_callback` will not be passed to the tool invocation. 283 If None, the value from the constructor will be used. 284 - **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. 285 If set, it will override the `tools` parameter provided during initialization. 286 287 **Returns:** 288 289 - <code>dict\[str, Any\]</code> – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role. 290 Each ChatMessage objects wraps the result of a tool invocation. 291 292 **Raises:** 293 294 - <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True. 295 - <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True. 296 - <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True. 297 - <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True. 298 299 #### to_dict 300 301 ```python 302 to_dict() -> dict[str, Any] 303 ``` 304 305 Serializes the component to a dictionary. 306 307 **Returns:** 308 309 - <code>dict\[str, Any\]</code> – Dictionary with serialized data. 310 311 #### from_dict 312 313 ```python 314 from_dict(data: dict[str, Any]) -> ToolInvoker 315 ``` 316 317 Deserializes the component from a dictionary. 318 319 **Parameters:** 320 321 - **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from. 322 323 **Returns:** 324 325 - <code>ToolInvoker</code> – The deserialized component.