1  ---
  2  title: "Agents"
  3  id: agents-api
  4  description: "Tool-using agents with provider-agnostic chat model support."
  5  slug: "/agents-api"
  6  ---
  7  
  8  <a id="agent"></a>
  9  
 10  ## Module agent
 11  
 12  <a id="agent.Agent"></a>
 13  
 14  ### Agent
 15  
 16  A tool-using Agent powered by a large language model.
 17  
 18  The Agent processes messages and calls tools until it meets an exit condition.
 19  You can set one or more exit conditions to control when it stops.
 20  For example, it can stop after generating a response or after calling a tool.
 21  
 22  Without tools, the Agent works like a standard LLM that generates text. It produces one response and then stops.
 23  
 24  ### Usage examples
 25  
 26  This is an example agent that:
 27  1. Searches for tipping customs in France.
 28  2. Uses a calculator to compute tips based on its findings.
 29  3. Returns the final answer with its context.
 30  
 31  ```python
 32  from haystack.components.agents import Agent
 33  from haystack.components.generators.chat import OpenAIChatGenerator
 34  from haystack.dataclasses import ChatMessage
 35  from haystack.tools import Tool
 36  
 37  # Tool functions - in practice, these would have real implementations
 38  def search(query: str) -> str:
 39      '''Search for information on the web.'''
 40      # Placeholder: would call actual search API
 41      return "In France, a 15% service charge is typically included, but leaving 5-10% extra is appreciated."
 42  
 43  def calculator(operation: str, a: float, b: float) -> float:
 44      '''Perform mathematical calculations.'''
 45      if operation == "multiply":
 46          return a * b
 47      elif operation == "percentage":
 48          return (a / 100) * b
 49      return 0
 50  
 51  # Define tools with JSON Schema
 52  tools = [
 53      Tool(
 54          name="search",
 55          description="Searches for information on the web",
 56          parameters={
 57              "type": "object",
 58              "properties": {
 59                  "query": {"type": "string", "description": "The search query"}
 60              },
 61              "required": ["query"]
 62          },
 63          function=search
 64      ),
 65      Tool(
 66          name="calculator",
 67          description="Performs mathematical calculations",
 68          parameters={
 69              "type": "object",
 70              "properties": {
 71                  "operation": {"type": "string", "description": "Operation: multiply, percentage"},
 72                  "a": {"type": "number", "description": "First number"},
 73                  "b": {"type": "number", "description": "Second number"}
 74              },
 75              "required": ["operation", "a", "b"]
 76          },
 77          function=calculator
 78      )
 79  ]
 80  
 81  # Create and run the agent
 82  agent = Agent(
 83      chat_generator=OpenAIChatGenerator(),
 84      tools=tools
 85  )
 86  
 87  result = agent.run(
 88      messages=[ChatMessage.from_user("Calculate the appropriate tip for an €85 meal in France")]
 89  )
 90  
 91  print(result["messages"][-1].text)
 92  ```
 93  
 94  <a id="agent.Agent.__init__"></a>
 95  
 96  #### Agent.\_\_init\_\_
 97  
 98  ```python
 99  def __init__(
100      *,
101      chat_generator: ChatGenerator,
102      tools: ToolsType | None = None,
103      system_prompt: str | None = None,
104      exit_conditions: list[str] | None = None,
105      state_schema: dict[str, Any] | None = None,
106      max_agent_steps: int = 100,
107      streaming_callback: StreamingCallbackT | None = None,
108      raise_on_tool_invocation_failure: bool = False,
109      tool_invoker_kwargs: dict[str, Any] | None = None,
110      confirmation_strategies: dict[str, ConfirmationStrategy] | None = None
111  ) -> None
112  ```
113  
114  Initialize the agent component.
115  
116  **Arguments**:
117  
118  - `chat_generator`: An instance of the chat generator that your agent should use. It must support tools.
119  - `tools`: A list of Tool and/or Toolset objects, or a single Toolset that the agent can use.
120  - `system_prompt`: System prompt for the agent.
121  - `exit_conditions`: List of conditions that will cause the agent to return.
122  Can include "text" if the agent should return when it generates a message without tool calls,
123  or tool names that will cause the agent to return once the tool was executed. Defaults to ["text"].
124  - `state_schema`: The schema for the runtime state used by the tools.
125  - `max_agent_steps`: Maximum number of steps the agent will run before stopping. Defaults to 100.
126  If the agent exceeds this number of steps, it will stop and return the current state.
127  - `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM.
128  The same callback can be configured to emit tool results when a tool is called.
129  - `raise_on_tool_invocation_failure`: Should the agent raise an exception when a tool invocation fails?
130  If set to False, the exception will be turned into a chat message and passed to the LLM.
131  - `tool_invoker_kwargs`: Additional keyword arguments to pass to the ToolInvoker.
132  - `confirmation_strategies`: A dictionary mapping tool names to ConfirmationStrategy instances.
133  
134  **Raises**:
135  
136  - `TypeError`: If the chat_generator does not support tools parameter in its run method.
137  - `ValueError`: If the exit_conditions are not valid.
138  
139  <a id="agent.Agent.warm_up"></a>
140  
141  #### Agent.warm\_up
142  
143  ```python
144  def warm_up() -> None
145  ```
146  
147  Warm up the Agent.
148  
149  <a id="agent.Agent.to_dict"></a>
150  
151  #### Agent.to\_dict
152  
153  ```python
154  def to_dict() -> dict[str, Any]
155  ```
156  
157  Serialize the component to a dictionary.
158  
159  **Returns**:
160  
161  Dictionary with serialized data
162  
163  <a id="agent.Agent.from_dict"></a>
164  
165  #### Agent.from\_dict
166  
167  ```python
168  @classmethod
169  def from_dict(cls, data: dict[str, Any]) -> "Agent"
170  ```
171  
172  Deserialize the agent from a dictionary.
173  
174  **Arguments**:
175  
176  - `data`: Dictionary to deserialize from
177  
178  **Returns**:
179  
180  Deserialized agent
181  
182  <a id="agent.Agent.run"></a>
183  
184  #### Agent.run
185  
186  ```python
187  def run(messages: list[ChatMessage],
188          streaming_callback: StreamingCallbackT | None = None,
189          *,
190          generation_kwargs: dict[str, Any] | None = None,
191          break_point: AgentBreakpoint | None = None,
192          snapshot: AgentSnapshot | None = None,
193          system_prompt: str | None = None,
194          tools: ToolsType | list[str] | None = None,
195          snapshot_callback: SnapshotCallback | None = None,
196          confirmation_strategy_context: dict[str, Any] | None = None,
197          **kwargs: Any) -> dict[str, Any]
198  ```
199  
200  Process messages and execute tools until an exit condition is met.
201  
202  **Arguments**:
203  
204  - `messages`: List of Haystack ChatMessage objects to process.
205  - `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM.
206  The same callback can be configured to emit tool results when a tool is called.
207  - `generation_kwargs`: Additional keyword arguments for LLM. These parameters will
208  override the parameters passed during component initialization.
209  - `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint
210  for "tool_invoker".
211  - `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
212  the relevant information to restart the Agent execution from where it left off.
213  - `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt.
214  - `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run.
215  When passing tool names, tools are selected from the Agent's originally configured tools.
216  - `snapshot_callback`: Optional callback function that is invoked when a pipeline snapshot is created.
217  The callback receives a `PipelineSnapshot` object and can return an optional string.
218  If provided, the callback is used instead of the default file-saving behavior.
219  - `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources
220  to confirmation strategies. Useful in web/server environments to provide per-request
221  objects (e.g., WebSocket connections, async queues, Redis pub/sub clients) that strategies
222  can use for non-blocking user interaction.
223  - `kwargs`: Additional data to pass to the State schema used by the Agent.
224  The keys must match the schema defined in the Agent's `state_schema`.
225  
226  **Raises**:
227  
228  - `BreakpointException`: If an agent breakpoint is triggered.
229  
230  **Returns**:
231  
232  A dictionary with the following keys:
233  - "messages": List of all messages exchanged during the agent's run.
234  - "last_message": The last message exchanged during the agent's run.
235  - Any additional keys defined in the `state_schema`.
236  
237  <a id="agent.Agent.run_async"></a>
238  
239  #### Agent.run\_async
240  
241  ```python
242  async def run_async(messages: list[ChatMessage],
243                      streaming_callback: StreamingCallbackT | None = None,
244                      *,
245                      generation_kwargs: dict[str, Any] | None = None,
246                      break_point: AgentBreakpoint | None = None,
247                      snapshot: AgentSnapshot | None = None,
248                      system_prompt: str | None = None,
249                      tools: ToolsType | list[str] | None = None,
250                      snapshot_callback: SnapshotCallback | None = None,
251                      confirmation_strategy_context: dict[str, Any]
252                      | None = None,
253                      **kwargs: Any) -> dict[str, Any]
254  ```
255  
256  Asynchronously process messages and execute tools until the exit condition is met.
257  
258  This is the asynchronous version of the `run` method. It follows the same logic but uses
259  asynchronous operations where possible, such as calling the `run_async` method of the ChatGenerator
260  if available.
261  
262  **Arguments**:
263  
264  - `messages`: List of Haystack ChatMessage objects to process.
265  - `streaming_callback`: An asynchronous callback that will be invoked when a response is streamed from the
266  LLM. The same callback can be configured to emit tool results when a tool is called.
267  - `generation_kwargs`: Additional keyword arguments for LLM. These parameters will
268  override the parameters passed during component initialization.
269  - `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint
270  for "tool_invoker".
271  - `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
272  the relevant information to restart the Agent execution from where it left off.
273  - `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt.
274  - `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run.
275  - `snapshot_callback`: Optional callback function that is invoked when a pipeline snapshot is created.
276  The callback receives a `PipelineSnapshot` object and can return an optional string.
277  If provided, the callback is used instead of the default file-saving behavior.
278  - `kwargs`: Additional data to pass to the State schema used by the Agent.
279  The keys must match the schema defined in the Agent's `state_schema`.
280  - `confirmation_strategy_context`: Optional dictionary for passing request-scoped resources
281  to confirmation strategies. Useful in web/server environments to provide per-request
282  objects (e.g., WebSocket connections, async queues, Redis pub/sub clients) that strategies
283  can use for non-blocking user interaction.
284  
285  **Raises**:
286  
287  - `BreakpointException`: If an agent breakpoint is triggered.
288  
289  **Returns**:
290  
291  A dictionary with the following keys:
292  - "messages": List of all messages exchanged during the agent's run.
293  - "last_message": The last message exchanged during the agent's run.
294  - Any additional keys defined in the `state_schema`.
295  
296  <a id="state/state"></a>
297  
298  ## Module state/state
299  
300  <a id="state/state.State"></a>
301  
302  ### State
303  
304  State is a container for storing shared information during the execution of an Agent and its tools.
305  
306  For instance, State can be used to store documents, context, and intermediate results.
307  
308  Internally it wraps a `_data` dictionary defined by a `schema`. Each schema entry has:
309  ```json
310    "parameter_name": {
311      "type": SomeType,  # expected type
312      "handler": Optional[Callable[[Any, Any], Any]]  # merge/update function
313    }
314    ```
315  
316  Handlers control how values are merged when using the `set()` method:
317  - For list types: defaults to `merge_lists` (concatenates lists)
318  - For other types: defaults to `replace_values` (overwrites existing value)
319  
320  A `messages` field with type `list[ChatMessage]` is automatically added to the schema.
321  
322  This makes it possible for the Agent to read from and write to the same context.
323  
324  ### Usage example
325  ```python
326  from haystack.components.agents.state import State
327  
328  my_state = State(
329      schema={"gh_repo_name": {"type": str}, "user_name": {"type": str}},
330      data={"gh_repo_name": "my_repo", "user_name": "my_user_name"}
331  )
332  ```
333  
334  <a id="state/state.State.__init__"></a>
335  
336  #### State.\_\_init\_\_
337  
338  ```python
339  def __init__(schema: dict[str, Any], data: dict[str, Any] | None = None)
340  ```
341  
342  Initialize a State object with a schema and optional data.
343  
344  **Arguments**:
345  
346  - `schema`: Dictionary mapping parameter names to their type and handler configs.
347  Type must be a valid Python type, and handler must be a callable function or None.
348  If handler is None, the default handler for the type will be used. The default handlers are:
349      - For list types: `haystack.agents.state.state_utils.merge_lists`
350      - For all other types: `haystack.agents.state.state_utils.replace_values`
351  - `data`: Optional dictionary of initial data to populate the state
352  
353  <a id="state/state.State.get"></a>
354  
355  #### State.get
356  
357  ```python
358  def get(key: str, default: Any = None) -> Any
359  ```
360  
361  Retrieve a value from the state by key.
362  
363  **Arguments**:
364  
365  - `key`: Key to look up in the state
366  - `default`: Value to return if key is not found
367  
368  **Returns**:
369  
370  Value associated with key or default if not found
371  
372  <a id="state/state.State.set"></a>
373  
374  #### State.set
375  
376  ```python
377  def set(key: str,
378          value: Any,
379          handler_override: Callable[[Any, Any], Any] | None = None) -> None
380  ```
381  
382  Set or merge a value in the state according to schema rules.
383  
384  Value is merged or overwritten according to these rules:
385    - if handler_override is given, use that
386    - else use the handler defined in the schema for 'key'
387  
388  **Arguments**:
389  
390  - `key`: Key to store the value under
391  - `value`: Value to store or merge
392  - `handler_override`: Optional function to override the default merge behavior
393  
394  <a id="state/state.State.data"></a>
395  
396  #### State.data
397  
398  ```python
399  @property
400  def data()
401  ```
402  
403  All current data of the state.
404  
405  <a id="state/state.State.has"></a>
406  
407  #### State.has
408  
409  ```python
410  def has(key: str) -> bool
411  ```
412  
413  Check if a key exists in the state.
414  
415  **Arguments**:
416  
417  - `key`: Key to check for existence
418  
419  **Returns**:
420  
421  True if key exists in state, False otherwise
422  
423  <a id="state/state.State.to_dict"></a>
424  
425  #### State.to\_dict
426  
427  ```python
428  def to_dict()
429  ```
430  
431  Convert the State object to a dictionary.
432  
433  <a id="state/state.State.from_dict"></a>
434  
435  #### State.from\_dict
436  
437  ```python
438  @classmethod
439  def from_dict(cls, data: dict[str, Any])
440  ```
441  
442  Convert a dictionary back to a State object.
443