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: 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  ```
164  
165  Initialize the ToolInvoker component.
166  
167  **Arguments**:
168  
169  - `tools`: A list of Tool and/or Toolset objects, 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.warm_up"></a>
191  
192  #### ToolInvoker.warm\_up
193  
194  ```python
195  def warm_up()
196  ```
197  
198  Warm up the tool invoker.
199  
200  This will warm up the tools registered in the tool invoker.
201  This method is idempotent and will only warm up the tools once.
202  
203  <a id="tool_invoker.ToolInvoker.run"></a>
204  
205  #### ToolInvoker.run
206  
207  ```python
208  @component.output_types(tool_messages=list[ChatMessage], state=State)
209  def run(messages: list[ChatMessage],
210          state: State | None = None,
211          streaming_callback: StreamingCallbackT | None = None,
212          *,
213          enable_streaming_callback_passthrough: bool | None = None,
214          tools: ToolsType | None = None) -> dict[str, Any]
215  ```
216  
217  Processes ChatMessage objects containing tool calls and invokes the corresponding tools, if available.
218  
219  **Arguments**:
220  
221  - `messages`: A list of ChatMessage objects.
222  - `state`: The runtime state that should be used by the tools.
223  - `streaming_callback`: A callback function that will be called to emit tool results.
224  Note that the result is only emitted once it becomes available — it is not
225  streamed incrementally in real time.
226  - `enable_streaming_callback_passthrough`: If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
227  This allows tools to stream their results back to the client.
228  Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
229  If False, the `streaming_callback` will not be passed to the tool invocation.
230  If None, the value from the constructor will be used.
231  - `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
232  If set, it will override the `tools` parameter provided during initialization.
233  
234  **Raises**:
235  
236  - `ToolNotFoundException`: If the tool is not found in the list of available tools and `raise_on_failure` is True.
237  - `ToolInvocationError`: If the tool invocation fails and `raise_on_failure` is True.
238  - `StringConversionError`: If the conversion of the tool result to a string fails and `raise_on_failure` is True.
239  - `ToolOutputMergeError`: If merging tool outputs into state fails and `raise_on_failure` is True.
240  
241  **Returns**:
242  
243  A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role.
244  Each ChatMessage objects wraps the result of a tool invocation.
245  
246  <a id="tool_invoker.ToolInvoker.run_async"></a>
247  
248  #### ToolInvoker.run\_async
249  
250  ```python
251  @component.output_types(tool_messages=list[ChatMessage], state=State)
252  async def run_async(messages: list[ChatMessage],
253                      state: State | None = None,
254                      streaming_callback: StreamingCallbackT | None = None,
255                      *,
256                      enable_streaming_callback_passthrough: bool | None = None,
257                      tools: ToolsType | None = None) -> dict[str, Any]
258  ```
259  
260  Asynchronously processes ChatMessage objects containing tool calls.
261  
262  Multiple tool calls are performed concurrently.
263  
264  **Arguments**:
265  
266  - `messages`: A list of ChatMessage objects.
267  - `state`: The runtime state that should be used by the tools.
268  - `streaming_callback`: An asynchronous callback function that will be called to emit tool results.
269  Note that the result is only emitted once it becomes available — it is not
270  streamed incrementally in real time.
271  - `enable_streaming_callback_passthrough`: If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
272  This allows tools to stream their results back to the client.
273  Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
274  If False, the `streaming_callback` will not be passed to the tool invocation.
275  If None, the value from the constructor will be used.
276  - `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
277  If set, it will override the `tools` parameter provided during initialization.
278  
279  **Raises**:
280  
281  - `ToolNotFoundException`: If the tool is not found in the list of available tools and `raise_on_failure` is True.
282  - `ToolInvocationError`: If the tool invocation fails and `raise_on_failure` is True.
283  - `StringConversionError`: If the conversion of the tool result to a string fails and `raise_on_failure` is True.
284  - `ToolOutputMergeError`: If merging tool outputs into state fails and `raise_on_failure` is True.
285  
286  **Returns**:
287  
288  A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role.
289  Each ChatMessage objects wraps the result of a tool invocation.
290  
291  <a id="tool_invoker.ToolInvoker.to_dict"></a>
292  
293  #### ToolInvoker.to\_dict
294  
295  ```python
296  def to_dict() -> dict[str, Any]
297  ```
298  
299  Serializes the component to a dictionary.
300  
301  **Returns**:
302  
303  Dictionary with serialized data.
304  
305  <a id="tool_invoker.ToolInvoker.from_dict"></a>
306  
307  #### ToolInvoker.from\_dict
308  
309  ```python
310  @classmethod
311  def from_dict(cls, data: dict[str, Any]) -> "ToolInvoker"
312  ```
313  
314  Deserializes the component from a dictionary.
315  
316  **Arguments**:
317  
318  - `data`: The dictionary to deserialize from.
319  
320  **Returns**:
321  
322  The deserialized component.
323