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