
Most common position in a pipeline	After a `ChatPromptBuilder` or user input
Mandatory init variables	`chat_generator`: An instance of a Chat Generator that supports tools
Mandatory run variables	`messages`: A list of `ChatMessage`s
Output variables	`messages`: Chat history with tool and model responses
API reference	Agents
GitHub link	https://github.com/deepset-ai/haystack/blob/main/haystack/components/agents/agent.py

Overview

The Agent component is a loop-based system that uses a chat-based large language model (LLM) and external tools to solve complex user queries. It works iteratively—calling tools, updating state, and generating prompts—until one of the configurable exit_conditions is met.

It can:

Dynamically select tools based on user input,
Maintain and validate runtime state using a schema,
Stream token-level outputs from the LLM.

The Agent returns a dictionary containing:

messages: the full conversation history,
Additional dynamic keys based on state_schema.

Parameters

To initialize the Agent component, you need to provide it with an instance of a Chat Generator that supports tools. You can pass a list of tools or ComponentTool instances, or wrap them in a Toolset to manage them as a group.

You can additionally configure:

A system_prompt for your Agent,
A list of exit_conditions strings that will cause the agent to return. Can be either:
- “text”, which means that the Agent will exit as soon as the LLM replies only with a text response,
- or specific tool names.
A state_schema for one agent invocation run. It defines extra information – such as documents or context – that tools can read from or write to during execution. You can use this schema to pass parameters that tools can both produce and consume.
streaming_callback to stream the tokens from the LLM directly in output.

📘
For a complete list of available parameters, refer to the Agents API Documentation.

Usage

On its own

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

# Tool Function
def calculate(expression: str) -> dict:
    try:
        result = eval(expression, {"__builtins__": {}})
        return {"result": result}
    except Exception as e:
        return {"error": str(e)}

# Tool Definition
calculator_tool = Tool(
    name="calculator",
    description="Evaluate basic math expressions.",
    parameters={
        "type": "object",
        "properties": {
            "expression": {"type": "string", "description": "Math expression to evaluate"}
        },
        "required": ["expression"]
    },
    function=calculate,
    outputs_to_state={"calc_result": {"source": "result"}}
)

# Agent Setup
agent = Agent(
    chat_generator=OpenAIChatGenerator(),
    tools=[calculator_tool],
    exit_conditions=["calculator"],
    state_schema={
        "calc_result": {"type": int},
    }
)

# Run the Agent
agent.warm_up()
response = agent.run(messages=[ChatMessage.from_user("What is 7 * (4 + 2)?")])

# Output
print(response["messages"])
print("Calc Result:", response.get("calc_result"))

In a pipeline

The example pipeline below creates a database assistant using OpenAIChatGenerator, LinkContentFetcher, and custom database tool. It reads the given URL and processes the page content, then builds a prompt for the AI. The assistant uses this information to write people's names and titles from the given page to the database.

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
from haystack.components.converters.html import HTMLToDocument
from haystack.components.fetchers.link_content import LinkContentFetcher
from haystack.core.pipeline import Pipeline
from haystack.tools import tool
from haystack.document_stores.in_memory import InMemoryDocumentStore
from typing import Optional
from haystack.dataclasses import ChatMessage, Document

document_store = InMemoryDocumentStore() # create a document store or an SQL database

@tool
def add_database_tool(name: str, surname: str, job_title: Optional[str], other: Optional[str]):
    """Use this tool to add names to the database with information about them"""
    document_store.write_documents([Document(content=name + " " + surname + " " + (job_title or ""), meta={"other":other})])
    return 

database_asistant = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
    tools=[add_database_tool],
    system_prompt="""
    You are a database assistant.
    Your task is to extract the names of people mentioned in the given context and add them to a knowledge base, along with additional relevant information about them that can be extracted from the context.
    Do not use you own knowledge, stay grounded to the given context.
    Do not ask the user for confirmation. Instead, automatically update the knowledge base and return a brief summary of the people added, including the information stored for each.
    """,
    exit_conditions=["text"],
    max_agent_steps=100,
    raise_on_tool_invocation_failure=False
)

extraction_agent = Pipeline()
extraction_agent.add_component("fetcher", LinkContentFetcher())
extraction_agent.add_component("converter", HTMLToDocument())
extraction_agent.add_component("builder", ChatPromptBuilder(
    template=[ChatMessage.from_user("""
    {% for doc in docs %}
    {{ doc.content|default|truncate(25000) }}
    {% endfor %}
    """)],
    required_variables=["docs"]
))

extraction_agent.add_component("database_agent", database_asistant)
extraction_agent.connect("fetcher.streams", "converter.sources")
extraction_agent.connect("converter.documents", "builder.docs")
extraction_agent.connect("builder", "database_agent")

agent_output = extraction_agent.run({"fetcher":{"urls":["https://en.wikipedia.org/wiki/Deepset"]}})

print(agent_output["database_agent"]["messages"][-1].text)

Additional References

🧑‍🍳 Cookbook: Build a GitHub Issue Resolver Agent

📓 Tutorial: Build a Tool-Calling Agent