Module agent

Agent

A Haystack component that implements a tool-using agent with provider-agnostic chat model support.

The component processes messages and executes tools until a exit_condition condition is met. The exit_condition can be triggered either by a direct text response or by invoking a specific designated tool.

Usage example

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.tools.tool import Tool

tools = [Tool(name="calculator", description="..."), Tool(name="search", description="...")]

agent = Agent(
    chat_generator=OpenAIChatGenerator(),
    tools=tools,
    exit_condition="search",
)

# Run the agent
result = agent.run(
    messages=[ChatMessage.from_user("Find information about Haystack")]
)

assert "messages" in result  # Contains conversation history

Agent.__init__

def __init__(*,
             chat_generator: ChatGenerator,
             tools: Optional[List[Tool]] = None,
             system_prompt: Optional[str] = None,
             exit_conditions: Optional[List[str]] = None,
             state_schema: Optional[Dict[str, Any]] = None,
             max_agent_steps: int = 100,
             raise_on_tool_invocation_failure: bool = False,
             streaming_callback: Optional[SyncStreamingCallbackT] = None)

Initialize the agent component.

Arguments:

• chat_generator: An instance of the chat generator that your agent should use. It must support tools.
• tools: List of Tool objects available to the agent
• system_prompt: System prompt for the agent.
• exit_conditions: List of conditions that will cause the agent to return. Can include "text" if the agent should return when it generates a message without tool calls, or tool names that will cause the agent to return once the tool was executed. Defaults to ["text"].
• state_schema: The schema for the runtime state used by the tools.
• max_agent_steps: Maximum number of steps the agent will run before stopping. Defaults to 100. If the agent exceeds this number of steps, it will stop and return the current state.
• raise_on_tool_invocation_failure: Should the agent raise an exception when a tool invocation fails? If set to False, the exception will be turned into a chat message and passed to the LLM.
• streaming_callback: A callback that will be invoked when a response is streamed from the LLM.

Raises:

• TypeError: If the chat_generator does not support tools parameter in its run method.

Agent.warm_up

def warm_up() -> None

Warm up the Agent.

Agent.to_dict

def to_dict() -> Dict[str, Any]

Serialize the component to a dictionary.

Returns:

Dictionary with serialized data

Agent.from_dict

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Agent"

Deserialize the agent from a dictionary.

Arguments:

• data: Dictionary to deserialize from

Returns:

Deserialized agent

Agent.run

def run(messages: List[ChatMessage],
        streaming_callback: Optional[SyncStreamingCallbackT] = None,
        **kwargs: Dict[str, Any]) -> Dict[str, Any]

Process messages and execute tools until the exit condition is met.

Arguments:

• messages: List of chat messages to process
• streaming_callback: A callback that will be invoked when a response is streamed from the LLM.
• kwargs: Additional data to pass to the State schema used by the Agent. The keys must match the schema defined in the Agent's state_schema.

Returns:

Dictionary containing messages and outputs matching the defined output types