1  ---
  2  title: "Agents"
  3  id: experimental-agents-api
  4  description: "Tool-using agents with provider-agnostic chat model support."
  5  slug: "/experimental-agents-api"
  6  ---
  7  
  8  <a id="haystack_experimental.components.agents.agent"></a>
  9  
 10  ## Module haystack\_experimental.components.agents.agent
 11  
 12  <a id="haystack_experimental.components.agents.agent.Agent"></a>
 13  
 14  ### Agent
 15  
 16  A Haystack component that implements a tool-using agent with provider-agnostic chat model support.
 17  
 18  NOTE: This class extends Haystack's Agent component to add support for human-in-the-loop confirmation strategies.
 19  
 20  The component processes messages and executes tools until an exit condition is met.
 21  The exit condition can be triggered either by a direct text response or by invoking a specific designated tool.
 22  Multiple exit conditions can be specified.
 23  
 24  When you call an Agent without tools, it acts as a ChatGenerator, produces one response, then exits.
 25  
 26  ### Usage example
 27  ```python
 28  from haystack.components.generators.chat import OpenAIChatGenerator
 29  from haystack.dataclasses import ChatMessage
 30  from haystack.tools.tool import Tool
 31  
 32  from haystack_experimental.components.agents import Agent
 33  from haystack_experimental.components.agents.human_in_the_loop import (
 34      HumanInTheLoopStrategy,
 35      AlwaysAskPolicy,
 36      NeverAskPolicy,
 37      SimpleConsoleUI,
 38  )
 39  
 40  calculator_tool = Tool(name="calculator", description="A tool for performing mathematical calculations.", ...)
 41  search_tool = Tool(name="search", description="A tool for searching the web.", ...)
 42  
 43  agent = Agent(
 44      chat_generator=OpenAIChatGenerator(),
 45      tools=[calculator_tool, search_tool],
 46      confirmation_strategies={
 47          calculator_tool.name: HumanInTheLoopStrategy(
 48              confirmation_policy=NeverAskPolicy(), confirmation_ui=SimpleConsoleUI()
 49          ),
 50          search_tool.name: HumanInTheLoopStrategy(
 51              confirmation_policy=AlwaysAskPolicy(), confirmation_ui=SimpleConsoleUI()
 52          ),
 53      },
 54  )
 55  
 56  # Run the agent
 57  result = agent.run(
 58      messages=[ChatMessage.from_user("Find information about Haystack")]
 59  )
 60  
 61  assert "messages" in result  # Contains conversation history
 62  ```
 63  
 64  <a id="haystack_experimental.components.agents.agent.Agent.__init__"></a>
 65  
 66  #### Agent.\_\_init\_\_
 67  
 68  ```python
 69  def __init__(*,
 70               chat_generator: ChatGenerator,
 71               tools: ToolsType | None = None,
 72               system_prompt: str | None = None,
 73               exit_conditions: list[str] | None = None,
 74               state_schema: dict[str, Any] | None = None,
 75               max_agent_steps: int = 100,
 76               streaming_callback: StreamingCallbackT | None = None,
 77               raise_on_tool_invocation_failure: bool = False,
 78               confirmation_strategies: dict[str, ConfirmationStrategy]
 79               | None = None,
 80               tool_invoker_kwargs: dict[str, Any] | None = None,
 81               chat_message_store: ChatMessageStore | None = None,
 82               memory_store: MemoryStore | None = None) -> None
 83  ```
 84  
 85  Initialize the agent component.
 86  
 87  **Arguments**:
 88  
 89  - `chat_generator`: An instance of the chat generator that your agent should use. It must support tools.
 90  - `tools`: List of Tool objects or a Toolset that the agent can use.
 91  - `system_prompt`: System prompt for the agent.
 92  - `exit_conditions`: List of conditions that will cause the agent to return.
 93  Can include "text" if the agent should return when it generates a message without tool calls,
 94  or tool names that will cause the agent to return once the tool was executed. Defaults to ["text"].
 95  - `state_schema`: The schema for the runtime state used by the tools.
 96  - `max_agent_steps`: Maximum number of steps the agent will run before stopping. Defaults to 100.
 97  If the agent exceeds this number of steps, it will stop and return the current state.
 98  - `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM.
 99  The same callback can be configured to emit tool results when a tool is called.
100  - `raise_on_tool_invocation_failure`: Should the agent raise an exception when a tool invocation fails?
101  If set to False, the exception will be turned into a chat message and passed to the LLM.
102  - `tool_invoker_kwargs`: Additional keyword arguments to pass to the ToolInvoker.
103  - `chat_message_store`: The ChatMessageStore that the agent can use to store
104  and retrieve chat messages history.
105  - `memory_store`: The memory store that the agent can use to store and retrieve memories.
106  
107  **Raises**:
108  
109  - `TypeError`: If the chat_generator does not support tools parameter in its run method.
110  - `ValueError`: If the exit_conditions are not valid.
111  
112  <a id="haystack_experimental.components.agents.agent.Agent.run"></a>
113  
114  #### Agent.run
115  
116  ```python
117  def run(messages: list[ChatMessage],
118          streaming_callback: StreamingCallbackT | None = None,
119          *,
120          generation_kwargs: dict[str, Any] | None = None,
121          break_point: AgentBreakpoint | None = None,
122          snapshot: AgentSnapshot | None = None,
123          system_prompt: str | None = None,
124          tools: ToolsType | list[str] | None = None,
125          confirmation_strategy_context: dict[str, Any] | None = None,
126          chat_message_store_kwargs: dict[str, Any] | None = None,
127          memory_store_kwargs: dict[str, Any] | None = None,
128          **kwargs: Any) -> dict[str, Any]
129  ```
130  
131  Process messages and execute tools until an exit condition is met.
132  
133  **Arguments**:
134  
135  - `messages`: List of Haystack ChatMessage objects to process.
136  - `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM.
137  The same callback can be configured to emit tool results when a tool is called.
138  - `generation_kwargs`: Additional keyword arguments for LLM. These parameters will
139  override the parameters passed during component initialization.
140  - `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint
141  for "tool_invoker".
142  - `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
143  the relevant information to restart the Agent execution from where it left off.
144  - `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt.
145  - `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run.
146  When passing tool names, tools are selected from the Agent's originally configured tools.
147  - `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources
148  to confirmation strategies. Useful in web/server environments to provide per-request
149  objects (e.g., WebSocket connections, async queues, Redis pub/sub clients) that strategies
150  can use for non-blocking user interaction.
151  - `chat_message_store_kwargs`: Optional dictionary of keyword arguments to pass to the ChatMessageStore.
152  For example, it can include the `chat_history_id` and `last_k` parameters for retrieving chat history.
153  - `memory_store_kwargs`: Optional dictionary of keyword arguments to pass to the MemoryStore.
154  It can include:
155  - `user_id`: The user ID to search and add memories from.
156  - `run_id`: The run ID to search and add memories from.
157  - `agent_id`: The agent ID to search and add memories from.
158  - `search_criteria`: A dictionary of containing kwargs for the `search_memories` method.
159      This can include:
160      - `filters`: A dictionary of filters to search for memories.
161      - `query`: The query to search for memories.
162          Note: If you pass this, the user query passed to the agent will be
163          ignored for memory retrieval.
164      - `top_k`: The number of memories to return.
165      - `include_memory_metadata`: Whether to include the memory metadata in the ChatMessage.
166  - `kwargs`: Additional data to pass to the State schema used by the Agent.
167  The keys must match the schema defined in the Agent's `state_schema`.
168  
169  **Raises**:
170  
171  - `RuntimeError`: If the Agent component wasn't warmed up before calling `run()`.
172  - `BreakpointException`: If an agent breakpoint is triggered.
173  
174  **Returns**:
175  
176  A dictionary with the following keys:
177  - "messages": List of all messages exchanged during the agent's run.
178  - "last_message": The last message exchanged during the agent's run.
179  - Any additional keys defined in the `state_schema`.
180  
181  <a id="haystack_experimental.components.agents.agent.Agent.run_async"></a>
182  
183  #### Agent.run\_async
184  
185  ```python
186  async def run_async(messages: list[ChatMessage],
187                      streaming_callback: StreamingCallbackT | None = None,
188                      *,
189                      generation_kwargs: dict[str, Any] | None = None,
190                      break_point: AgentBreakpoint | None = None,
191                      snapshot: AgentSnapshot | None = None,
192                      system_prompt: str | None = None,
193                      tools: ToolsType | list[str] | None = None,
194                      confirmation_strategy_context: dict[str, Any]
195                      | None = None,
196                      chat_message_store_kwargs: dict[str, Any] | None = None,
197                      memory_store_kwargs: dict[str, Any] | None = None,
198                      **kwargs: Any) -> dict[str, Any]
199  ```
200  
201  Asynchronously process messages and execute tools until the exit condition is met.
202  
203  This is the asynchronous version of the `run` method. It follows the same logic but uses
204  asynchronous operations where possible, such as calling the `run_async` method of the ChatGenerator
205  if available.
206  
207  **Arguments**:
208  
209  - `messages`: List of Haystack ChatMessage objects to process.
210  - `streaming_callback`: An asynchronous callback that will be invoked when a response is streamed from the
211  LLM. The same callback can be configured to emit tool results when a tool is called.
212  - `generation_kwargs`: Additional keyword arguments for LLM. These parameters will
213  override the parameters passed during component initialization.
214  - `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint
215  for "tool_invoker".
216  - `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
217  the relevant information to restart the Agent execution from where it left off.
218  - `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt.
219  - `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run.
220  - `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources
221  to confirmation strategies. Useful in web/server environments to provide per-request
222  objects (e.g., WebSocket connections, async queues, Redis pub/sub clients) that strategies
223  can use for non-blocking user interaction.
224  - `chat_message_store_kwargs`: Optional dictionary of keyword arguments to pass to the ChatMessageStore.
225  For example, it can include the `chat_history_id` and `last_k` parameters for retrieving chat history.
226  - `kwargs`: Additional data to pass to the State schema used by the Agent.
227  - `memory_store_kwargs`: Optional dictionary of keyword arguments to pass to the MemoryStore.
228  It can include:
229  - `user_id`: The user ID to search and add memories from.
230  - `run_id`: The run ID to search and add memories from.
231  - `agent_id`: The agent ID to search and add memories from.
232  - `search_criteria`: A dictionary of containing kwargs for the `search_memories` method.
233      This can include:
234      - `filters`: A dictionary of filters to search for memories.
235      - `query`: The query to search for memories.
236          Note: If you pass this, the user query passed to the agent will be
237          ignored for memory retrieval.
238      - `top_k`: The number of memories to return.
239      - `include_memory_metadata`: Whether to include the memory metadata in the ChatMessage.
240  - `kwargs`: Additional data to pass to the State schema used by the Agent.
241  The keys must match the schema defined in the Agent's `state_schema`.
242  
243  **Raises**:
244  
245  - `RuntimeError`: If the Agent component wasn't warmed up before calling `run_async()`.
246  - `BreakpointException`: If an agent breakpoint is triggered.
247  
248  **Returns**:
249  
250  A dictionary with the following keys:
251  - "messages": List of all messages exchanged during the agent's run.
252  - "last_message": The last message exchanged during the agent's run.
253  - Any additional keys defined in the `state_schema`.
254  
255  <a id="haystack_experimental.components.agents.agent.Agent.to_dict"></a>
256  
257  #### Agent.to\_dict
258  
259  ```python
260  def to_dict() -> dict[str, Any]
261  ```
262  
263  Serialize the component to a dictionary.
264  
265  **Returns**:
266  
267  Dictionary with serialized data
268  
269  <a id="haystack_experimental.components.agents.agent.Agent.from_dict"></a>
270  
271  #### Agent.from\_dict
272  
273  ```python
274  @classmethod
275  def from_dict(cls, data: dict[str, Any]) -> "Agent"
276  ```
277  
278  Deserialize the agent from a dictionary.
279  
280  **Arguments**:
281  
282  - `data`: Dictionary to deserialize from
283  
284  **Returns**:
285  
286  Deserialized agent
287  
288  <a id="haystack_experimental.components.agents.human_in_the_loop.breakpoint"></a>
289  
290  ## Module haystack\_experimental.components.agents.human\_in\_the\_loop.breakpoint
291  
292  <a id="haystack_experimental.components.agents.human_in_the_loop.breakpoint.get_tool_calls_and_descriptions_from_snapshot"></a>
293  
294  #### get\_tool\_calls\_and\_descriptions\_from\_snapshot
295  
296  ```python
297  def get_tool_calls_and_descriptions_from_snapshot(
298          agent_snapshot: AgentSnapshot,
299          breakpoint_tool_only: bool = True
300  ) -> tuple[list[dict], dict[str, str]]
301  ```
302  
303  Extract tool calls and tool descriptions from an AgentSnapshot.
304  
305  By default, only the tool call that caused the breakpoint is processed and its arguments are reconstructed.
306  This is useful for scenarios where you want to present the relevant tool call and its description
307  to a human for confirmation before execution.
308  
309  **Arguments**:
310  
311  - `agent_snapshot`: The AgentSnapshot from which to extract tool calls and descriptions.
312  - `breakpoint_tool_only`: If True, only the tool call that caused the breakpoint is returned. If False, all tool
313  calls are returned.
314  
315  **Returns**:
316  
317  A tuple containing a list of tool call dictionaries and a dictionary of tool descriptions
318  
319  <a id="haystack_experimental.components.agents.human_in_the_loop.errors"></a>
320  
321  ## Module haystack\_experimental.components.agents.human\_in\_the\_loop.errors
322  
323  <a id="haystack_experimental.components.agents.human_in_the_loop.errors.HITLBreakpointException"></a>
324  
325  ### HITLBreakpointException
326  
327  Exception raised when a tool execution is paused by a ConfirmationStrategy (e.g. BreakpointConfirmationStrategy).
328  
329  <a id="haystack_experimental.components.agents.human_in_the_loop.errors.HITLBreakpointException.__init__"></a>
330  
331  #### HITLBreakpointException.\_\_init\_\_
332  
333  ```python
334  def __init__(message: str,
335               tool_name: str,
336               snapshot_file_path: str,
337               tool_call_id: str | None = None) -> None
338  ```
339  
340  Initialize the HITLBreakpointException.
341  
342  **Arguments**:
343  
344  - `message`: The exception message.
345  - `tool_name`: The name of the tool whose execution is paused.
346  - `snapshot_file_path`: The file path to the saved pipeline snapshot.
347  - `tool_call_id`: Optional unique identifier for the tool call. This can be used to track and correlate
348  the decision with a specific tool invocation.
349  
350  <a id="haystack_experimental.components.agents.human_in_the_loop.strategies"></a>
351  
352  ## Module haystack\_experimental.components.agents.human\_in\_the\_loop.strategies
353  
354  <a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy"></a>
355  
356  ### BreakpointConfirmationStrategy
357  
358  Confirmation strategy that raises a tool breakpoint exception to pause execution and gather user feedback.
359  
360  This strategy is designed for scenarios where immediate user interaction is not possible.
361  When a tool execution requires confirmation, it raises an `HITLBreakpointException`, which is caught by the Agent.
362  The Agent then serialize its current state, including the tool call details. This information can then be used to
363  notify a user to review and confirm the tool execution.
364  
365  <a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.__init__"></a>
366  
367  #### BreakpointConfirmationStrategy.\_\_init\_\_
368  
369  ```python
370  def __init__(snapshot_file_path: str) -> None
371  ```
372  
373  Initialize the BreakpointConfirmationStrategy.
374  
375  **Arguments**:
376  
377  - `snapshot_file_path`: The path to the directory that the snapshot should be saved.
378  
379  <a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.run"></a>
380  
381  #### BreakpointConfirmationStrategy.run
382  
383  ```python
384  def run(
385      *,
386      tool_name: str,
387      tool_description: str,
388      tool_params: dict[str, Any],
389      tool_call_id: str | None = None,
390      confirmation_strategy_context: dict[str, Any] | None = None
391  ) -> ToolExecutionDecision
392  ```
393  
394  Run the breakpoint confirmation strategy for a given tool and its parameters.
395  
396  **Arguments**:
397  
398  - `tool_name`: The name of the tool to be executed.
399  - `tool_description`: The description of the tool.
400  - `tool_params`: The parameters to be passed to the tool.
401  - `tool_call_id`: Optional unique identifier for the tool call. This can be used to track and correlate the decision with a
402  specific tool invocation.
403  - `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources. Not used by this strategy but included for
404  interface compatibility.
405  
406  **Raises**:
407  
408  - `HITLBreakpointException`: Always raises an `HITLBreakpointException` exception to signal that user confirmation is required.
409  
410  **Returns**:
411  
412  This method does not return; it always raises an exception.
413  
414  <a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.run_async"></a>
415  
416  #### BreakpointConfirmationStrategy.run\_async
417  
418  ```python
419  async def run_async(
420      *,
421      tool_name: str,
422      tool_description: str,
423      tool_params: dict[str, Any],
424      tool_call_id: str | None = None,
425      confirmation_strategy_context: dict[str, Any] | None = None
426  ) -> ToolExecutionDecision
427  ```
428  
429  Async version of run. Calls the sync run() method.
430  
431  **Arguments**:
432  
433  - `tool_name`: The name of the tool to be executed.
434  - `tool_description`: The description of the tool.
435  - `tool_params`: The parameters to be passed to the tool.
436  - `tool_call_id`: Optional unique identifier for the tool call.
437  - `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources.
438  
439  **Raises**:
440  
441  - `HITLBreakpointException`: Always raises an `HITLBreakpointException` exception to signal that user confirmation is required.
442  
443  **Returns**:
444  
445  This method does not return; it always raises an exception.
446  
447  <a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.to_dict"></a>
448  
449  #### BreakpointConfirmationStrategy.to\_dict
450  
451  ```python
452  def to_dict() -> dict[str, Any]
453  ```
454  
455  Serializes the BreakpointConfirmationStrategy to a dictionary.
456  
457  <a id="haystack_experimental.components.agents.human_in_the_loop.strategies.BreakpointConfirmationStrategy.from_dict"></a>
458  
459  #### BreakpointConfirmationStrategy.from\_dict
460  
461  ```python
462  @classmethod
463  def from_dict(cls, data: dict[str, Any]) -> "BreakpointConfirmationStrategy"
464  ```
465  
466  Deserializes the BreakpointConfirmationStrategy from a dictionary.
467  
468  **Arguments**:
469  
470  - `data`: Dictionary to deserialize from.
471  
472  **Returns**:
473  
474  Deserialized BreakpointConfirmationStrategy.
475