Skip to content
Agents tracked: 501 Releases (7d): 777 Agent status: no reported issuesSince last limit reset: Claude 10d · Codex 8d For AI agents: Markdown Updated Nov 21, 2026

Haystack changelog: what's new each month

Every stable Haystack release summarised by month: the highlights, new features, improvements, fixes and anything you need to act on. 12 months covered; the current month updates daily.

November 2026 · so far

2 releases: 2.31.1 → 3.5.0

November brought dependency updates for security and API compatibility, along with several important changes to how Haystack handles data and integrates with OpenAI's latest models. Users upgrading to version 3.5.0 should review breaking changes around Excel parsing, state keys, and OpenAI model defaults.

Action needed
  • Minimum OpenAI SDK version raised from 2.6.0 to 3.26.0.
  • Minimum Pydantic version now 2.12 (2.14 on Python 3.15).
  • Minimum anyio version is now 4.14.2.
  • Minimum certifi version is now 2026.10.19.

Highlights

  • OpenAI SDK minimum version raised to 3.26.0 to support the Decisions API.
  • Default OpenAI model changed from gpt-5-mini to gpt-5.6-terra.
  • Excel parser now preserves text like "NA" and "NULL" instead of treating them as missing values by default.
  • Variadic and multi-sender list inputs now respect connection order in pipelines.
  • Token usage metadata requested by default when streaming with OpenAI generators.

Improved

  • OpenAIChatGenerator and AzureOpenAIChatGenerator now request token usage metadata by default during streaming.
  • Components with variadic or multi-sender list inputs now receive values in connection order.

October 2026

3 releases: 3.3.0 → 3.4.1

October brought stability improvements and fixes across document handling and message processing, along with important security updates. The month also standardized how page numbers are reported across different document splitters.

Action needed
  • Python 3.10 support dropped; minimum version is now Python 3.11.
  • RecursiveDocumentSplitter now reports the page a chunk starts on instead of where it ends.
  • Haystack requires anyio>=4.14.2 and certifi>=2026.10.19.

Highlights

  • Page number metadata now means the same thing in every splitter: the page where a chunk's text starts.
  • BM25 retrieval now correctly handles Chinese, Japanese, and Korean text.
  • ChatPromptBuilder no longer drops content parts when working with ChatMessage templates.
  • RecursiveDocumentSplitter now preserves whitespace and handles overlapping chunks consistently.

New

  • BM25L and BM25Plus scoring options for InMemoryBM25Retriever.
  • BM25 retrieval now filters to return only documents containing at least one query term.

Improved

  • TextCleaner.run now raises clear TypeErrors when inputs are invalid instead of failing silently.
  • RecursiveDocumentSplitter with overlap now returns chunks as they appear in the document.
  • FilterPolicy.MERGE now correctly intersects initialization and runtime logical filters using OR or NOT.
  • ChatMessage.from_openai_dict_format now raises clear errors for unsupported content parts.
  • Pipeline.connect() now handles Callable type annotations without raising TypeError.

Fixed

  • BM25 tokenization for Chinese, Japanese, and Korean text.
  • ChatPromptBuilder dropping content parts with ChatMessage list templates.
  • CompactionHook.close() now properly releases token counter resources.
  • ConfirmationHook no longer drops messages after rewriting conversations.
  • DocumentSplitter and related splitters incorrectly reporting page numbers for chunks beginning with form feeds.
  • RecursiveDocumentSplitter reporting incorrect end pages for chunks spanning page breaks.

September 2026

2 releases: 3.1.1 → 3.2.0

September brought refinements to message handling across multiple integrations, along with significant changes to how tools and components are managed in Haystack. A new token budget control system and conversation compaction capabilities were added to help manage resource usage.

Action needed
  • The + operator for combining Toolsets has been removed; pass Toolsets as a list instead.
  • Toolset.add() now accepts only single Tools, not other Toolsets; use list syntax for combining.
  • Serialized OutputAdapter and ConditionalRouter components with Jinja custom filters must be loaded with Pipeline.load(..., unsafe=True).

Highlights

  • Tool combination syntax changed: use lists instead of the + operator or Toolset.add() for multiple tools.
  • New experimental TokenBudgetHook lets you cap tokens spent in an Agent run.
  • Added stoprun control flag to let hooks end runs cleanly with custom reasons.
  • New SummarizationCompactor progressively summarizes conversations to fit token budgets.
  • Pipeline.addcomponents() method added to register multiple components at once.

New

  • SummarizationCompactor component (experimental) for progressive conversation summarization within token limits.
  • TokenBudgetHook (experimental) to enforce token spending caps on Agent runs.
  • stoprun control flag allowing hooks to end Agent runs gracefully with custom exit reasons.
  • Pipeline.addcomponents() method to register multiple component name-to-instance mappings in one call.

Improved

  • OpenAI Chat Completions and Responses converters now handle assistant messages with no content parts without raising errors.
  • Hugging Face message converter now handles empty assistant messages gracefully by sending them with empty content.
  • toolresultoffloaded meta key now consistently holds a list of store references to support results spanning multiple stores.

Fixed

  • OpenAI Chat Completions converter no longer raises when receiving assistant messages with no content from discarded malformed tool calls.
  • Hugging Face converter error handling for assistant messages with no content parts.

August 2026

1 release: 3.1.0

Haystack 3.1.0 brings improved agent visibility and control, with new cloning capabilities, better resource management, and enhanced PDF handling. The month focused on making agents easier to debug, route, and integrate into complex workflows.

Action needed
  • OutputAdapter and ConditionalRouter components with custom Jinja filters must now be loaded with Pipeline.load(..., unsafe=True).
  • exitreason is now a reserved state key on Agent; custom state schema keys with this name must be renamed or Agent initialization will raise ValueError.

Highlights

  • Agents now report an exitreason output showing why a run stopped, enabling better downstream routing and conditional logic.
  • New Agent.clone() method lets you create copies with modified configuration without rebuilding from scratch.
  • PDF components now support link parsing and formatting, matching existing DOCX functionality.
  • Components using document stores provide close() methods for proper resource cleanup.
  • Hook invocation tracing added to help monitor and optimize agent hook performance.

New

  • Agent.clone() method to create agent copies with optionally replaced initialization parameters.
  • exitreason output on Agent runs reporting the reason for stopping (text, tool call, max iterations, etc.).
  • linkformat parameter for PyPDFToDocument and PDFMinerToDocument to parse and format PDF annotation links.
  • close() and closeasync() methods on document store components for resource cleanup.
  • Tracing spans for every Agent hook invocation with hook point, name, and type details.
  • HAYSTACKUNSAFEDESERIALIZATION environment variable as a process-wide alternative to unsafe=True parameter.

Improved

  • PDF link parsing now available across all PDF extraction components with consistent formatting options.

July 2026

2 releases: 2.31.0 → 3.0.0

July brought significant improvements to evaluation and document handling in version 2.31.0, followed by a major 3.0.0 release that restructures how agents work with skills and tools. The 3.0.0 release includes breaking changes that require attention for existing deployments.

Action needed
  • Human-in-the-Loop is now implemented as ConfirmationHook; existing implementations must be updated.
  • Tools no longer implicitly receive State values by parameter name; must declare inputsfromstate explicitly.
  • Document.id generation changed to deterministic computation from metadata; documents with non-empty meta will have different IDs than in 2.x.
  • Template variables in Agent and PromptBuilder are required by default; use requiredvariables=None to restore old behavior.

Highlights

  • Agents now treat skills as first-class citizens with progressive disclosure, showing only essential information until needed.
  • Tools can now be passed dynamically at runtime, allowing one agent to serve multiple teams and tasks.
  • Native async support added to multiple evaluators and tools for better performance in async applications.
  • Document matching in evaluators now uses content fields instead of auto-generated IDs for more reliable comparisons.
  • Human-in-the-loop workflows are now implemented as hooks rather than special cases.

New

  • SkillToolset discovers skills progressively, reducing context overhead.
  • Dynamic tool selection via tools parameter in run and runasync methods.
  • Native async tools using @tool decorator for async def callables.
  • ToolResultOffloadHook writes large tool results to a store with compact pointers.
  • YAML frontmatter extraction in MarkdownToDocument.
  • Reference range expansion in AnswerBuilder for comma-separated and hyphenated ranges.
  • Output passthrough option in ConditionalRouter for plain variable handling.
  • Asynchronous evaluation support (LLMEvaluator, FaithfulnessEvaluator, ContextRelevanceEvaluator).

Improved

  • DocumentNDCGEvaluator now matches documents by content field instead of auto-generated ID.
  • Document comparison consistency across all evaluators with documentcomparisonfield parameter.
  • Agent template variables now required by default for safer configuration.
  • Document IDs now computed deterministically from canonical JSON of metadata.

June 2026

3 releases: 2.30.0 → 2.30.2

June brought updates to image generation following OpenAI model changes, introduced a new Python-aware code splitter, and fixed agent exit behavior. A minor improvement also made Azure configuration more flexible.

Action needed
  • DALLEImageGenerator default model changed from dall-e-3 to gpt-image-2; quality parameter values changed from standard/hd to auto/high/medium/low; size parameter accepts different values.
  • DALLEImageGenerator responseformat parameter is now ignored.

Highlights

  • DALLEImageGenerator updated to use gpt-image-2 and new OpenAI model, quality, and size parameters.
  • New PythonCodeSplitter component keeps functions and methods intact while splitting Python source files.
  • Agent no longer exits prematurely under default exit conditions.
  • AzureOpenAIChatGenerator now accepts Secrets for endpoint and API version configuration.

New

  • PythonCodeSplitter component for syntax-aware splitting of Python source files.
  • Support for gpt-image-1 and gpt-image-1-mini models in DALLEImageGenerator.
  • New quality values (auto, high, medium, low) for image generation.
  • Arbitrary size support for gpt-image-2 in addition to fixed sizes.
  • Secret parameter support for AzureOpenAIChatGenerator endpoint and API version.

Improved

  • DALLEImageGenerator now always returns base64-encoded JSON format.
  • PythonCodeSplitter uses greedy merging of syntax units (docstrings, imports, functions, classes) into chunks.
  • PythonCodeSplitter falls back to line-based splitting with overlap only when functions exceed oversized threshold.

Fixed

  • Agent premature exit under default exit conditions; now correctly waits for assistant message with text.

May 2026

1 release: 2.29.0

May brought important updates to Haystack's LLM interface, async capabilities, and component reliability. The release includes breaking changes to function signatures alongside improvements to pipeline flexibility and error handling.

Action needed
  • LLM.run and LLM.runasync: messages and streamingcallback must now be passed as keyword arguments, not positional arguments

Highlights

  • LLM.run and LLM.runasync now require keyword arguments for messages and streamingcallback parameters.
  • CacheChecker now supports async execution for use in AsyncPipeline.
  • MultiRetriever component now offers reciprocal rank fusion and concatenation merge modes.
  • Resumable snapshots now handle non-serializable inputs and outputs more gracefully.
  • Fixed tool schema validation in OpenAIChatGenerator to properly enforce constraints on nested objects.

New

  • runasync method added to CacheChecker component
  • joinmode parameter for MultiRetriever supporting reciprocal rank fusion and concatenation strategies
  • LLM now supports two distinct usage modes

Improved

  • Pipeline.connect() now documents input ordering behavior for auto-promoted lazy variadic sockets with multiple senders
  • Resumable snapshots now omit only failing top-level fields instead of entire snapshots when non-serializable objects are encountered
  • LLM interface refactored for clearer keyword argument handling

Fixed

  • NamedEntityExtractor no longer incorrectly modifies spaCy/Thinc device state after execution
  • OpenAIChatGenerator with toolsstrict=True now recursively applies schema constraints to all nested objects in tool parameters

April 2026

2 releases: 2.27.0 → 2.28.0

April brought expanded metadata operations for document stores, improved async support across components, and a migration to httpx for HTTP handling. Several breaking changes were introduced to enforce better practices in agent initialization and LLM configuration.

Action needed
  • Agent.run() and Agent.runasync() now require explicit messages argument; pass an empty list if previously using default None.
  • LLMComponent now requires userprompt to be provided at initialization with at least one Jinja2 template variable.
  • requestwithretry and asyncrequestwithretry no longer raise requests.exceptions.RequestException; error handling changed due to httpx migration.

Highlights

  • InMemoryDocumentStore gained new metadata query operations and full async variants for all filtering and metadata methods.
  • Pipelines now support auto-variadic connections with type conversion, allowing multiple senders to connect to single list-typed inputs.
  • Agent.run() and Agent.runasync() now require explicit messages argument; LLMComponent requires userprompt with at least one template variable.
  • Tools and components can declare a State parameter to receive the live agent State object without extra wiring.
  • HTTP request handling standardized across Haystack by switching from requests to httpx library.

New

  • InMemoryDocumentStore: countdocumentsbyfilter, countuniquemetadatabyfilter, getmetadatafieldsinfo, getmetadatafieldminmax, and getmetadatafielduniquevalues operations.
  • Async variants of InMemoryDocumentStore metadata methods: getmetadatafieldsinfoasync, getmetadatafieldminmaxasync, and getmetadatafielduniquevaluesasync.
  • AzureOpenAIChatGenerator now exposes SUPPORTEDMODELS class variable listing supported model IDs.
  • Partial support for image-text-to-text task in HuggingFaceLocalChatGenerator.
  • totracedict method added to ImageContent and FileContent dataclasses for better trace handling of binary data.
  • Async variants of InMemoryDocumentStore filtering: updatebyfilterasync and countdocumentsbyfilterasync.
  • runasync method added to LLMMetadataExtractor with concurrent ChatGenerator requests.
  • State parameter support in tool and component signatures to receive live agent State object.

Improved

  • Pipelines now support auto-variadic connections with type conversion between multiple senders and single list-typed inputs.
  • Error reporting for failed HTTP requests improved through httpx adoption.
  • ChatPromptBuilder no longer misinterprets specially crafted template variables as structured content.
  • createagentsnapshot made robust to handle serialization errors with fallback and warning logging.
  • LLMMetadataExtractor now runs ChatGenerator requests concurrently using maxworkers parameter.
  • Markdown-producing converter documentation clarified regarding potential output flattening by DocumentCleaner.

Fixed

  • ChatPromptBuilder issue where specially crafted template variables could be interpreted as structured content instead of plain text.
  • createagentsnapshot now handles serialization errors gracefully instead of failing.

March 2026

3 releases: 2.25.2 → 2.26.1

March brought refinements to Agent messaging, expanded LLM model support, and new ranking capabilities. The month focused on flexibility in component configuration and runtime behavior.

Action needed
  • Agent messages runtime parameter changed from required to optional; pipelines relying on previous behavior should be tested.

Highlights

  • LLMRanker component uses LLM-powered JSON output to rerank documents with customizable prompts.
  • Agent system prompts now support Jinja2 template syntax for dynamic message construction.
  • Union-typed list inputs now allow multiple connections to pipeline components.
  • Expanded Python support through Python 3.14 compatibility.
  • AzureOpenAI and OpenAI chat generators expose supported model IDs directly in code.

New

  • LLMRanker component for LLM-based document reranking with PromptBuilder integration.
  • Jinja2 message template syntax support in Agent system_prompt parameter.
  • SearchableToolset customization parameters for bootstrap search tool naming and descriptions.
  • SUPPORTEDMODELS class variable on AzureOpenAIChatGenerator and OpenAIChatGenerator.
  • Python 3.14 support.

Improved

  • Components with union-typed list inputs (e.g. list[str] | list[ChatMessage]) now support multiple input connections.
  • Agent messages runtime parameter is now optional, allowing execution with only user_prompt.
  • LLM component defaults to empty messages list unless provided at runtime.

Fixed

  • ChatPromptBuilder no longer misinterprets specially crafted template variables as structured content like images or tool calls.
  • DocumentCleaner log format string corrected to properly interpolate document IDs in warnings.

February 2026

4 releases: 2.24.0 → 2.25.1

February brought significant improvements to pipeline flexibility and component connections, along with deprecations of older template systems and updates to Hugging Face integration defaults.

Action needed
  • Removed deprecated deserializedocumentstoreinitiparamsinplace function (deprecated in 2.23.0).
  • Removed PipelineTemplate and PredefinedPipeline classes; use Pipeline YAML files instead.
  • Deduplication behavior in Rankers, MultiQueryEmbeddingRetriever, and MultiQueryTextRetriever changed to use document id; users relying on previous deduplication behavior must update their code.
  • Default Hugging Face pipeline task is now text-generation; replace task="text2text-generation" with task="text-generation" or pin transformers<5 to use older behavior.

Highlights

  • Pipelines now support connecting multiple component outputs directly to a single input without requiring a Joiner component.
  • Automatic type conversion between ChatMessage and str types, and between list and single-item types, simplifies pipeline definitions.
  • Removed deprecated PipelineTemplate and PredefinedPipeline classes; users should migrate to Pipeline YAML files.
  • Default Hugging Face pipeline task updated to text-generation; text2text-generation is now deprecated.
  • Fixed smart connection logic for optional list types in flexible pipeline connections.

New

  • Connect multiple list[T] outputs directly to a single list[T] input by automatically combining them.
  • Automatic conversion of list[ChatMessage] to ChatMessage and list[str] to str by taking the first element.
  • List wrapping support: components returning type T can connect to components expecting list[T].
  • Auto variadic sockets now support Optional[list[...]] input types.

Improved

  • Flexible pipeline connections now handle automatic value conversion for Union types.
  • Smart connection logic enhanced to support connecting multiple outputs to Optional[list[...]] sockets.
  • Deduplication in Rankers now uses document id instead of content-based matching.

Fixed

  • Fixed bug in flexible pipeline connections preventing automatic value conversion for Union types.
  • Fixed smart connection logic for multiple outputs to Optional[list[...]] sockets.

January 2026

2 releases: 2.22.0 → 2.23.0

January brought improvements to model support and tracing capabilities, along with changes to pipeline snapshot handling and better serialization for custom components. The month included updates to default models, reasoning content support, and stricter control over pipeline snapshot saving.

Action needed
  • Pipeline snapshot saving is disabled by default; set HAYSTACK_PIPELINE_SNAPSHOT_SAVE_ENABLED=true to restore old behavior.
  • Removed backward compatibility for deserializing pipeline snapshots with the old pipelineoutputs format from before Haystack 2.22.0.
  • Removed returnemptyonnomatch parameter from RegexTextExtractor component; passing it will now raise an error.

Highlights

  • Pipeline snapshots are now disabled by default; enable them with an environment variable if needed.
  • Added reasoning content support to extract chain-of-thought output from models like DeepSeek R1.
  • Improved serialization for custom components with ComponentDevice, Secret, and object attributes.
  • Better nested trace visualization when agents run inside pipelines.
  • Support for modern Python type syntax (X | Y instead of Union[X, Y]).

New

  • Snapshot callback parameter for Pipeline.run() to customize pipeline snapshot handling.
  • Enable thinking parameter for chat templates to generate intermediate reasoning steps.
  • Support for multiple tool string outputs.
  • HAYSTACK_PIPELINE_SNAPSHOT_SAVE_ENABLED environment variable to control snapshot persistence.

Improved

  • HuggingFaceLocalChatGenerator now uses Qwen/Qwen3-0.6B as the default model.
  • SentenceTransformersSimilarityRanker supports querysuffix and documentsuffix parameters for Qwen3 reranker models.
  • Agent tracing spans now use component spans as parents for proper nested visualization.
  • OpenAIChatGenerator handles asyncio.CancelledError exceptions gracefully during streaming.
  • Custom components with ComponentDevice, Secret, or object attributes serialize without explicit todict/fromdict definitions.

Fixed

  • OpenAIChatGenerator streaming now properly closes async loops when tasks are cancelled mid-stream.

December 2025

1 release: 2.21.0

December brought significant enhancements to query handling and retrieval capabilities, with new multi-query components for broader search coverage and updated default models across major LLM providers.

Action needed
  • Default OpenAI model changed from gpt-4o-mini to gpt-5-mini for OpenAIChatGenerator.
  • Default Azure OpenAI model changed from gpt-4o-mini to gpt-4.1-mini and API version updated to 2024-12-01-preview.
  • RegexTextExtractor returnemptyonnomatch parameter defaults to True (returns empty dict) instead of previous behavior.

Highlights

  • QueryExpander generates semantically similar query variations to broaden search coverage.
  • MultiQueryTextRetriever and MultiQueryEmbeddingRetriever run multiple queries in parallel and merge results.
  • FilterRetriever and AutoMergingRetriever now support asynchronous execution.
  • Default LLM models updated to newer versions (gpt-5-mini for OpenAI, gpt-4.1-mini for Azure OpenAI).

New

  • QueryExpander component generates semantically similar variations of user queries.
  • MultiQueryTextRetriever runs multiple text-based queries in parallel and merges results by score.
  • MultiQueryEmbeddingRetriever performs multi-query retrieval using embeddings for richer semantic recall.
  • returnemptyonnomatch parameter added to RegexTextExtractor for controlling empty match behavior.

Improved

  • FilterRetriever now supports asynchronous execution.
  • AutoMergingRetriever now supports asynchronous execution.
  • Azure OpenAI API version updated from 2023-05-15 to 2024-12-01-preview.
  • Default OpenAI model updated to gpt-5-mini for OpenAIChatGenerator.

Summaries are written automatically from the official release notes (full changelog ↗); check the original notes before relying on a detail. Haystack: pricing, features and alternatives · All changelogs