docs: Update Agent docs to reflect new features and explain different common patterns

[sjrl]

Related Issues

• follow up to docs: Update tool docs #11236

Proposed Changes:

• Update Agent docs to include information about new features that have been added
• Update examples to use recommended patterns especially around designing tools
• Restructure the docs to make them easier to understand and navigate
• Made the Multi Agent Systems section to better highlight multi agents in Haystack and when they should be used (e.g. context engineering)

How did you test it?

Ran the 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 5, 2026 9:51am

[claude]

Code review

Bug: Invalid model name gpt-5.4-nano

gpt-5.4-nano is not a real OpenAI model and will cause a model_not_found error at runtime for anyone copy-pasting the examples in this PR.

The codebase's own authoritative SUPPORTED_MODELS list in openai.py confirms:

• gpt-5-nano ✅ (real model, used throughout the test suite)
• gpt-5.4 ✅ (real model in SUPPORTED_MODELS)
• gpt-5.4-nano ❌ (does not exist — the 5.4 decimal-versioned family has -pro/-chat/-codex variants, not -nano)

The intended replacement for the previous gpt-4o-mini examples is almost certainly gpt-5-nano.

Affected locations (both docs-website/docs/pipeline-components/agents-1/agent.mdx and docs-website/versioned_docs/version-2.28/pipeline-components/agents-1/agent.mdx):

• Line 94: calculator example
• Line 148: database pipeline example
• Line 222: YAML example
• Line 325: streaming example
• Lines 391 and 409: multi-agent example

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

[sjrl]

Code review

Bug: Invalid model name gpt-5.4-nano

gpt-5.4-nano is not a real OpenAI model and will cause a model_not_found error at runtime for anyone copy-pasting the examples in this PR.

The codebase's own authoritative SUPPORTED_MODELS list in openai.py confirms:

• gpt-5-nano ✅ (real model, used throughout the test suite)
• gpt-5.4 ✅ (real model in SUPPORTED_MODELS)
• gpt-5.4-nano ❌ (does not exist — the 5.4 decimal-versioned family has -pro/-chat/-codex variants, not -nano)

The intended replacement for the previous gpt-4o-mini examples is almost certainly gpt-5-nano.

Affected locations (both docs-website/docs/pipeline-components/agents-1/agent.mdx and docs-website/versioned_docs/version-2.28/pipeline-components/agents-1/agent.mdx):

• Line 94: calculator example
• Line 148: database pipeline example
• Line 222: YAML example
• Line 325: streaming example
• Lines 391 and 409: multi-agent example

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

How do we update Claude? XD

[julian-risch]

One nit pick otherwise looks good to me. I'll approve right after applying my suggestions