docs: Update concept docs for Agent and move/improve State docs

[sjrl]

Related Issues

• follow up to docs: Small update to HITL docs #11257, docs: Update Agent docs to reflect new features and explain different common patterns #11254, docs: Update agent api docstrings #11253, docs: Update toolset and searchable toolset docs #11239, docs: Update component and pipeline tool docs #11237

Proposed Changes:

• Moved states.mdx docs to be alongside the Agent and HITL component docs
• Shortened the agent concepts docs and linked more heavily to our component docs
• Updated examples to use recommened patterns
• states docs were updated to highlight more practical use of state with Agent

How did you test it?

Ran code blocks locally

Notes for the reviewer

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ready	Preview, Comment	May 7, 2026 0:58am

[claude]

test

[claude]

Code review - two issues found. Issue 1: gpt-5.4-nano typo. Issue 2: Wrong import path.

[claude]

Code review

Two issues found:

Issue 1: Invalid model name gpt-5.4-nano (typo)

haystack/docs-website/docs/concepts/agents.mdx

Lines 92 to 94 in df0dbf6

	tool_calling_agent = Agent(
	chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
	system_prompt=(

The model gpt-5.4-nano does not exist in OpenAIs catalog — this is a typo for gpt-5-nano. This string was introduced in 14 places across the new state.mdx, agents.mdx, and their version-2.28 mirrors. The deleted code correctly used gpt-5-nano. Any reader copy-pasting these snippets will get a model_not_found error from the OpenAI API.

Fix: replace all occurrences of gpt-5.4-nano with gpt-5-nano.

---

Issue 2: Incorrect import path for merge_lists / replace_values

haystack/docs-website/docs/pipeline-components/agents-1/state.mdx

Lines 70 to 74 in df0dbf6

	### Default Handlers
	State provides two built-in merge behaviors (importable from `haystack.components.agents`):
	- **`merge_lists`**: Appends to the existing list (default for list types)

The new state.mdx says these are "importable from haystack.components.agents", but haystack/components/agents/__init__.py only exports Agent and State. merge_lists and replace_values are only accessible from haystack.components.agents.state. The deleted docs had the correct path (from haystack.components.agents.state.state_utils import merge_lists, replace_values). This error also appears in the version-2.28 mirror.

Fix: change "importable from haystack.components.agents" to "importable from haystack.components.agents.state".

[anakin87]

Sounds reasonable