How to run a first Haystack agent

Haystack’s get-started page is the setup guide for a first tool-calling agent. It documents that path after the install step and the RAG example, and it is the page to follow for packages, environment variables, and the run call. The Agent component page is a reference, not the first-run recipe. Use it only to confirm which constructor argument is required and which fields come back from a run.

These steps follow the Haystack docs labeled Version 3.4.

Install the packages the OpenAI example uses

The get-started page installs the minimal form of Haystack with this command:

pip install haystack-ai

On the OpenAI tab of “Build your first Agent,” the page states that OpenAIChatGenerator is included in the haystack-ai package. That tab does not show a second install for the generator.

The agent examples add one package the RAG example does not. The page says all of the examples under that heading use SerperDevWebSearch, which lives in the serperdev-haystack package, and it shows:

pip install serperdev-haystack

Set the two environment variables

Those web-search examples require a SerperDev API key. The page says to set it as the SERPERDEV_API_KEY environment variable. It does not show a shell assignment or a placeholder value for that variable. Put the key in the environment before the script runs.

The OpenAI generator does not take a literal key in the published snippet. The call reads OPENAI_API_KEY through Secret.from_env_var. The get-started Agent section does not show a shell line for that variable either. Set the variable named in that call, and leave the Python unchanged.

Run the published OpenAI agent

The OpenAI tab builds a search tool, passes it to Agent, and runs one user message. This is the complete snippet from that tab:

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.tools import ComponentTool
from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
from haystack.utils import Secret

search_tool = ComponentTool(component=SerperDevWebSearch())

agent = Agent(
    chat_generator=OpenAIChatGenerator(
        api_key=Secret.from_env_var("OPENAI_API_KEY"),
        model="gpt-4o-mini",
    ),
    tools=[search_tool],
    system_prompt="You are a helpful assistant that can search the web for information.",
)

result = agent.run(messages=[ChatMessage.from_user("What is Haystack AI?")])

print(result["last_message"].text)

Keep the calls in the order the page shows them.

The snippet wraps SerperDevWebSearch in ComponentTool and stores that object as the search tool. The Agent constructor receives that object in the tools list, along with an OpenAIChatGenerator and a system prompt. The generator is constructed with the model name gpt-4o-mini and the environment-variable secret shown above. The run method takes a messages list whose only item is a user ChatMessage asking what Haystack AI is. The print statement then reads the text of last_message on the returned dictionary.

The get-started page does not include a sample reply for that question. Whatever string prints is the text of the run’s final message. Do not expect the docs to match a particular sentence.

The page’s own description of this section is that agents are AI systems that can use tools to gather information, perform actions, and interact with external systems, and that this example searches the web to answer questions.

Check the Agent contract after the script works

The component page is where the required-versus-optional split is explicit. It says chat_generator is the only mandatory init parameter, and that it must be an instance of a Chat Generator that supports tools. All other init parameters are optional. tools is in that optional list, even though the get-started example passes one tool. The package name on the component page is haystack-ai.

The mandatory run variable is messages: a list of ChatMessage objects. That is the argument the get-started snippet passes when it runs the agent.

The component returns a dictionary. last_message is the final ChatMessage of the run, which is the object whose text the snippet prints. The page also lists messages for the chat history with tool and model responses, plus step_count, token_usage, tool_call_counts, and exit_reason. The first-run snippet does not print those keys. Figures shown next to those keys elsewhere on the component page come from a different example, not from the web-search script, so they are not the expected output of this run.

If you omit the optional init arguments, the page documents these defaults:

exit_conditions defaults to ["text"]. The page says that value stops the agent when the LLM replies without a tool call.
max_agent_steps defaults to 100.
raise_on_tool_invocation_failure defaults to false. In that case the error is passed back to the LLM as a message so it can recover, instead of raising.

The get-started constructor does not set exit_conditions, state_schema, streaming_callback, max_agent_steps, or hooks. Leave them out of the first script. The component page also says agent attributes are not meant to be reassigned after initialization, because several parameters are processed at init time. If you later need a modified copy, it recommends clone() rather than setting attributes on the agent you already built.

Do not mix provider tabs

The same Agent section has tabs for other generators. They are separate examples, not edits to the OpenAI block. The Hugging Face tab uses HuggingFaceAPIChatGenerator from the huggingface-api-haystack package and reads HF_API_TOKEN through Secret.from_env_var. The Anthropic, Amazon Bedrock, and Google Gemini tabs show their own installs:

pip install anthropic-haystack

pip install amazon-bedrock-haystack

pip install google-genai-haystack

Each of those tabs then constructs a different chat generator. The page also says Haystack supports Cohere, Mistral, NVIDIA, Ollama, and others, and it points readers to the Generators documentation and the integrations page. Stay on the OpenAI tab for this first run unless you are deliberately following another tab.

What to do next

Install the two packages shown above, set SERPERDEV_API_KEY and OPENAI_API_KEY, and run the OpenAI snippet from the get-started Agent section without adding arguments the page does not show. When it returns, read the reply the way the snippet does: the text of last_message. Then use the Agent component page if you need the other dictionary keys or the default exit behavior. For a longer follow-on, the get-started Next Steps section names the “Build a Tool-Calling Agent” tutorial, which covers a tool-calling agent that can use both components and pipelines as tools.