You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -18,86 +18,93 @@ An AI agent is a system that can:
18
18
- Generate intelligent responses (using LLMs like OpenAI or Hugging Face models),
19
19
- Perform actions (calling APIs, fetching live data, executing functions).
20
20
21
-
### Understanding AI Agents
21
+
AI agents are autonomous systems that use large language models (LLMs) to make decisions and solve complex tasks.
22
+
They interact with their environment using tools, memory, and reasoning.
23
+
An AI agent is more than a chatbot — it actively plans, chooses the right tools, and executes tasks to achieve a goal.
24
+
Unlike traditional software, it adapts to new information and refines its process as needed.
22
25
23
-
AI agents are autonomous systems that use large language models (LLMs) to make decisions and solve complex tasks. They interact with their environment using tools, memory, and reasoning.
24
-
25
-
### What Makes an AI Agent
26
-
27
-
An AI agent is more than a chatbot. It actively plans, chooses the right tools and executes tasks to achieve a goal. Unlike traditional software, it adapts to new information and refines its process as needed.
28
-
29
-
1.**LLM as the Brain**: The agent's core is an LLM, which understands context, processes natural language and serves as the central intelligence system.
26
+
1.**LLM as the Brain**: The agent’s core is an LLM, which understands context, processes natural language and serves as the central intelligence system.
30
27
2.**Tools for Interaction**: Agents connect to external tools, APIs, and databases to gather information and take action.
31
28
3.**Memory for Context**: Short-term memory helps track conversations, while long-term memory stores knowledge for future interactions.
32
29
4.**Reasoning and Planning**: Agents break down complex problems, come up with step-by-step action plans, and adapt based on new data and feedback.
33
30
34
-
### How AI Agents Work
31
+
An AI agent starts with a prompt that defines its role and objectives.
32
+
It decides when to use tools, gathers data, and refines its approach through loops of reasoning and action.
33
+
For example, a customer service agent answers queries using a database — if it lacks an answer, it fetches real-time data, summarizes it, and responds.
34
+
A coding assistant understands project requirements, suggests solutions, and writes code.
35
35
36
-
An AI agent starts with a prompt that defines its role and objectives. It decides when to use tools, gathers data, and refines its approach through loops of reasoning and action. It evaluates progress and adjusts its strategy to improve results.
36
+
## Key Components
37
37
38
-
For example, a customer service agent answers queries using a database. If it lacks an answer, it fetches real-time data, summarizes it, and provides a response. A coding assistant understands project requirements, suggests solutions, and even writes code.
38
+
### Agent Component
39
39
40
-
## Key Components
40
+
Haystack has a built-in [Agent](../pipeline-components/agents-1/agent.mdx) component that manages the full tool-calling loop — it calls the LLM, invokes tools, updates state, and continues until a stopping condition is met.
41
+
Key capabilities include:
41
42
42
-
### Agents
43
+
-**State management**: Share typed data between tools, accumulate results across iterations, and surface them in the result dict using `state_schema`. See [State](../pipeline-components/agents-1/state.mdx).
44
+
-**Streaming**: Stream token-by-token output with a `streaming_callback`.
45
+
-**Human-in-the-loop**: Intercept tool calls for human review before execution. See [Human in the Loop](../pipeline-components/agents-1/human-in-the-loop.mdx).
46
+
-**Multi-agent systems**: Wrap an `Agent` as a `ComponentTool` to build coordinator/specialist architectures. See [Multi-Agent Systems](./agents/multi-agent-systems.mdx).
47
+
-**MCP server exposure**: Expose your agent as an MCP server using [Hayhooks](../development/hayhooks.mdx), making it callable from any MCP-compatible client such as Claude Desktop or Cursor.
48
+
-**Multimodal inputs**: Pass images alongside text using `ImageContent` in `ChatMessage` content parts, or return `ImageContent` from tools for dynamic image analysis. Requires a vision-capable model such as `gpt-5` or `gemini-2.5-flash`. See [Multimodal Inputs](../pipeline-components/agents-1/agent.mdx#multimodal-inputs).
43
49
44
-
Haystack has a universal [Agent](../pipeline-components/agents-1/agent.mdx) component that interacts with chat-based LLMs and tools to solve complex queries. It requires a Chat Generator that supports tools to work and can be customizable according to your needs. Check out the [Agent](../pipeline-components/agents-1/agent.mdx) documentation, or the [example](#tool-calling-agent) below to see how it works.
50
+
Check out the [Agent](../pipeline-components/agents-1/agent.mdx) documentation, or the [example](#tool-calling-agent) below to get started.
45
51
46
-
### Additional Components
52
+
### State
47
53
48
-
You can build an AI agent in Haystack yourself, using the three main elements in a pipeline:
54
+
[`State`](../pipeline-components/agents-1/state.mdx) is Haystack's built-in mechanism for sharing data between tools and accumulating results across multiple tool calls.
55
+
You define a `state_schema` on the `Agent`, and any keys declared there are returned alongside `messages` and `last_message` in the agent's result dict.
49
56
50
-
-[Chat Generators](../pipeline-components/generators.mdx) to generate tool calls (with tool name and arguments) or assistant responses with an LLM,
51
-
-[`Tool`](../tools/tool.mdx) class that allows the LLM to perform actions such as running a pipeline or calling an external API, connecting to the external world,
52
-
-[`ToolInvoker`](../pipeline-components/tools/toolinvoker.mdx) component to execute tool calls generated by an LLM. It parses the LLM's tool-calling responses and invokes the appropriate tool with the correct arguments from the pipeline.
57
+
### Tools
53
58
54
-
There are three ways of creating a tool in Haystack:
59
+
Haystack provides several ways to create and manage tools:
55
60
56
-
-[`Tool`](../tools/tool.mdx) class – Creates a tool representation for a consistent tool-calling experience across all Generators. It allows for most customization, as you can define its own name and description.
57
-
-[`ComponentTool`](../tools/componenttool.mdx) class – Wraps a Haystack component as a callable tool.
58
-
-[`@tool`](../tools/tool.mdx#tool-decorator) decorator – Creates tools from Python functions and automatically uses their function name and docstring.
59
-
-[Toolset](../tools/toolset.mdx) – A container for grouping multiple tools that can be passed directly to Agents or Generators.
61
+
-[`Tool`](../tools/tool.mdx) class / [`@tool`](../tools/tool.mdx#tool-decorator) decorator – Define a tool from a Python function. The `@tool` decorator automatically uses the function's name and docstring; the `Tool` class gives full control over the name, description, and schema.
62
+
-[`ComponentTool`](../tools/componenttool.mdx) – Wraps any Haystack component as a callable tool.
63
+
-[`PipelineTool`](../tools/pipelinetool.mdx) – Wraps a full Haystack pipeline as a callable tool.
64
+
-[`MCPTool`](../tools/mcptool.mdx) / [`MCPToolset`](../tools/mcptoolset.mdx) – Connects to Model Context Protocol (MCP) servers to load external tools.
65
+
-[`Toolset`](../tools/toolset.mdx) – Groups multiple tools into a single unit to pass to an Agent or Generator.
66
+
-[`SearchableToolset`](../tools/searchabletoolset.mdx) – Enables keyword-based tool discovery for large catalogs, so the LLM only sees relevant tools at each step.
60
67
61
-
## Example Agents
68
+
## Example
62
69
63
70
### Tool-Calling Agent
64
71
65
-
You can create a similar tool-calling agent with the `Agent` component:
72
+
Create a tool-calling agent with the `Agent` component. This example requires `OPENAI_API_KEY` and `SERPERDEV_API_KEY` to be set as environment variables:
73
+
74
+
```shell
75
+
export OPENAI_API_KEY=<your-openai-key>
76
+
export SERPERDEV_API_KEY=<your-serperdev-key>
77
+
```
66
78
67
79
```python
68
80
from haystack.components.agents import Agent
69
81
from haystack.components.generators.chat import OpenAIChatGenerator
82
+
from haystack.components.generators.utils import print_streaming_chunk
70
83
from haystack.components.websearch import SerperDevWebSearch
71
-
from haystack.dataclasses import Document, ChatMessage
72
-
from haystack.tools.component_tool import ComponentTool
73
-
74
-
75
-
## Create the web search component
76
-
web_search = SerperDevWebSearch(top_k=3)
84
+
from haystack.dataclasses import ChatMessage
85
+
from haystack.tools import ComponentTool
77
86
78
-
## Create the ComponentTool with simpler parameters
87
+
# Wrap the web search component as a tool
79
88
web_tool = ComponentTool(
80
-
component=web_search,
89
+
component=SerperDevWebSearch(top_k=3),
81
90
name="web_search",
82
91
description="Search the web for current information like weather, news, or facts.",
"You're a helpful agent. When asked about current information like weather, news, or facts, "
98
+
"use the web_search tool to find the information and then summarize the findings."
99
+
),
92
100
tools=[web_tool],
101
+
streaming_callback=print_streaming_chunk,
93
102
)
94
103
95
-
## Run the agent with the user message
96
-
user_message = ChatMessage.from_user("How is the weather in Berlin?")
97
-
result = tool_calling_agent.run(messages=[user_message])
98
-
99
-
## Print the result - using .text instead of .content
100
-
print(result["messages"][-1].text)
104
+
result = tool_calling_agent.run(
105
+
messages=[ChatMessage.from_user("How is the weather in Berlin?")],
106
+
)
107
+
print(result["last_message"].text)
101
108
```
102
109
103
110
Resulting in:
@@ -112,98 +119,3 @@ Resulting in:
112
119
113
120
For more details, you can check the full forecasts on [AccuWeather](https://www.accuweather.com/en/de/berlin/10178/current-weather/178087) or [Weather.com](https://weather.com/weather/today/l/5ca23443513a0fdc1d37ae2ffaf5586162c6fe592a66acc9320a0d0536be1bb9).
114
121
```
115
-
116
-
### Pipeline With Tools
117
-
118
-
Here’s an example of how you would build a tool-calling agent with the help of `ToolInvoker`.
119
-
120
-
This is what’s happening in this code example:
121
-
122
-
1.`OpenAIChatGenerator` uses an LLM to analyze the user's message and determines whether to provide an assistant response or initiate a tool call.
123
-
2.`ConditionalRouter` directs the output from the `OpenAIChatGenerator` to `there_are_tool_calls` branch if it’s a tool call or to `final_replies` to return to the user directly.
124
-
3.`ToolInvoker` executes the tool call generated by the LLM. `ComponentTool` wraps the `SerperDevWebSearch` component that fetches real-time search results, making it accessible for `ToolInvoker` to execute it as a tool.
125
-
4. After the tool provides its output, the `ToolInvoker` sends this information back to the `OpenAIChatGenerator`, along with the original user question stored by the `MessageCollector`.
126
-
127
-
```python
128
-
from haystack import component, Pipeline
129
-
from haystack.components.tools import ToolInvoker
130
-
from haystack.components.generators.chat import OpenAIChatGenerator
131
-
from haystack.components.routers import ConditionalRouter
132
-
from haystack.components.websearch import SerperDevWebSearch
133
-
from haystack.core.component.types import Variadic
134
-
from haystack.dataclasses import ChatMessage
135
-
from haystack.tools import ComponentTool
136
-
137
-
from typing import Any
138
-
139
-
140
-
## helper component to temporarily store last user query before the tool call
"You're a helpful agent choosing the right tool when necessary",
193
-
),
194
-
ChatMessage.from_user("How is the weather in Berlin?"),
195
-
]
196
-
result = tool_agent.run({"messages": messages})
197
-
198
-
print(result["router"]["final_replies"][0].text)
199
-
```
200
-
201
-
Resulting in:
202
-
203
-
```python
204
-
>>> The current weather in Berlin is around 46°F (8°C) with cloudy conditions. The high for today is forecasted to reach 48°F (9°C) and the low is expected to be around 37°F (3°C). The humidity is quite high at 92%, and there is a light wind blowing at 4 mph.
205
-
206
-
For more detailed weather updates, you can check the following links:
0 commit comments