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 #### __init__ 153 154 ```python 155 __init__( 156 tools: ToolsType, 157 raise_on_failure: bool = True, 158 convert_result_to_json_string: bool = False, 159 streaming_callback: StreamingCallbackT | None = None, 160 *, 161 enable_streaming_callback_passthrough: bool = False, 162 max_workers: int = 4 163 ) -> None 164 ```` 165 166 Initialize the ToolInvoker component. 167 168 **Parameters:** 169 170 - **tools** (<code>ToolsType</code>) – A list of Tool and/or Toolset objects, or a Toolset instance that can resolve tools. 171 - **raise_on_failure** (<code>bool</code>) – If True, the component will raise an exception in case of errors 172 (tool not found, tool invocation errors, tool result conversion errors). 173 If False, the component will return a ChatMessage object with `error=True` 174 and a description of the error in `result`. 175 - **convert_result_to_json_string** (<code>bool</code>) – If True, the tool invocation result will be converted to a string using `json.dumps`. 176 If False, the tool invocation result will be converted to a string using `str`. 177 - **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that will be called to emit tool results. 178 Note that the result is only emitted once it becomes available — it is not 179 streamed incrementally in real time. 180 - **enable_streaming_callback_passthrough** (<code>bool</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. 181 This allows tools to stream their results back to the client. 182 Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. 183 If False, the `streaming_callback` will not be passed to the tool invocation. 184 - **max_workers** (<code>int</code>) – The maximum number of workers to use in the thread pool executor. 185 This also decides the maximum number of concurrent tool invocations. 186 187 **Raises:** 188 189 - <code>ValueError</code> – If no tools are provided or if duplicate tool names are found. 190 191 #### warm_up 192 193 ```python 194 warm_up() -> None 195 ``` 196 197 Warm up the tool invoker. 198 199 This will warm up the tools registered in the tool invoker. 200 This method is idempotent and will only warm up the tools once. 201 202 #### run 203 204 ```python 205 run( 206 messages: list[ChatMessage], 207 state: State | None = None, 208 streaming_callback: StreamingCallbackT | None = None, 209 *, 210 enable_streaming_callback_passthrough: bool | None = None, 211 tools: ToolsType | None = None 212 ) -> dict[str, Any] 213 ``` 214 215 Processes ChatMessage objects containing tool calls and invokes the corresponding tools, if available. 216 217 **Parameters:** 218 219 - **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects. 220 - **state** (<code>State | None</code>) – The runtime state that should be used by the tools. 221 - **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that will be called to emit tool results. 222 Note that the result is only emitted once it becomes available — it is not 223 streamed incrementally in real time. 224 - **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. 225 This allows tools to stream their results back to the client. 226 Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. 227 If False, the `streaming_callback` will not be passed to the tool invocation. 228 If None, the value from the constructor will be used. 229 - **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. 230 If set, it will override the `tools` parameter provided during initialization. 231 232 **Returns:** 233 234 - <code>dict\[str, Any\]</code> – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role. 235 Each ChatMessage objects wraps the result of a tool invocation. 236 237 **Raises:** 238 239 - <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True. 240 - <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True. 241 - <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True. 242 - <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True. 243 244 #### run_async 245 246 ```python 247 run_async( 248 messages: list[ChatMessage], 249 state: State | None = None, 250 streaming_callback: StreamingCallbackT | None = None, 251 *, 252 enable_streaming_callback_passthrough: bool | None = None, 253 tools: ToolsType | None = None 254 ) -> dict[str, Any] 255 ``` 256 257 Asynchronously processes ChatMessage objects containing tool calls. 258 259 Multiple tool calls are performed concurrently. 260 261 **Parameters:** 262 263 - **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects. 264 - **state** (<code>State | None</code>) – The runtime state that should be used by the tools. 265 - **streaming_callback** (<code>StreamingCallbackT | None</code>) – An asynchronous callback function that will be called to emit tool results. 266 Note that the result is only emitted once it becomes available — it is not 267 streamed incrementally in real time. 268 - **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. 269 This allows tools to stream their results back to the client. 270 Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. 271 If False, the `streaming_callback` will not be passed to the tool invocation. 272 If None, the value from the constructor will be used. 273 - **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. 274 If set, it will override the `tools` parameter provided during initialization. 275 276 **Returns:** 277 278 - <code>dict\[str, Any\]</code> – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role. 279 Each ChatMessage objects wraps the result of a tool invocation. 280 281 **Raises:** 282 283 - <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True. 284 - <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True. 285 - <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True. 286 - <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True. 287 288 #### to_dict 289 290 ```python 291 to_dict() -> dict[str, Any] 292 ``` 293 294 Serializes the component to a dictionary. 295 296 **Returns:** 297 298 - <code>dict\[str, Any\]</code> – Dictionary with serialized data. 299 300 #### from_dict 301 302 ```python 303 from_dict(data: dict[str, Any]) -> ToolInvoker 304 ``` 305 306 Deserializes the component from a dictionary. 307 308 **Parameters:** 309 310 - **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from. 311 312 **Returns:** 313 314 - <code>ToolInvoker</code> – The deserialized component.