Install & Compatibility
Where this runs
tested against v0.19.0.post1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 164.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 12.0s · import 0.000s · 159MB
170MB installed
● package 170MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Agent
✓ from haystack_experimental.agents.agent import Agent
✗ from haystack_experimental.agents.agent import Agent
This quickstart demonstrates creating and running an experimental Haystack Agent. It uses `OpenAIChatGenerator` (requires `openai` extra) and `PromptBuilder` to respond to a simple query. The `Agent` is a core experimental component for orchestration.
import os
from haystack_experimental.agents.agent import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.builders.prompt_builder import PromptBuilder
# Ensure your OpenAI API key is set as an environment variable
os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'sk-...')
# Initialize LLM and PromptBuilder
llm = OpenAIChatGenerator()
prompt_builder = PromptBuilder(template="{{ query }}")
# Create an experimental Agent
agent = Agent(
tools=[], # Agents can use tools, but for this quickstart we'll keep it simple
prompt_builder=prompt_builder,
llm=llm,
max_iterations=3,
debug=True
)
# Run the agent
result = agent.run(query="What is the capital of France?")
print(f"Agent Output: {result.answer}")
Debug
Known issues
breakingComponents within `haystack-experimental` are volatile. Their APIs are unstable and subject to frequent breaking changes, renaming, or complete removal without prior notice due to their experimental nature.fixRefer to the latest documentation and changelog (`docs.haystack.deepset.ai/reference/experimental-overview`) before upgrading or integrating. Expect to adapt your code frequently.
affects: All versions
gotchaCompatibility with the core `haystack-ai` library is tightly coupled. Updates to either `haystack-experimental` or `haystack-ai` can introduce incompatibilities, requiring specific version alignments.fixAlways check the release notes of `haystack-experimental` for the compatible `haystack-ai` version. Pin your `haystack-ai` version accordingly.
affects: All versions
breakingPython 3.9 support was dropped, requiring Python 3.10 or newer.fixUpgrade your Python environment to 3.10 or higher.
affects: 0.16.0 and later
deprecatedThe `EmbedderBasedDocumentsplitter` component was removed.fixUse standard Haystack DocumentSplitters (e.g., `DocumentSplitter`) or other available experimental text splitting components.
affects: 0.16.0 and later
deprecatedHuman-in-the-Loop (HiTL) related code was removed as it migrated out of `haystack-experimental`.fixRefer to the core Haystack library for current HiTL functionalities, if applicable.
affects: 0.18.0 and later
Upgrade
Version history
0.19.0.post1latest on PyPI · released Jul 28, 2026
Audit
Dependencies
haystack-airequiredThis library is built on and integrates with the Haystack 2.x core, providing experimental components for it.
openaioptionalRequired for using OpenAI models with components like OpenAIChatGenerator, typically installed via the `[openai]` extra.