NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #5335 most downloaded on PyPI
LLM framework to build customizable, production-ready LLM applications. Connect components (models, vector DBs, file converters) to pipelines or agents that can interact with your data.
Latest stable
3.5.0
Last release 8 days ago
11 Nov 2026
Ships on a steady schedule
a new release about every 8 days
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
3 years old
277 releases · first in 2023
Drag across the ruler to compare, or tap a release to open it.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
The OpenAI Chat Completions and Responses converters no longer raise on an assistant message with no content parts, which a Chat Generator returns whe
ChatMessage.from_openai_dict_format accepts the same empty content, so such a message round-trips.The OpenAI Chat Completions and Responses converters no longer raise on an assistant message with no content parts, which a Chat Generator returns whe
ChatMessage.from_openai_dict_format accepts the same empty content, so such a message round-trips.Fixed a remote code execution vulnerability that could be triggered by loading an untrusted pipeline in default safe mode (Pipeline.load / Pipeline.lo…
Experimental context compaction for Agent. Runs before LLM calls and shortens the conversation once it crosses a configured fraction of the context window. The built-in SlidingWindowCompactor first removes entire historical turns, then, if needed, individual steps of the current task, replacing what it removes with a short omission note.
A second experimental compaction strategy, ToolResultPruningCompactor, instead of dropping whole turns, replaces older/large tool results with placeholders while keeping the most recent tool-calling steps (and their parallel results) intact.
from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor, ToolResultPruningCompactor
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
hook = CompactionHook(
compactor=SlidingWindowCompactor(), # or ToolResultPruningCompactor(min_keep_steps=2, min_tokens=200),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
tools=[web_search],
hooks={"before_llm": [hook]},
)
New haystack.token_counters module for estimating message/tool-schema size before sending a request (e.g. to decide when to compact). ApproximateTokenCounter needs no dependencies; TiktokenCounter is a local counter, closer estimates for OpenAI models; OpenAITokenCounter calls OpenAI's counting API for exact, model-specific counts.
from haystack.token_counters import OpenAITokenCounter, ApproximateTokenCounter, TiktokenCounter
from haystack.dataclasses import ChatMessage
counter = OpenAITokenCounter("gpt-5-mini")
# No dependencies: estimates from text length.
counter_app = ApproximateTokenCounter(chars_per_token=4.0).count(messages)
# Closer for OpenAI models; needs: pip install tiktoken
counter_tiktoken = TiktokenCounter(encoding="o200k_base").count(messages)
count = counter.count([ChatMessage.from_user("Hello!")])
AgentTool wraps a Haystack Agent as a Tool so another Agent can delegate to it. Only the wrapped Agent's final reply is visible to the caller; its intermediate steps remain outside the main agent's context.
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.tools import AgentTool
researcher = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-mini"),
system_prompt="You are a research specialist. Investigate the task and report your findings.",
tools=[web_search],
)
research_specialist = AgentTool(
agent=researcher,
name="research",
description="Research a question on the web and report the findings",
)
coordinator = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4"),
tools=[research_specialist],
system_prompt="You coordinate specialists. Delegate research questions, then answer the user.",
)
result = coordinator.run([ChatMessage.from_user("What are the latest developments in the Haystack framework?")])
print(result["last_message"].text)
See the multi-agent systems tutorial for a full walkthrough.
Add an Agent.clone() method that returns a new Agent with the same configuration, optionally replacing some init parameters: variant = agent.clone(system_prompt="Answer in German.").
Added a link_format parameter to both PyPDFToDocument and PDFMinerToDocument components, matching the existing functionality in DOCXToDocument. Links are parsed from PDF annotations and appended at the bottom of the page content.
Agent now returns an exit_reason output reporting why the run stopped, making it easier to route the Agent's output downstream (for example with a ConditionalRouter). It is one of: "text" (the model returned a reply with no tool calls), the name of the tool that satisfied a tool exit condition (in which case last_message is that tool's result), or "max_agent_steps" (the Agent hit max_agent_steps before meeting an exit condition). The reason is also available to hooks via state.get("exit_reason"), so an after_run hook can, for instance, append a fallback answer when the step budget is exhausted.
Haystack components that use a document store now provide close and close_async methods for releasing resources. These methods are available on: AutoMergingRetriever, CacheChecker, DocumentWriter, FilterRetriever, and SentenceWindowRetriever. If the underlying Document Store does not implement the corresponding method, calling close or close_async has no effect.
Add a content-free haystack.agent.hook tracing span for every Agent hook invocation. Each span identifies the hook point, hook name, and hook type, allowing hook latency and failures to be attributed without tracing the potentially large Agent State. CompactionHook also adds its configured compaction strategy, estimated context size, whether compaction was triggered, its token target, and whether the compactor returned a replacement.
Added the HAYSTACK_UNSAFE_DESERIALIZATION environment variable as a process-wide equivalent of loading with unsafe=True. When set to a truthy value (1 or true), every Pipeline.load / Pipeline.loads / Pipeline.from_dict call skips all deserialization safety checks — the module allowlist, the builtin/import-primitive and control-plane denylists, the object-internals traversal guard, and the refusal to honor a component's own unsafe: true flag. This is intended for deployments that only ever load fully trusted pipelines and cannot pass unsafe=True at every call site. A warning is logged the first time it takes effect. Only enable it when every pipeline the process loads is trusted: a single untrusted pipeline then leads to arbitrary code execution.
The switch is not limited to pipeline loading: it disables the same checks for every deserialization path in the process, including ones that take no unsafe argument of their own — Tool.from_dict, State.from_dict (agent snapshot resume), and the ConditionalRouter and OutputAdapter Jinja sandbox flags. A deployment that loads trusted pipelines at startup but accepts serialized tools or agent state at request time is therefore exposed on the request path as well, not only at load time.
The variable is read once, on the first deserialization in the process, and the result is then frozen for the process lifetime: writes to it afterwards are ignored, in either direction. Set it before the first pipeline is loaded. Freezing keeps the safety mode of a process from changing under a caller's feet and, because the first read happens before any deserialized data can run, stops a hostile pipeline from switching the checks off while it is being loaded.
Serialized OutputAdapter and ConditionalRouter components containing Jinja custom_filters must now be loaded with Pipeline.load(..., unsafe=True) (or the equivalent Pipeline.loads / Pipeline.from_dict option).
exit_reason is now a reserved state key on Agent. If you defined a custom state_schema key named exit_reason, rename it: the Agent now raises a ValueError at initialization when a reserved key is redefined.
Agent.state_schema now contains the user-provided state schema, exactly as passed to __init__. Previously it contained the resolved schema, which also included messages and the keys the Agent manages internally (step_count, token_usage, exit_reason, ...). If you were reading agent.state_schema to inspect the effective runtime schema, use the new public attribute agent.resolved_state_schema instead.
DocumentMAPEvaluator scores can change because average precision now uses all unique, valid ground-truth comparison values as its denominator and credits each value at most once. Re-baseline evaluations that relied on the previous scores.
PipelineSnapshot.pipeline_state.inputs changed shape. It used to store one flattened value per socket, {component: {socket: value}}. It now stores the pipeline's internal inputs, keeping the component that sent each one in the order it arrived: {component: {socket: [{"sender": ..., "value": ...}]}}. PipelineState gained an inputs_format field recording which of the two shapes a snapshot uses. The same applies to BreakpointException.inputs, which returns that field.
You are affected if you read pipeline_state.inputs (or BreakpointException.inputs) directly, for example to display or post-process a snapshot. Resuming a pipeline with Pipeline.run(pipeline_snapshot=...) is not affected, and neither is code that only passes snapshots around or persists them.
To adapt, read the input from the list and take its value:
inputs = snapshot.pipeline_state.inputs["serialized_data"]
# before
value = inputs["my_component"]["my_socket"]
# now
value = inputs["my_component"]["my_socket"][0]["value"]
A socket that received inputs from several senders has one list item per input, each recording the sender that produced it.
Snapshots written by earlier versions of Haystack have inputs_format set to None and keep the flattened shape, so branch on that field if you need to handle both.
Loading a serialized OutputAdapter or ConditionalRouter whose unsafe init parameter is set to true now raises DeserializationError unless the pipeline is loaded in unsafe mode. Pipelines that legitimately rely on an unsafe OutputAdapter/ConditionalRouter embedded in serialized data must now load with Pipeline.load(..., unsafe=True) (or Pipeline.loads / Pipeline.from_dict with unsafe=True).
Passing window_size=0 to SentenceWindowRetriever.run or SentenceWindowRetriever.run_async now raises a ValueError instead of silently using the window_size set in the constructor. You are affected if you pass window_size=0 at runtime, either directly or from an upstream component in a pipeline. If you were relying on 0 to mean "use the value from the constructor", omit the argument (or pass None) instead:
InMemoryDocumentStore.get_metadata_field_unique_values (and its async counterpart)'s search_term parameter now matches against the metadata field's own value (case-insensitive substring) instead of the document's content. Callers relying on the previous content-matching behavior will need to filter documents by content themselves before calling this method.
The Agent now warms up its hooks before every run, not only the first one, as it already does for Tools and Toolsets. If your hook has a warm_up() that does expensive setup (opening a client, loading a model), make it return early once done, for example if self._client is not None: return.
Haystack can call warm_up() on Tools and Toolsets more than once, for example before every run. Previously Toolset absorbed repeated calls with an internal _is_warmed_up flag; that flag is gone and every call now reaches your warm_up(). If your custom Tool or Toolset does expensive work there (connecting to a server, loading a model), or relied on the _is_warmed_up attribute, guard with your own state and return early, for example if self._client is not None: return.
Fixed the serialization of PDFMinerToDocument. The component did not define to_dict, so the default serialization fell back to reading the init parameters from same-named attributes. Since the layout parameters are stored in self.layout_params, they were silently serialized with their default values, for example a component created with char_margin=0.5 was serialized with char_margin=2.0. Custom layout parameters are now preserved when a pipeline is serialized and loaded again.
Cancel and await sibling retrieval tasks when a concurrent call fails in MultiRetriever, MultiQueryTextRetriever, or MultiQueryEmbeddingRetriever.
Fixed an infinite recursion in CSVDocumentSplitter when nested row and column blocks were split together.
Comparing two Document objects with == now takes all metadata into account. Previously, two documents with different metadata could be considered equal if the metadata contained keys with the same names as document fields (such as id or content).
Document.from_dict(document.to_dict()) now correctly rebuilds any document. Previously, if the metadata contained keys with the same names as document fields (such as id or meta), this either raised an error or silently lost those metadata entries.
Fixed DocumentNDCGEvaluator producing NDCG scores outside the documented 0.0 to 1.0 range when the same document appeared more than once. A document retrieved multiple times used to be counted multiple times, pushing the score above 1.0; a ground truth document listed multiple times used to inflate the ideal gain, keeping a perfect retrieval below 1.0. Each distinct relevant document is now counted once, with the same relevance, in both the actual and ideal gain, so scores stay within range.
Fix FilterPolicy.MERGE in InMemoryBM25Retriever and InMemoryEmbeddingRetriever so initialization filters are combined with runtime comparison filters instead of being silently overwritten.
Fixed AnswerBuilder returning referenced documents in a scrambled order instead of ascending source-index order. The referenced document indices were collected in a set and iterated directly, so documents were emitted in the set's internal hash-table order (e.g. citations [3] [10] [50] yielded documents ordered 10, 3, 50). This order was deterministic but did not match the intuitive source order. The referenced documents are now returned sorted by their source index.
Fixed serialize_type and deserialize_type to correctly round-trip Callable types that declare an explicit parameter list, such as Callable[[int, str], bool]. Previously the parameter list was dropped during serialization (producing a malformed string like typing.Callable[, bool]) and could no longer be deserialized. This affected components that serialize type annotations, for example ConditionalRouter and OutputAdapter using a Callable output type.
Fix DocumentMAPEvaluator to include missed relevant documents in the average precision denominator and avoid crediting duplicate retrievals of the same document.
Fixed DocumentSplitter producing chunks that were not present in the source document when split_threshold was set together with split_overlap. Merging a below-threshold trailing segment into the previous split re-appended the overlapping units, duplicating text. The overlap is now added only once.
Fixed EmbeddingBasedDocumentSplitter.run_async embedding through the synchronous path while recursively splitting chunks longer than max_length. Only the first pass was async: the recursion called the sync splitting helper, so the embedder's blocking run ran on the event loop for every over-long chunk. The recursion now embeds through run_async as well.
Fixed JSONConverter raising a KeyError instead of logging its intended "Failed to extract text, skipping it" warning when a source is a ByteStream without a file_path in its meta (for example ByteStream.from_string(...), the exact usage shown in the component's own docstring examples). Affected error paths: invalid UTF-8 content, a jq_schema filter that fails to apply, and malformed JSON content.
Fixed LinkContentFetcher rotating the User-Agent on a cursor shared by every URL in the same run()/run_async() call. The URLs are fetched concurrently, so a retry triggered by one of them advanced the user agent for the others, and each completed fetch reset the cursor for the requests still in flight — most retries went out with the un-rotated user agent. Each fetch now walks the user_agents list on its own, so a URL rotates exactly as documented no matter how many other URLs are fetched alongside it.
Fixed MarkdownHeaderSplitter silently dropping a trailing header that has no body text. With keep_headers=True (the default), a header at the end of the document whose only content is whitespace was buffered to prepend to the next chunk, but with no following chunk it was never emitted, so the split documents no longer reconstructed the original text. Such trailing headers are now emitted as a final chunk.
Fixed MarkdownHeaderSplitter collapsing blank lines that follow a header with no body text. With keep_headers=True, such headers were re-joined with a single newline when prepended to the next chunk, so the split documents did not reconstruct the original text. Chunk content is now sliced from the original text and is byte-exact.
Fixed MarkdownHeaderSplitter including surrounding whitespace in the header and parent_headers metadata fields. The header text is now stripped; chunk content still keeps the header line's original whitespace.
Fixed schema-based serialization of lists, tuples and sets holding mixed types. Previously the schema was derived from the first element only, so deserializing such a value raised an AttributeError or silently returned mis-typed data (for example an Agent State field or a pipeline breakpoint input holding [Document(...), "text", 3]). Mixed-type arrays now record one schema per position using the JSON Schema prefixItems keyword and round-trip correctly. Homogeneous arrays keep the exact same output as before, so existing snapshots still load.
Fixed MSGToDocument raising a KeyError when converting a ByteStream source that has no file_path in its meta (for example a bare ByteStream(data=...), rather than a file path or a stream produced via ByteStream.from_file_path). Attachments extracted from such a source no longer include a parent_file_path key, since there is no source file path to record.
Pipeline connections now always convert values in the same way. When a component output is connected to an input that accepts multiple types, Haystack is sometimes able to automatically convert the value, and more than one conversion may be possible. For example, a ChatMessage with text "hello" connected to an input annotated str | list[str] can be delivered either as plain text ("hello") or as a list containing the text (["hello"]). Previously the conversion strategy was chosen non-deterministically, so the same pipeline could return a different value across runs. The conversion strategy is now selected using a fixed priority: first, wrapping a value in a list or unwrapping a single-element list; second, converting between ChatMessage and str; and last, combining both conversions.
Fixed normalize_metadata (used by all file converters) returning the same dictionary object for every source when meta is None or a single dictionary. Each source now receives an independent copy, so mutating one source's metadata downstream no longer leaks into the others.
OpenAIResponsesChatGenerator no longer mutates the parameters schema of the Tool objects passed to it. Previously every run wrote additionalProperties: False into the user's live Tool.parameters, silently altering the tool for any other generator that shared the same Tool instance and making serialization round trips unstable.
OpenAIResponsesChatGenerator no longer raises IndexError when it is warmed up with an empty tools list.
Fixed the parent of the haystack.agent.step.tool spans when an Agent step invokes several tools. The parent span is now resolved once before the tools run, so all tool calls of a step appear as siblings. Previously each span asked the tracer for the currently active span from inside its own concurrent invocation, which made the tool calls after the first one appear nested under a sibling tool call.
Fixed the haystack.pipeline.output_data tracing tag being empty. The tag was set at the start of Pipeline.run/run_async from the still-empty outputs, and since tracing backends coerce a tag value when it is set, the recorded output was always an empty dictionary. It is now set once the run completes so it reflects the final pipeline outputs. The tag is also gated behind content tracing (HAYSTACK_CONTENT_TRACING_ENABLED), consistent with the component-level input/output tags.
Fixed resuming a Pipeline from a pipeline_snapshot that was taken on a component's second or later visit, which failed with PipelineComponentsBlockedError: Cannot run pipeline - all components are blocked. A snapshot stored only the values of the pipeline's inputs and dropped the information about which component had sent each one, so on resume every restored input looked like it came from outside the pipeline, and such an input can only trigger a component on its first visit. Snapshots now record the sender of each input. Snapshots created by earlier versions of Haystack behave as before, so re-create them to resume anywhere in a looping pipeline.
Fixed a resumed Pipeline passing malformed inputs to the component the snapshot was taken on, whenever that component ran more than once after the resume, for example inside a loop. Every visit after the first reused the handling meant only for the paused visit and skipped the regular input consumption, so a variadic component could receive a bare value where it expected a list, raising errors such as TypeError: object of type 'int' has no len() from a BranchJoiner. This affected snapshots taken at any visit count, including the first.
Fixed QueryExpander returning duplicate queries when the chat generator repeats an expansion. Generated queries are now deduplicated while preserving first-seen order, so repeated expansions no longer trigger redundant retrievals or consume the requested expansion budget. Both run and run_async are affected.
RecursiveDocumentSplitter's word-mode fixed-size fallback no longer counts a run of whitespace (e.g. a double space, tab, or page break) as a word, so it no longer produces chunks smaller than split_length. It also no longer emits a whitespace-only chunk when the text ends in whitespace right after a chunk boundary; that trailing whitespace is now attached to the previous chunk instead. This changes the exact chunk boundaries and chunk count produced by the word-unit fallback for any text containing such whitespace runs. Documents already split and indexed under the old behavior will produce different chunks if re-split after upgrading, so re-index any document store that relies on stable chunk boundaries from this fallback path.
Fixed an issue where PipelineBase.remove_component did not reset auto-variadic socket flags (is_lazy_variadic and wrap_input_in_list) on input sockets when components or connections were removed.
Fixed Pipeline.remove_component leaving dangling references to the removed component on the sockets of its neighboring components. Previously, removing a component reset only its own sockets, so a surviving neighbor kept the removed component's name in its input socket's senders (or output socket's receivers). This corrupted introspection and validation: Pipeline.inputs() hid a now-unconnected mandatory input, and feeding that input directly could raise a spurious "already connected" error. The removed component's name is now stripped from its neighbors' sockets as well.
SentenceWindowRetriever.run and SentenceWindowRetriever.run_async now validate an explicitly provided window_size=0 instead of treating it as unset and falling back to the constructor value.
Fixed the schema-aware serialization helper used for pipeline snapshots and Agent State (_serialize_value_with_schema) so it no longer silently passes unsupported objects through as if they were serialized. Values such as datetime, bytes, complex and arbitrary objects without a to_dict method were previously stored unchanged and mislabeled as strings, which broke JSON storage and round-tripping of snapshots. Unsupported values now raise a SerializationError, and the callers that build snapshots (pipeline breakpoints and State.to_dict) catch it to omit only the offending field while keeping the rest of the payload resumable.
Added support for serializing and deserializing frozenset values in _serialize_value_with_schema. A frozenset now round-trips back to a frozenset instead of being dropped.
Fixed serialize_type/deserialize_type for typing.Literal. Previously a Literal type hint was serialized with its values rendered as bare tokens (e.g. typing.Literal[yes, no]), which failed to deserialize, and values that looked like type names (e.g. Literal["int", "str"]) were silently turned into types on the round-trip. The values are now serialized with repr() and read back with ast.literal_eval, so a Literal type used by a component (such as OutputAdapter or ConditionalRouter) round-trips correctly through pipeline serialization.
Fixed an AttributeError: 'str' object has no attribute 'items' raised by create_tool_from_function, the @tool decorator, and ComponentTool when a tool parameter is named properties. Keys inside a JSON schema properties mapping are property names and are no longer misinterpreted as schema keywords when stripping the auto-generated title keywords.
Fixed create_tool_from_function, the @tool decorator, and ComponentTool corrupting a tool's JSON schema when the string title appears as a name rather than as a schema keyword. Stripping the auto-generated title keywords no longer deletes entries of $defs, definitions, patternProperties, dependentSchemas or dependentRequired (which would leave a $ref dangling or silently drop a validation rule), and no longer edits title keys inside default, const, enum or examples values, which are instance data and part of the tool's contract.
Fixed _ToolsetWrapper.__getitem__ (used when combining Toolsets with +) raising IndexError for negative indices, unlike a plain Toolset. Indexing a combined toolset now behaves consistently with a list of Tools, as documented.
Fixed serialization of types that contain ... (Ellipsis), such as variadic tuples (tuple[int, ...]) and Callable[..., X]. Previously serialize_type rendered the ... as the literal string "Ellipsis", which deserialize_type then rejected as a non-type builtin, so a component using such a type (for example OutputAdapter(output_type=tuple[int, ...])) could be serialized but not deserialized, breaking Pipeline.loads() / Pipeline.load(). These types now round-trip correctly, and pipelines serialized by older versions (which emitted "Ellipsis") can still be loaded.
Fixed ConfirmationHook applying a Human-in-the-Loop decision to the wrong tool call when a custom ConfirmationStrategy returns a decision with a missing or incorrect tool_call_id. Each decision is now bound to the tool call for which its strategy ran, and ID-bearing decisions are no longer matched to a different call by name. Haystack's existing requirement of exactly one decision per tool call is now explicitly enforced. Each matched decision is consumed after use, so a missing, unused, or reused decision raises a ValueError instead of being silently misapplied.
DocumentJoiner and AnswerJoiner now resolve top_k consistently and validate it. Previously, a runtime top_k=0 was treated as "unset" and silently fell back to the instance's top_k, instead of returning an empty list as requested. Both components now:
ValueError at initialization if top_k is not None and is less than or equal to 0.ValueError at runtime if top_k passed to run() is negative.run() is called with top_k=0, regardless of the instance's configured top_k.Fixes MetaFieldRanker silently treating a runtime top_k=0 as unset and falling back to the value configured at initialization. Runtime values that are not greater than zero now raise a ValueError as documented.
Fixed PythonCodeSplitter losing identifying context for oversized functions, methods, or classes. When a unit is too large and falls back to line-based secondary splitting, only the first resulting piece naturally retains the source def/class line; every piece now includes a qualified_name field in meta identifying the function, method, or class it came from.
Fixed RecursiveDocumentSplitter not setting the source_id meta field on the chunks it produces. It wrote only parent_id, while every other splitter in the library (DocumentSplitter, CSVDocumentSplitter, EmbeddingBasedDocumentSplitter, HierarchicalDocumentSplitter, MarkdownHeaderSplitter and PythonCodeSplitter) writes source_id. Components that follow that convention therefore rejected its output: SentenceWindowRetriever reads source_id by default and raises when it is absent, so it failed with "The retrieved documents must have 'source_id' in their metadata." on a pipeline that worked with any other splitter. Chunks now carry source_id as well as parent_id, which keeps its previous value for callers already reading it.
Tool functions defined in a module using from __future__ import annotations are now inspected correctly by Agent. Postponed annotations are stored as strings, so a parameter annotated with State was not recognized and the live State object was not injected into the tool call. The annotations are now resolved before they are inspected.
MarkdownHeaderSplitter and CSVDocumentSplitter now deep-copy the metadata of the document they split, matching DocumentSplitter. Previously they copied it shallowly, so nested values such as a list under meta["tags"] were shared between every chunk and with the input document, and editing one chunk's metadata changed all the others. HierarchicalDocumentSplitter had the same problem on its root node, which kept references into the input document's metadata.
Keep an Agent's execution counter in sync with step_count restored by a before_run hook, so restarted Agents continue from the saved step instead of resetting the count.
Prevent arbitrary callables registered as serialized Jinja custom filters from executing while a pipeline is loaded in safe mode. Jinja can invoke filters with constant arguments during template compilation, and its sandbox does not apply callable-safety checks to filters.
Harden callable deserialization by checking the real module of every object traversed in a dotted callable path. This prevents an allowlisted module from exposing an object defined in an unallowlisted module that leads back to an otherwise allowlisted final callable.
Fixed a remote code execution vulnerability that could be triggered by loading an untrusted pipeline in default safe mode (Pipeline.load / Pipeline.loads / Pipeline.from_dict, without unsafe=True). A malicious pipeline could either (a) set unsafe: true on an OutputAdapter or ConditionalRouter to disable the Jinja sandbox entirely, or (b) register the thread_safe_import import primitive as a Jinja custom_filters entry to import os and execute arbitrary commands — bypassing the deserialization allowlist and Jinja sandbox. The fix denies import primitives during callable deserialization, refuses to honor a component's unsafe flag while loading in safe mode, and hardens the Jinja sandbox (OutputAdapter, ConditionalRouter, PromptBuilder, ChatPromptBuilder) to block attribute access on module objects and calls into dangerous modules.
Closed an additional remote code execution vector in the deserialization control-plane hardening: the pipeline loading entry points (Pipeline.loads / Pipeline.load / Pipeline.from_dict, which accept unsafe=True) and the execute primitives (Pipeline.run / run_async / run_async_generator / stream) were still resolvable from the allowlisted haystack namespace. Bound as a custom_filters entry on an OutputAdapter or ConditionalRouter (which bypass the Jinja sandbox), Pipeline.loads(..., unsafe=True) let a pipeline loaded in default safe mode load a nested pipeline whose own filters (allow_deserialization_module, deserialize_callable) bind under the nested unsafe context, disarming the process-wide allowlist with "*" and invoking os.system. All of these entry points are now marked as deserializer-internal, so they can never be produced by deserializing untrusted data. unsafe=True still bypasses the check by design; there are no public API changes.
Fixed a remote code execution vulnerability that could be triggered by loading an untrusted pipeline in default safe mode (Pipeline.load / Pipeline.loads / Pipeline.from_dict, without unsafe=True). Because the deserialization allowlist admits the whole haystack namespace, the deserializer's own allowlist-administration function (allow_deserialization_module) and its resolution helpers (deserialize_callable, deserialize_type, import_class_by_name) were themselves resolvable from serialized data. A malicious pipeline could register allow_deserialization_module as a Jinja custom_filters entry (on an OutputAdapter or ConditionalRouter), call it with "*" to disarm the allowlist process-wide, and then use the equally-resolvable deserialize_callable to resolve and invoke os.system. Loading alone was enough to trigger this: a Jinja filter called with constant arguments runs while the component is being constructed, so the pipeline never had to be run. The same attribute walk could also reach the deserializer's mutable control-plane state directly — for example a filter bound to _extra_allowed_modules.append — to widen the allowlist persistently and stage a later attack. Relatedly, the handle resolver walked attribute names freely, so a handle could descend into object internals such as <function>.__globals__ (a live module namespace, and via it __builtins__ and eval/exec) or <type>.__subclasses__ — classic sandbox-escape gadgets that stay inside an allowlisted module. The fix refuses to deserialize the deserialization control plane as a whole: the allowlist administration and resolution helpers (marked at definition time), everything defined in haystack.core.serialization_security, and any bound method of the mutable allowlist/context state. It also refuses to traverse into dunder and frame/code attributes while resolving a handle. This applies to both the callable- and class-resolution paths, and is bypassed only when the pipeline is loaded with unsafe=True.
Harden FileSystemToolResultStore.read() so it only reads references that resolve within the configured store root. This closes a boundary gap where callers could previously pass an arbitrary filesystem path to read() instead of a store-scoped reference returned by write().
Extracted DOCXLinkFormat to a reusable LinkFormat Enum in haystack/components/converters/utils.py. DOCXLinkFormat is now an alias for backward compatibility.
The Agent now tracks an approximate current context-window size in its internal State under context_tokens, refreshed after every LLM call with that reply's prompt-plus-completion tokens (normalized across the prompt_tokens/completion_tokens and input_tokens/output_tokens key conventions). Unlike token_usage, which accumulates across the whole run, context_tokens is replaced each call. Hooks can read it via state.get("context_tokens") — for example, a before_llm hook that triggers context compaction once the value crosses a threshold. It is a best-effort snapshot: it is 0 when the generator does not report usage, and does not count messages appended after the latest call until the next call refreshes it.
before_run hooks can now read state.data["tools"]. The key was previously written only once the first step had started, so a before_run hook hit a KeyError. It holds a snapshot of the tools available at that point, refreshed before every LLM call, so with a dynamic toolset such as SearchableToolset a before_run hook sees only the tools discovered so far.
Added an opt-in strict_datetime_comparison keyword argument to document_matches_filter, InMemoryDocumentStore, and MetadataRouter. When enabled, timezone-naive and timezone-aware datetimes never match each other. By default, mixed-awareness datetimes continue to be reconciled by copying the timezone from the aware value to the naive one, and this behavior is now consistent across equality, membership, and ordering operators.
Added a filters parameter to InMemoryDocumentStore.get_metadata_field_unique_values (sync and async), allowing the set of documents considered when computing unique metadata field values to be restricted.
InMemoryDocumentStore.get_metadata_field_unique_values and its async counterpart now support pagination via from_ and size parameters, matching the behavior of other Document Stores (e.g. Chroma).
MockChatGenerator's response_fn can now be tool-aware. If the callable accepts a second positional argument, it also receives the tools passed to run/run_async (a ToolsType or None), so a dynamic mock can build tool calls whose arguments follow the tool's parameter schema or route between the available tools. Existing single-argument response_fn callables are unaffected and keep receiving only the messages.
State.to_dict now accepts a skip_keys parameter to exclude specific keys from the output.
Add a tracing span per ConfirmationStrategy run to ConfirmationHook. Each haystack.agent.hook.human_in_the_loop.strategy span identifies the tool call it confirms and records the strategy type and the applied confirm, modify, or reject decision. When content tracing is enabled, spans also carry the arguments the strategy was run with and the ToolExecutionDecision it returned under haystack.agent.hook.human_in_the_loop.strategy.input and haystack.agent.hook.human_in_the_loop.strategy.output; chat messages, the confirmation strategy context, and the Agent State are not recorded by the hook.
LLMEvaluator, LLMRanker, QueryExpander, LLMMetadataExtractor, LLMDocumentContentExtractor and LLMMessagesRouter now wrap their internal ChatGenerator calls in a haystack.chat_generator.run tracing span. These components do not return ChatMessage objects, so the LLM token usage carried in reply.meta["usage"] was previously lost to tracers. The new span exposes the generator's replies via the haystack.component.output tag, so token usage is now visible in traces (requires content tracing to be enabled). When the generator runs across threads, the span is nested under the component's span.
+ operator (toolset_a + toolset_b) and passing a Toolset to add() (toolset_a.add(toolset_b)). Pass Toolsets as a list wherever tools are accepted instead: Agent(tools=[toolset_a, toolset_b]).@Aarkin7, @anakin87, @anxkhn, @aquib8112, @Aryan-Pardeshi, @atikulmunna, @bharadwaj-pendyala, @bilgeyucel, @bogdankostic, @camgrimsec, @chuenchen309, @davidpavlovschi, @davidsbatista, @DhanushPillay, @DivyaNarahari97, @erikos, @GovindhKishore, @hxaxd, @immuhammadfurqan, @iridescentWen, @jaideeppyne, @julian-risch, @kacperlukawski, @KXHXK, @LHMQ878, @LK-maker-007, @lntutor, @manjunathbhaskar, @mittalpk, @MVS-source, @onatozmenn, @otiscuilei, @pcbeingused333, @rautaditya2606, @sjrl, @sohumt123, @Solaris-star, @TimurRakhmatullin86, @vidigoat, @vinkiYu, @winklemad, @yaodong-shen
Fixed a remote code execution vulnerability that could be triggered by loading an untrusted pipeline in default safe mode ( Pipeline.load / Pipeline.l…
OutputAdapter and ConditionalRouter components containing Jinja custom_filters must now be loaded with Pipeline.load(..., unsafe=True) (or the equivalent Pipeline.loads / Pipeline.from_dict option).Added the HAYSTACK_UNSAFE_DESERIALIZATION environment variable as a process-wide equivalent of loading with unsafe=True. When set to a truthy value (1 or true), every Pipeline.load / Pipeline.loads / Pipeline.from_dict call skips all deserialization safety checks — the module allowlist, the builtin/import-primitive and control-plane denylists, the object-internals traversal guard, and the refusal to honor a component's own unsafe: true flag. This is intended for deployments that only ever load fully trusted pipelines and cannot pass unsafe=True at every call site. A warning is logged the first time it takes effect. Only enable it when every pipeline the process loads is trusted: a single untrusted pipeline then leads to arbitrary code execution.
The switch is not limited to pipeline loading: it disables the same checks for every deserialization path in the process, including ones that take no unsafe argument of their own — Tool.from_dict, State.from_dict (agent snapshot resume), and the ConditionalRouter and OutputAdapter Jinja sandbox flags. A deployment that loads trusted pipelines at startup but accepts serialized tools or agent state at request time is therefore exposed on the request path as well, not only at load time.
The variable is read once, on the first deserialization in the process, and the result is then frozen for the process lifetime: writes to it afterwards are ignored, in either direction. Set it before the first pipeline is loaded. Freezing keeps the safety mode of a process from changing under a caller's feet and, because the first read happens before any deserialized data can run, stops a hostile pipeline from switching the checks off while it is being loaded.
exit_reason is now a reserved state key on Agent. If you defined a custom state_schema key named exit_reason, rename it: the Agent now raises a ValueError at initialization when a reserved key is redefined.
Agent.state_schema now contains the user-provided state schema, exactly as passed to __init__. Previously it contained the resolved schema, which also included messages and the keys the Agent manages internally (step_count, token_usage, exit_reason, ...). If you were reading agent.state_schema to inspect the effective runtime schema, use the new public attribute agent.resolved_state_schema instead.
DocumentMAPEvaluator scores can change because average precision now uses all unique, valid ground-truth comparison values as its denominator and credits each value at most once. Re-baseline evaluations that relied on the previous scores.
PipelineSnapshot.pipeline_state.inputs changed shape. It used to store one flattened value per socket, {component: {socket: value}}. It now stores the pipeline's internal inputs, keeping the component that sent each one in the order it arrived: {component: {socket: [{"sender": ..., "value": ...}]}}. PipelineState gained an inputs_format field recording which of the two shapes a snapshot uses. The same applies to BreakpointException.inputs, which returns that field.
You are affected if you read pipeline_state.inputs (or BreakpointException.inputs) directly, for example to display or post-process a snapshot. Resuming a pipeline with Pipeline.run(pipeline_snapshot=...) is not affected, and neither is code that only passes snapshots around or persists them.
To adapt, read the input from the list and take its value:
inputs = snapshot.pipeline_state.inputs["serialized_data"]
# before
value = inputs["my_component"]["my_socket"]
# now
value = inputs["my_component"]["my_socket"][0]["value"]A socket that received inputs from several senders has one list item per input, each recording the sender that produced it.
Snapshots written by earlier versions of Haystack have inputs_format set to None and keep the flattened shape, so branch on that field if you need to handle both.
Loading a serialized OutputAdapter or ConditionalRouter whose unsafe init parameter is set to true now raises DeserializationError unless the pipeline is loaded in unsafe mode. Pipelines that legitimately rely on an unsafe OutputAdapter/ConditionalRouter embedded in serialized data must now load with Pipeline.load(..., unsafe=True) (or Pipeline.loads / Pipeline.from_dict with unsafe=True).
Passing window_size=0 to SentenceWindowRetriever.run or SentenceWindowRetriever.run_async now raises a ValueError instead of silently using the window_size set in the constructor. You are affected if you pass window_size=0 at runtime, either directly or from an upstream component in a pipeline. If you were relying on 0 to mean "use the value from the constructor", omit the argument (or pass None) instead:
retriever = SentenceWindowRetriever(document_store=document_store, window_size=3)
# Before: silently used window_size=3
retriever.run(retrieved_documents=docs, window_size=0)
# After: omit the argument to use the constructor value
retriever.run(retrieved_documents=docs)InMemoryDocumentStore.get_metadata_field_unique_values (and its async counterpart)'s search_term parameter now matches against the metadata field's own value (case-insensitive substring) instead of the document's content. Callers relying on the previous content-matching behavior will need to filter documents by content themselves before calling this method.
The Agent now warms up its hooks before every run, not only the first one, as it already does for Tools and Toolsets. If your hook has a warm_up() that does expensive setup (opening a client, loading a model), make it return early once done, for example if self._client is not None: return.
Haystack can call warm_up() on Tools and Toolsets more than once, for example before every run. Previously Toolset absorbed repeated calls with an internal _is_warmed_up flag; that flag is gone and every call now reaches your warm_up(). If your custom Tool or Toolset does expensive work there (connecting to a server, loading a model), or relied on the _is_warmed_up attribute, guard with your own state and return early, for example if self._client is not None: return.
Added a link_format parameter to both PyPDFToDocument and PDFMinerToDocument components, matching the existing functionality in DOCXToDocument. Links are parsed from PDF annotations and appended at the bottom of the page content.
Added experimental context compaction for the Agent. CompactionHook runs before LLM calls and shortens the conversation when it reaches a configured fraction of the model's context window.
The first built-in strategy, SlidingWindowCompactor, preserves leading system messages, the latest user task, and as much complete recent conversation as the target allows. It removes complete historical turns first, and only when removing every historical turn is insufficient does it remove individual Agent steps from the current task. It replaces removed history with a short omission note, left where the removed messages used to sit: directly after the leading system messages when only historical turns were removed, and directly after the latest user message when the current task's own steps were removed. Only one note is ever present, because a later compaction folds an earlier one into its replacement.
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
hook = CompactionHook(
compactor=SlidingWindowCompactor(),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
tools=[web_search],
hooks={"before_llm": [hook]},
)The hook uses provider-reported context usage when available and locally estimates the request otherwise, including tool schemas. Leave headroom above compact_at for the next reply and its tool results.
SlidingWindowCompactor treats an assistant message and its following tool results as one step, so a tool call is never separated from its results. Historical turns are likewise kept or removed in full, so an assistant reply is not retained without the user message it answers. It can also land above the requested target rather than under it, because leading system messages and the current task are never removed and min_keep_steps holds on to the newest Agent steps whatever their size, so a long system prompt or one large tool result can leave the conversation well over the target. Compaction is lossy: removed messages cannot be recovered or summarized by this strategy. Implement the Compactor protocol to provide a custom strategy.
CompactionHook and SlidingWindowCompactor emit an ExperimentalWarning and may change without a deprecation cycle.
Agent now returns an exit_reason output reporting why the run stopped, making it easier to route the Agent's output downstream (for example with a ConditionalRouter). It is one of: "text" (the model returned a reply with no tool calls), the name of the tool that satisfied a tool exit condition (in which case last_message is that tool's result), or "max_agent_steps" (the Agent hit max_agent_steps before meeting an exit condition). The reason is also available to hooks via state.get("exit_reason"), so an after_run hook can, for instance, append a fallback answer when the step budget is exhausted.
Add OpenAITokenCounter, which uses OpenAI's input token counting API to return model-specific counts for Haystack ChatMessage objects and optional tool schemas. Unlike local estimates, it supports OpenAI's exact accounting for request formatting, images, files, and tools.
Here is an example:
from haystack.dataclasses import ChatMessage
from haystack.token_counters import OpenAITokenCounter
counter = OpenAITokenCounter("gpt-5-mini")
count = counter.count([ChatMessage.from_user("Hello!")])Added haystack.token_counters: a TokenCounter protocol for estimating how many tokens a list of ChatMessage objects occupies, with two implementations.
Providers report token usage only after a call, and only for the call as a whole, so anything that needs a size beforehand - deciding whether a conversation still fits a model's context window, or how much of it to drop - has to estimate one.
from haystack.dataclasses import ChatMessage
from haystack.token_counters import ApproximateTokenCounter, TiktokenCounter
messages = [ChatMessage.from_user("Hello, how are you?")]
# No dependencies: estimates from text length.
ApproximateTokenCounter(chars_per_token=4.0).count(messages)
# Closer for OpenAI models; needs: pip install tiktoken
TiktokenCounter(encoding="o200k_base").count(messages)ApproximateTokenCounter needs nothing installed and estimates from text length at a configurable chars_per_token. TiktokenCounter counts with OpenAI's byte-pair encoder, which is closer for OpenAI models but requires tiktoken and drifts on other providers; it raises at construction when the dependency is missing, and loads its encoding on first use.
Neither can measure an image or a file, since a tokenizer only sees text and providers derive an image's cost from its dimensions. Both charge a flat tokens_per_image and tokens_per_file instead, counting images a tool returned inside its result as well as those a message carries directly. Raise those values if you send large images or long documents.
Tool schemas are sent alongside the messages and consume tokens too, so count takes an optional tools argument to have them included:
counter.count(messages, tools=[my_tool])Implement TokenCounter to count differently - for instance against a provider's own token-counting endpoint, which is the only way to have images counted exactly.
Added the experimental ToolResultPruningCompactor. It reduces Agent context usage by replacing older, large tool results with short placeholders while preserving tool-call/result structure. Results from a configurable number of recent tool-calling Agent steps remain intact, including parallel results from those steps.
from haystack.hooks.compaction import CompactionHook, ToolResultPruningCompactor
compaction_hook = CompactionHook(
compactor=ToolResultPruningCompactor(
min_keep_steps=2,
min_tokens=200,
),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)Add an Agent.clone() method that returns a new Agent with the same configuration, optionally replacing some init parameters: variant = agent.clone(system_prompt="Answer in German.").
Added AgentTool, a Tool that wraps a Haystack Agent, allowing it to be used as a tool by another Agent. It is a building block for multi-agent systems: an Agent specialized in one task becomes a tool that another Agent can delegate to. The calling Agent only sees the final reply, so all the steps the wrapped Agent takes stay out of its context. Sensible defaults make this work out of the box: the task is delegated as a single user message and comes back as text.
Example:
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.tools import AgentTool, ComponentTool
from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
researcher = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-mini"),
system_prompt="You are a research specialist. Investigate the task and report your findings.",
tools=[
ComponentTool(
component=SerperDevWebSearch(
top_k=3,
),
name="web_search",
description="Search the web for current information on any topic",
),
],
)
research = AgentTool(
agent=researcher,
name="research",
description="Research a question on the web and report the findings",
)
coordinator = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4"),
tools=[research],
system_prompt="You coordinate specialists. Delegate research questions, then answer the user.",
)
result = coordinator.run([ChatMessage.from_user("What are the latest developments in the Haystack framework?")])
print(result["last_message"].text)Haystack components that use a document store now provide close and close_async methods for releasing resources. These methods are available on: AutoMergingRetriever, CacheChecker, DocumentWriter, FilterRetriever, and SentenceWindowRetriever. If the underlying Document Store does not implement the corresponding method, calling close or close_async has no effect.
Add a content-free haystack.agent.hook tracing span for every Agent hook invocation. Each span identifies the hook point, hook name, and hook type, allowing hook latency and failures to be attributed without tracing the potentially large Agent State. CompactionHook also adds its configured compaction strategy, estimated context size, whether compaction was triggered, its token target, and whether the compactor returned a replacement.
DOCXLinkFormat to a reusable LinkFormat Enum in haystack/components/converters/utils.py. DOCXLinkFormat is now an alias for backward compatibility.Agent now tracks an approximate current context-window size in its internal State under context_tokens, refreshed after every LLM call with that reply's prompt-plus-completion tokens (normalized across the prompt_tokens/completion_tokens and input_tokens/output_tokens key conventions). Unlike token_usage, which accumulates across the whole run, context_tokens is replaced each call. Hooks can read it via state.get("context_tokens") — for example, a before_llm hook that triggers context compaction once the value crosses a threshold. It is a best-effort snapshot: it is 0 when the generator does not report usage, and does not count messages appended after the latest call until the next call refreshes it.before_run hooks can now read state.data["tools"]. The key was previously written only once the first step had started, so a before_run hook hit a KeyError. It holds a snapshot of the tools available at that point, refreshed before every LLM call, so with a dynamic toolset such as SearchableToolset a before_run hook sees only the tools discovered so far.strict_datetime_comparison keyword argument to document_matches_filter, InMemoryDocumentStore, and MetadataRouter. When enabled, timezone-naive and timezone-aware datetimes never match each other. By default, mixed-awareness datetimes continue to be reconciled by copying the timezone from the aware value to the naive one, and this behavior is now consistent across equality, membership, and ordering operators.filters parameter to InMemoryDocumentStore.get_metadata_field_unique_values (sync and async), allowing the set of documents considered when computing unique metadata field values to be restricted.InMemoryDocumentStore.get_metadata_field_unique_values and its async counterpart now support pagination via from_ and size parameters, matching the behavior of other Document Stores (e.g. Chroma).MockChatGenerator's response_fn can now be tool-aware. If the callable accepts a second positional argument, it also receives the tools passed to run/run_async (a ToolsType or None), so a dynamic mock can build tool calls whose arguments follow the tool's parameter schema or route between the available tools. Existing single-argument response_fn callables are unaffected and keep receiving only the messages.State.to_dict now accepts a skip_keys parameter to exclude specific keys from the output.ConfirmationStrategy run to ConfirmationHook. Each haystack.agent.hook.human_in_the_loop.strategy span identifies the tool call it confirms and records the strategy type and the applied confirm, modify, or reject decision. When content tracing is enabled, spans also carry the arguments the strategy was run with and the ToolExecutionDecision it returned under haystack.agent.hook.human_in_the_loop.strategy.input and haystack.agent.hook.human_in_the_loop.strategy.output; chat messages, the confirmation strategy context, and the Agent State are not recorded by the hook.LLMEvaluator, LLMRanker, QueryExpander, LLMMetadataExtractor, LLMDocumentContentExtractor and LLMMessagesRouter now wrap their internal ChatGenerator calls in a haystack.chat_generator.run tracing span. These components do not return ChatMessage objects, so the LLM token usage carried in reply.meta["usage"] was previously lost to tracers. The new span exposes the generator's replies via the haystack.component.output tag, so token usage is now visible in traces (requires content tracing to be enabled). When the generator runs across threads, the span is nested under the component's span.+ operator (toolset_a + toolset_b) and passing a Toolset to add() (toolset_a.add(toolset_b)). Pass Toolsets as a list wherever tools are accepted instead: Agent(tools=[toolset_a, toolset_b]).Pipeline.load / Pipeline.loads / Pipeline.from_dict, without unsafe=True). A malicious pipeline could either (a) set unsafe: true on an OutputAdapter or ConditionalRouter to disable the Jinja sandbox entirely, or (b) register the thread_safe_import import primitive as a Jinja custom_filters entry to import os and execute arbitrary commands — bypassing the deserialization allowlist and Jinja sandbox. The fix denies import primitives during callable deserialization, refuses to honor a component's unsafe flag while loading in safe mode, and hardens the Jinja sandbox (OutputAdapter, ConditionalRouter, PromptBuilder, ChatPromptBuilder) to block attribute access on module objects and calls into dangerous modules.Pipeline.loads / Pipeline.load / Pipeline.from_dict, which accept unsafe=True) and the execute primitives (Pipeline.run / run_async / run_async_generator / stream) were still resolvable from the allowlisted haystack namespace. Bound as a custom_filters entry on an OutputAdapter or ConditionalRouter (which bypass the Jinja sandbox), Pipeline.loads(..., unsafe=True) let a pipeline loaded in default safe mode load a nested pipeline whose own filters (allow_deserialization_module, deserialize_callable) bind under the nested unsafe context, disarming the process-wide allowlist with "*" and invoking os.system. All of these entry points are now marked as deserializer-internal, so they can never be produced by deserializing untrusted data. unsafe=True still bypasses the check by design; there are no public API changes.Pipeline.load / Pipeline.loads / Pipeline.from_dict, without unsafe=True). Because the deserialization allowlist admits the whole haystack namespace, the deserializer's own allowlist-administration function (allow_deserialization_module) and its resolution helpers (deserialize_callable, deserialize_type, import_class_by_name) were themselves resolvable from serialized data. A malicious pipeline could register allow_deserialization_module as a Jinja custom_filters entry (on an OutputAdapter or ConditionalRouter), call it with "*" to disarm the allowlist process-wide, and then use the equally-resolvable deserialize_callable to resolve and invoke os.system. Loading alone was enough to trigger this: a Jinja filter called with constant arguments runs while the component is being constructed, so the pipeline never had to be run. The same attribute walk could also reach the deserializer's mutable control-plane state directly — for example a filter bound to _extra_allowed_modules.append — to widen the allowlist persistently and stage a later attack. Relatedly, the handle resolver walked attribute names freely, so a handle could descend into object internals such as <function>.__globals__ (a live module namespace, and via it __builtins__ and eval/exec) or <type>.__subclasses__ — classic sandbox-escape gadgets that stay inside an allowlisted module. The fix refuses to deserialize the deserialization control plane as a whole: the allowlist administration and resolution helpers (marked at definition time), everything defined in haystack.core.serialization_security, and any bound method of the mutable allowlist/context state. It also refuses to traverse into dunder and frame/code attributes while resolving a handle. This applies to both the callable- and class-resolution paths, and is bypassed only when the pipeline is loaded with unsafe=True.FileSystemToolResultStore.read() so it only reads references that resolve within the configured store root. This closes a boundary gap where callers could previously pass an arbitrary filesystem path to read() instead of a store-scoped reference returned by write().Fixed the serialization of PDFMinerToDocument. The component did not define to_dict, so the default serialization fell back to reading the init parameters from same-named attributes. Since the layout parameters are stored in self.layout_params, they were silently serialized with their default values, for example a component created with char_margin=0.5 was serialized with char_margin=2.0. Custom layout parameters are now preserved when a pipeline is serialized and loaded again.
Cancel and await sibling retrieval tasks when a concurrent call fails in MultiRetriever, MultiQueryTextRetriever, or MultiQueryEmbeddingRetriever.
Fixed an infinite recursion in CSVDocumentSplitter when nested row and column blocks were split together.
Comparing two Document objects with == now takes all metadata into account. Previously, two documents with different metadata could be considered equal if the metadata contained keys with the same names as document fields (such as id or content).
Document.from_dict(document.to_dict()) now correctly rebuilds any document. Previously, if the metadata contained keys with the same names as document fields (such as id or meta), this either raised an error or silently lost those metadata entries.
Fixed DocumentNDCGEvaluator producing NDCG scores outside the documented 0.0 to 1.0 range when the same document appeared more than once. A document retrieved multiple times used to be counted multiple times, pushing the score above 1.0; a ground truth document listed multiple times used to inflate the ideal gain, keeping a perfect retrieval below 1.0. Each distinct relevant document is now counted once, with the same relevance, in both the actual and ideal gain, so scores stay within range.
Fixed AnswerBuilder returning referenced documents in a scrambled order instead of ascending source-index order. The referenced document indices were collected in a set and iterated directly, so documents were emitted in the set's internal hash-table order (e.g. citations [3] [10] [50] yielded documents ordered 10, 3, 50). This order was deterministic but did not match the intuitive source order. The referenced documents are now returned sorted by their source index.
Fixed serialize_type and deserialize_type to correctly round-trip Callable types that declare an explicit parameter list, such as Callable[[int, str], bool]. Previously the parameter list was dropped during serialization (producing a malformed string like typing.Callable[, bool]) and could no longer be deserialized. This affected components that serialize type annotations, for example ConditionalRouter and OutputAdapter using a Callable output type.
Fix DocumentMAPEvaluator to include missed relevant documents in the average precision denominator and avoid crediting duplicate retrievals of the same document.
Fixed DocumentSplitter producing chunks that were not present in the source document when split_threshold was set together with split_overlap. Merging a below-threshold trailing segment into the previous split re-appended the overlapping units, duplicating text. The overlap is now added only once.
Fixed EmbeddingBasedDocumentSplitter.run_async embedding through the synchronous path while recursively splitting chunks longer than max_length. Only the first pass was async: the recursion called the sync splitting helper, so the embedder's blocking run ran on the event loop for every over-long chunk. The recursion now embeds through run_async as well.
Fixed JSONConverter raising a KeyError instead of logging its intended "Failed to extract text, skipping it" warning when a source is a ByteStream without a file_path in its meta (for example ByteStream.from_string(...), the exact usage shown in the component's own docstring examples). Affected error paths: invalid UTF-8 content, a jq_schema filter that fails to apply, and malformed JSON content.
Fixed LinkContentFetcher rotating the User-Agent on a cursor shared by every URL in the same run()/run_async() call. The URLs are fetched concurrently, so a retry triggered by one of them advanced the user agent for the others, and each completed fetch reset the cursor for the requests still in flight — most retries went out with the un-rotated user agent. Each fetch now walks the user_agents list on its own, so a URL rotates exactly as documented no matter how many other URLs are fetched alongside it.
Fixed MarkdownHeaderSplitter silently dropping a trailing header that has no body text. With keep_headers=True (the default), a header at the end of the document whose only content is whitespace was buffered to prepend to the next chunk, but with no following chunk it was never emitted, so the split documents no longer reconstructed the original text. Such trailing headers are now emitted as a final chunk.
Fixed MarkdownHeaderSplitter collapsing blank lines that follow a header with no body text. With keep_headers=True, such headers were re-joined with a single newline when prepended to the next chunk, so the split documents did not reconstruct the original text. Chunk content is now sliced from the original text and is byte-exact.
Fixed MarkdownHeaderSplitter including surrounding whitespace in the header and parent_headers metadata fields. The header text is now stripped; chunk content still keeps the header line's original whitespace.
Fixed schema-based serialization of lists, tuples and sets holding mixed types. Previously the schema was derived from the first element only, so deserializing such a value raised an AttributeError or silently returned mis-typed data (for example an Agent State field or a pipeline breakpoint input holding [Document(...), "text", 3]). Mixed-type arrays now record one schema per position using the JSON Schema prefixItems keyword and round-trip correctly. Homogeneous arrays keep the exact same output as before, so existing snapshots still load.
Fixed MSGToDocument raising a KeyError when converting a ByteStream source that has no file_path in its meta (for example a bare ByteStream(data=...), rather than a file path or a stream produced via ByteStream.from_file_path). Attachments extracted from such a source no longer include a parent_file_path key, since there is no source file path to record.
Pipeline connections now always convert values in the same way. When a component output is connected to an input that accepts multiple types, Haystack is sometimes able to automatically convert the value, and more than one conversion may be possible. For example, a ChatMessage with text "hello" connected to an input annotated str | list[str] can be delivered either as plain text ("hello") or as a list containing the text (["hello"]). Previously the conversion strategy was chosen non-deterministically, so the same pipeline could return a different value across runs. The conversion strategy is now selected using a fixed priority: first, wrapping a value in a list or unwrapping a single-element list; second, converting between ChatMessage and str; and last, combining both conversions.
Fixed normalize_metadata (used by all file converters) returning the same dictionary object for every source when meta is None or a single dictionary. Each source now receives an independent copy, so mutating one source's metadata downstream no longer leaks into the others.
OpenAIResponsesChatGenerator no longer mutates the parameters schema of the Tool objects passed to it. Previously every run wrote additionalProperties: False into the user's live Tool.parameters, silently altering the tool for any other generator that shared the same Tool instance and making serialization round trips unstable.
OpenAIResponsesChatGenerator no longer raises IndexError when it is warmed up with an empty tools list.
Fixed the parent of the haystack.agent.step.tool spans when an Agent step invokes several tools. The parent span is now resolved once before the tools run, so all tool calls of a step appear as siblings. Previously each span asked the tracer for the currently active span from inside its own concurrent invocation, which made the tool calls after the first one appear nested under a sibling tool call.
Fixed the haystack.pipeline.output_data tracing tag being empty. The tag was set at the start of Pipeline.run/run_async from the still-empty outputs, and since tracing backends coerce a tag value when it is set, the recorded output was always an empty dictionary. It is now set once the run completes so it reflects the final pipeline outputs. The tag is also gated behind content tracing (HAYSTACK_CONTENT_TRACING_ENABLED), consistent with the component-level input/output tags.
Fixed resuming a Pipeline from a pipeline_snapshot that was taken on a component's second or later visit, which failed with PipelineComponentsBlockedError: Cannot run pipeline - all components are blocked. A snapshot stored only the values of the pipeline's inputs and dropped the information about which component had sent each one, so on resume every restored input looked like it came from outside the pipeline, and such an input can only trigger a component on its first visit. Snapshots now record the sender of each input. Snapshots created by earlier versions of Haystack behave as before, so re-create them to resume anywhere in a looping pipeline.
Fixed a resumed Pipeline passing malformed inputs to the component the snapshot was taken on, whenever that component ran more than once after the resume, for example inside a loop. Every visit after the first reused the handling meant only for the paused visit and skipped the regular input consumption, so a variadic component could receive a bare value where it expected a list, raising errors such as TypeError: object of type 'int' has no len() from a BranchJoiner. This affected snapshots taken at any visit count, including the first.
Fixed QueryExpander returning duplicate queries when the chat generator repeats an expansion. Generated queries are now deduplicated while preserving first-seen order, so repeated expansions no longer trigger redundant retrievals or consume the requested expansion budget. Both run and run_async are affected.
RecursiveDocumentSplitter's word-mode fixed-size fallback no longer counts a run of whitespace (e.g. a double space, tab, or page break) as a word, so it no longer produces chunks smaller than split_length. It also no longer emits a whitespace-only chunk when the text ends in whitespace right after a chunk boundary; that trailing whitespace is now attached to the previous chunk instead.
This changes the exact chunk boundaries and chunk count produced by the word-unit fallback for any text containing such whitespace runs. Documents already split and indexed under the old behavior will produce different chunks if re-split after upgrading, so re-index any document store that relies on stable chunk boundaries from this fallback path.
Fixed an issue where PipelineBase.remove_component did not reset auto-variadic socket flags (is_lazy_variadic and wrap_input_in_list) on input sockets when components or connections were removed.
Fixed Pipeline.remove_component leaving dangling references to the removed component on the sockets of its neighboring components. Previously, removing a component reset only its own sockets, so a surviving neighbor kept the removed component's name in its input socket's senders (or output socket's receivers). This corrupted introspection and validation: Pipeline.inputs() hid a now-unconnected mandatory input, and feeding that input directly could raise a spurious "already connected" error. The removed component's name is now stripped from its neighbors' sockets as well.
SentenceWindowRetriever.run and SentenceWindowRetriever.run_async now validate an explicitly provided window_size=0 instead of treating it as unset and falling back to the constructor value.
Fixed the schema-aware serialization helper used for pipeline snapshots and Agent State (_serialize_value_with_schema) so it no longer silently passes unsupported objects through as if they were serialized. Values such as datetime, bytes, complex and arbitrary objects without a to_dict method were previously stored unchanged and mislabeled as strings, which broke JSON storage and round-tripping of snapshots. Unsupported values now raise a SerializationError, and the callers that build snapshots (pipeline breakpoints and State.to_dict) catch it to omit only the offending field while keeping the rest of the payload resumable.
Added support for serializing and deserializing frozenset values in _serialize_value_with_schema. A frozenset now round-trips back to a frozenset instead of being dropped.
Fixed serialize_type/deserialize_type for typing.Literal. Previously a Literal type hint was serialized with its values rendered as bare tokens (e.g. typing.Literal[yes, no]), which failed to deserialize, and values that looked like type names (e.g. Literal["int", "str"]) were silently turned into types on the round-trip. The values are now serialized with repr() and read back with ast.literal_eval, so a Literal type used by a component (such as OutputAdapter or ConditionalRouter) round-trips correctly through pipeline serialization.
Fixed an AttributeError: 'str' object has no attribute 'items' raised by create_tool_from_function, the @tool decorator, and ComponentTool when a tool parameter is named properties. Keys inside a JSON schema properties mapping are property names and are no longer misinterpreted as schema keywords when stripping the auto-generated title keywords.
Fixed create_tool_from_function, the @tool decorator, and ComponentTool corrupting a tool's JSON schema when the string title appears as a name rather than as a schema keyword. Stripping the auto-generated title keywords no longer deletes entries of $defs, definitions, patternProperties, dependentSchemas or dependentRequired (which would leave a $ref dangling or silently drop a validation rule), and no longer edits title keys inside default, const, enum or examples values, which are instance data and part of the tool's contract.
Fixed _ToolsetWrapper.__getitem__ (used when combining Toolsets with +) raising IndexError for negative indices, unlike a plain Toolset. Indexing a combined toolset now behaves consistently with a list of Tools, as documented.
Fixed serialization of types that contain ... (Ellipsis), such as variadic tuples (tuple[int, ...]) and Callable[..., X]. Previously serialize_type rendered the ... as the literal string "Ellipsis", which deserialize_type then rejected as a non-type builtin, so a component using such a type (for example OutputAdapter(output_type=tuple[int, ...])) could be serialized but not deserialized, breaking Pipeline.loads() / Pipeline.load(). These types now round-trip correctly, and pipelines serialized by older versions (which emitted "Ellipsis") can still be loaded.
Fixed ConfirmationHook applying a Human-in-the-Loop decision to the wrong tool call when a custom ConfirmationStrategy returns a decision with a missing or incorrect tool_call_id. Each decision is now bound to the tool call for which its strategy ran, and ID-bearing decisions are no longer matched to a different call by name. Haystack's existing requirement of exactly one decision per tool call is now explicitly enforced. Each matched decision is consumed after use, so a missing, unused, or reused decision raises a ValueError instead of being silently misapplied.
DocumentJoiner and AnswerJoiner now resolve top_k consistently and validate it. Previously, a runtime top_k=0 was treated as "unset" and silently fell back to the instance's top_k, instead of returning an empty list as requested. Both components now:
ValueError at initialization if top_k is not None and is less than or equal to 0.ValueError at runtime if top_k passed to run() is negative.run() is called with top_k=0, regardless of the instance's configured top_k.Fixes MetaFieldRanker silently treating a runtime top_k=0 as unset and falling back to the value configured at initialization. Runtime values that are not greater than zero now raise a ValueError as documented.
Fixed PythonCodeSplitter losing identifying context for oversized functions, methods, or classes. When a unit is too large and falls back to line-based secondary splitting, only the first resulting piece naturally retains the source def/class line; every piece now includes a qualified_name field in meta identifying the function, method, or class it came from.
Fixed RecursiveDocumentSplitter not setting the source_id meta field on the chunks it produces. It wrote only parent_id, while every other splitter in the library (DocumentSplitter, CSVDocumentSplitter, EmbeddingBasedDocumentSplitter, HierarchicalDocumentSplitter, MarkdownHeaderSplitter and PythonCodeSplitter) writes source_id. Components that follow that convention therefore rejected its output: SentenceWindowRetriever reads source_id by default and raises when it is absent, so it failed with "The retrieved documents must have 'source_id' in their metadata." on a pipeline that worked with any other splitter. Chunks now carry source_id as well as parent_id, which keeps its previous value for callers already reading it.
Tool functions defined in a module using from __future__ import annotations are now inspected correctly by Agent. Postponed annotations are stored as strings, so a parameter annotated with State was not recognized and the live State object was not injected into the tool call. The annotations are now resolved before they are inspected.
MarkdownHeaderSplitter and CSVDocumentSplitter now deep-copy the metadata of the document they split, matching DocumentSplitter. Previously they copied it shallowly, so nested values such as a list under meta["tags"] were shared between every chunk and with the input document, and editing one chunk's metadata changed all the others. HierarchicalDocumentSplitter had the same problem on its root node, which kept references into the input document's metadata.
Keep an Agent's execution counter in sync with step_count restored by a before_run hook, so restarted Agents continue from the saved step instead of resetting the count.
@Aarkin7, @anakin87, @anxkhn, @aquib8112, @Aryan-Pardeshi, @atikulmunna, @bharadwaj-pendyala, @bilgeyucel, @bogdankostic, @camgrimsec, @chuenchen309, @davidpavlovschi, @davidsbatista, @DhanushPillay, @DivyaNarahari97, @erikos, @GovindhKishore, @hxaxd, @immuhammadfurqan, @iridescentWen, @jaideeppyne, @julian-risch, @kacperlukawski, @KXHXK, @LHMQ878, @LK-maker-007, @lntutor, @manjunathbhaskar, @mittalpk, @MVS-source, @onatozmenn, @otiscuilei, @pcbeingused333, @rautaditya2606, @sjrl, @sohumt123, @Solaris-star, @TimurRakhmatullin86, @vidigoat, @vinkiYu, @winklemad, @yaodong-shen
Fixed a remote code execution vulnerability that could be triggered by loading an untrusted pipeline in default safe mode ( Pipeline.load / Pipeline.l…
OutputAdapter and ConditionalRouter components containing Jinja custom_filters must now be loaded with Pipeline.load(..., unsafe=True) (or the equivalent Pipeline.loads / Pipeline.from_dict option).Added the HAYSTACK_UNSAFE_DESERIALIZATION environment variable as a process-wide equivalent of loading with unsafe=True. When set to a truthy value (1 or true), every Pipeline.load / Pipeline.loads / Pipeline.from_dict call skips all deserialization safety checks — the module allowlist, the builtin/import-primitive and control-plane denylists, the object-internals traversal guard, and the refusal to honor a component's own unsafe: true flag. This is intended for deployments that only ever load fully trusted pipelines and cannot pass unsafe=True at every call site. A warning is logged the first time it takes effect. Only enable it when every pipeline the process loads is trusted: a single untrusted pipeline then leads to arbitrary code execution.
The switch is not limited to pipeline loading: it disables the same checks for every deserialization path in the process, including ones that take no unsafe argument of their own — Tool.from_dict, State.from_dict (agent snapshot resume), and the ConditionalRouter and OutputAdapter Jinja sandbox flags. A deployment that loads trusted pipelines at startup but accepts serialized tools or agent state at request time is therefore exposed on the request path as well, not only at load time.
The variable is read once, on the first deserialization in the process, and the result is then frozen for the process lifetime: writes to it afterwards are ignored, in either direction. Set it before the first pipeline is loaded. Freezing keeps the safety mode of a process from changing under a caller's feet and, because the first read happens before any deserialized data can run, stops a hostile pipeline from switching the checks off while it is being loaded.
exit_reason is now a reserved state key on Agent. If you defined a custom state_schema key named exit_reason, rename it: the Agent now raises a ValueError at initialization when a reserved key is redefined.
Agent.state_schema now contains the user-provided state schema, exactly as passed to __init__. Previously it contained the resolved schema, which also included messages and the keys the Agent manages internally (step_count, token_usage, exit_reason, ...). If you were reading agent.state_schema to inspect the effective runtime schema, use the new public attribute agent.resolved_state_schema instead.
DocumentMAPEvaluator scores can change because average precision now uses all unique, valid ground-truth comparison values as its denominator and credits each value at most once. Re-baseline evaluations that relied on the previous scores.
PipelineSnapshot.pipeline_state.inputs changed shape. It used to store one flattened value per socket, {component: {socket: value}}. It now stores the pipeline's internal inputs, keeping the component that sent each one in the order it arrived: {component: {socket: [{"sender": ..., "value": ...}]}}. PipelineState gained an inputs_format field recording which of the two shapes a snapshot uses. The same applies to BreakpointException.inputs, which returns that field.
You are affected if you read pipeline_state.inputs (or BreakpointException.inputs) directly, for example to display or post-process a snapshot. Resuming a pipeline with Pipeline.run(pipeline_snapshot=...) is not affected, and neither is code that only passes snapshots around or persists them.
To adapt, read the input from the list and take its value:
inputs = snapshot.pipeline_state.inputs["serialized_data"]
# before
value = inputs["my_component"]["my_socket"]
# now
value = inputs["my_component"]["my_socket"][0]["value"]A socket that received inputs from several senders has one list item per input, each recording the sender that produced it.
Snapshots written by earlier versions of Haystack have inputs_format set to None and keep the flattened shape, so branch on that field if you need to handle both.
Loading a serialized OutputAdapter or ConditionalRouter whose unsafe init parameter is set to true now raises DeserializationError unless the pipeline is loaded in unsafe mode. Pipelines that legitimately rely on an unsafe OutputAdapter/ConditionalRouter embedded in serialized data must now load with Pipeline.load(..., unsafe=True) (or Pipeline.loads / Pipeline.from_dict with unsafe=True).
Passing window_size=0 to SentenceWindowRetriever.run or SentenceWindowRetriever.run_async now raises a ValueError instead of silently using the window_size set in the constructor. You are affected if you pass window_size=0 at runtime, either directly or from an upstream component in a pipeline. If you were relying on 0 to mean "use the value from the constructor", omit the argument (or pass None) instead:
retriever = SentenceWindowRetriever(document_store=document_store, window_size=3)
# Before: silently used window_size=3
retriever.run(retrieved_documents=docs, window_size=0)
# After: omit the argument to use the constructor value
retriever.run(retrieved_documents=docs)InMemoryDocumentStore.get_metadata_field_unique_values (and its async counterpart)'s search_term parameter now matches against the metadata field's own value (case-insensitive substring) instead of the document's content. Callers relying on the previous content-matching behavior will need to filter documents by content themselves before calling this method.
The Agent now warms up its hooks before every run, not only the first one, as it already does for Tools and Toolsets. If your hook has a warm_up() that does expensive setup (opening a client, loading a model), make it return early once done, for example if self._client is not None: return.
Haystack can call warm_up() on Tools and Toolsets more than once, for example before every run. Previously Toolset absorbed repeated calls with an internal _is_warmed_up flag; that flag is gone and every call now reaches your warm_up(). If your custom Tool or Toolset does expensive work there (connecting to a server, loading a model), or relied on the _is_warmed_up attribute, guard with your own state and return early, for example if self._client is not None: return.
Added a link_format parameter to both PyPDFToDocument and PDFMinerToDocument components, matching the existing functionality in DOCXToDocument. Links are parsed from PDF annotations and appended at the bottom of the page content.
Added experimental context compaction for the Agent. CompactionHook runs before LLM calls and shortens the conversation when it reaches a configured fraction of the model's context window.
The first built-in strategy, SlidingWindowCompactor, preserves leading system messages, the latest user task, and as much complete recent conversation as the target allows. It removes complete historical turns first, and only when removing every historical turn is insufficient does it remove individual Agent steps from the current task. It replaces removed history with a short omission note, left where the removed messages used to sit: directly after the leading system messages when only historical turns were removed, and directly after the latest user message when the current task's own steps were removed. Only one note is ever present, because a later compaction folds an earlier one into its replacement.
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
hook = CompactionHook(
compactor=SlidingWindowCompactor(),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
tools=[web_search],
hooks={"before_llm": [hook]},
)The hook uses provider-reported context usage when available and locally estimates the request otherwise, including tool schemas. Leave headroom above compact_at for the next reply and its tool results.
SlidingWindowCompactor treats an assistant message and its following tool results as one step, so a tool call is never separated from its results. Historical turns are likewise kept or removed in full, so an assistant reply is not retained without the user message it answers. It can also land above the requested target rather than under it, because leading system messages and the current task are never removed and min_keep_steps holds on to the newest Agent steps whatever their size, so a long system prompt or one large tool result can leave the conversation well over the target. Compaction is lossy: removed messages cannot be recovered or summarized by this strategy. Implement the Compactor protocol to provide a custom strategy.
CompactionHook and SlidingWindowCompactor emit an ExperimentalWarning and may change without a deprecation cycle.
Agent now returns an exit_reason output reporting why the run stopped, making it easier to route the Agent's output downstream (for example with a ConditionalRouter). It is one of: "text" (the model returned a reply with no tool calls), the name of the tool that satisfied a tool exit condition (in which case last_message is that tool's result), or "max_agent_steps" (the Agent hit max_agent_steps before meeting an exit condition). The reason is also available to hooks via state.get("exit_reason"), so an after_run hook can, for instance, append a fallback answer when the step budget is exhausted.
Add OpenAITokenCounter, which uses OpenAI's input token counting API to return model-specific counts for Haystack ChatMessage objects and optional tool schemas. Unlike local estimates, it supports OpenAI's exact accounting for request formatting, images, files, and tools.
Here is an example:
from haystack.dataclasses import ChatMessage
from haystack.token_counters import OpenAITokenCounter
counter = OpenAITokenCounter("gpt-5-mini")
count = counter.count([ChatMessage.from_user("Hello!")])Added haystack.token_counters: a TokenCounter protocol for estimating how many tokens a list of ChatMessage objects occupies, with two implementations.
Providers report token usage only after a call, and only for the call as a whole, so anything that needs a size beforehand - deciding whether a conversation still fits a model's context window, or how much of it to drop - has to estimate one.
from haystack.dataclasses import ChatMessage
from haystack.token_counters import ApproximateTokenCounter, TiktokenCounter
messages = [ChatMessage.from_user("Hello, how are you?")]
# No dependencies: estimates from text length.
ApproximateTokenCounter(chars_per_token=4.0).count(messages)
# Closer for OpenAI models; needs: pip install tiktoken
TiktokenCounter(encoding="o200k_base").count(messages)ApproximateTokenCounter needs nothing installed and estimates from text length at a configurable chars_per_token. TiktokenCounter counts with OpenAI's byte-pair encoder, which is closer for OpenAI models but requires tiktoken and drifts on other providers; it raises at construction when the dependency is missing, and loads its encoding on first use.
Neither can measure an image or a file, since a tokenizer only sees text and providers derive an image's cost from its dimensions. Both charge a flat tokens_per_image and tokens_per_file instead, counting images a tool returned inside its result as well as those a message carries directly. Raise those values if you send large images or long documents.
Tool schemas are sent alongside the messages and consume tokens too, so count takes an optional tools argument to have them included:
counter.count(messages, tools=[my_tool])Implement TokenCounter to count differently - for instance against a provider's own token-counting endpoint, which is the only way to have images counted exactly.
Added the experimental ToolResultPruningCompactor. It reduces Agent context usage by replacing older, large tool results with short placeholders while preserving tool-call/result structure. Results from a configurable number of recent tool-calling Agent steps remain intact, including parallel results from those steps.
from haystack.hooks.compaction import CompactionHook, ToolResultPruningCompactor
compaction_hook = CompactionHook(
compactor=ToolResultPruningCompactor(
min_keep_steps=2,
min_tokens=200,
),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)Add an Agent.clone() method that returns a new Agent with the same configuration, optionally replacing some init parameters: variant = agent.clone(system_prompt="Answer in German.").
Added AgentTool, a Tool that wraps a Haystack Agent, allowing it to be used as a tool by another Agent. It is a building block for multi-agent systems: an Agent specialized in one task becomes a tool that another Agent can delegate to. The calling Agent only sees the final reply, so all the steps the wrapped Agent takes stay out of its context. Sensible defaults make this work out of the box: the task is delegated as a single user message and comes back as text.
Example:
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.tools import AgentTool, ComponentTool
from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
researcher = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-mini"),
system_prompt="You are a research specialist. Investigate the task and report your findings.",
tools=[
ComponentTool(
component=SerperDevWebSearch(
top_k=3,
),
name="web_search",
description="Search the web for current information on any topic",
),
],
)
research = AgentTool(
agent=researcher,
name="research",
description="Research a question on the web and report the findings",
)
coordinator = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4"),
tools=[research],
system_prompt="You coordinate specialists. Delegate research questions, then answer the user.",
)
result = coordinator.run([ChatMessage.from_user("What are the latest developments in the Haystack framework?")])
print(result["last_message"].text)Haystack components that use a document store now provide close and close_async methods for releasing resources. These methods are available on: AutoMergingRetriever, CacheChecker, DocumentWriter, FilterRetriever, and SentenceWindowRetriever. If the underlying Document Store does not implement the corresponding method, calling close or close_async has no effect.
Add a content-free haystack.agent.hook tracing span for every Agent hook invocation. Each span identifies the hook point, hook name, and hook type, allowing hook latency and failures to be attributed without tracing the potentially large Agent State. CompactionHook also adds its configured compaction strategy, estimated context size, whether compaction was triggered, its token target, and whether the compactor returned a replacement.
DOCXLinkFormat to a reusable LinkFormat Enum in haystack/components/converters/utils.py. DOCXLinkFormat is now an alias for backward compatibility.Agent now tracks an approximate current context-window size in its internal State under context_tokens, refreshed after every LLM call with that reply's prompt-plus-completion tokens (normalized across the prompt_tokens/completion_tokens and input_tokens/output_tokens key conventions). Unlike token_usage, which accumulates across the whole run, context_tokens is replaced each call. Hooks can read it via state.get("context_tokens") — for example, a before_llm hook that triggers context compaction once the value crosses a threshold. It is a best-effort snapshot: it is 0 when the generator does not report usage, and does not count messages appended after the latest call until the next call refreshes it.before_run hooks can now read state.data["tools"]. The key was previously written only once the first step had started, so a before_run hook hit a KeyError. It holds a snapshot of the tools available at that point, refreshed before every LLM call, so with a dynamic toolset such as SearchableToolset a before_run hook sees only the tools discovered so far.strict_datetime_comparison keyword argument to document_matches_filter, InMemoryDocumentStore, and MetadataRouter. When enabled, timezone-naive and timezone-aware datetimes never match each other. By default, mixed-awareness datetimes continue to be reconciled by copying the timezone from the aware value to the naive one, and this behavior is now consistent across equality, membership, and ordering operators.filters parameter to InMemoryDocumentStore.get_metadata_field_unique_values (sync and async), allowing the set of documents considered when computing unique metadata field values to be restricted.InMemoryDocumentStore.get_metadata_field_unique_values and its async counterpart now support pagination via from_ and size parameters, matching the behavior of other Document Stores (e.g. Chroma).MockChatGenerator's response_fn can now be tool-aware. If the callable accepts a second positional argument, it also receives the tools passed to run/run_async (a ToolsType or None), so a dynamic mock can build tool calls whose arguments follow the tool's parameter schema or route between the available tools. Existing single-argument response_fn callables are unaffected and keep receiving only the messages.State.to_dict now accepts a skip_keys parameter to exclude specific keys from the output.ConfirmationStrategy run to ConfirmationHook. Each haystack.agent.hook.human_in_the_loop.strategy span identifies the tool call it confirms and records the strategy type and the applied confirm, modify, or reject decision. When content tracing is enabled, spans also carry the arguments the strategy was run with and the ToolExecutionDecision it returned under haystack.agent.hook.human_in_the_loop.strategy.input and haystack.agent.hook.human_in_the_loop.strategy.output; chat messages, the confirmation strategy context, and the Agent State are not recorded by the hook.LLMEvaluator, LLMRanker, QueryExpander, LLMMetadataExtractor, LLMDocumentContentExtractor and LLMMessagesRouter now wrap their internal ChatGenerator calls in a haystack.chat_generator.run tracing span. These components do not return ChatMessage objects, so the LLM token usage carried in reply.meta["usage"] was previously lost to tracers. The new span exposes the generator's replies via the haystack.component.output tag, so token usage is now visible in traces (requires content tracing to be enabled). When the generator runs across threads, the span is nested under the component's span.+ operator (toolset_a + toolset_b) and passing a Toolset to add() (toolset_a.add(toolset_b)). Pass Toolsets as a list wherever tools are accepted instead: Agent(tools=[toolset_a, toolset_b]).Pipeline.load / Pipeline.loads / Pipeline.from_dict, without unsafe=True). A malicious pipeline could either (a) set unsafe: true on an OutputAdapter or ConditionalRouter to disable the Jinja sandbox entirely, or (b) register the thread_safe_import import primitive as a Jinja custom_filters entry to import os and execute arbitrary commands — bypassing the deserialization allowlist and Jinja sandbox. The fix denies import primitives during callable deserialization, refuses to honor a component's unsafe flag while loading in safe mode, and hardens the Jinja sandbox (OutputAdapter, ConditionalRouter, PromptBuilder, ChatPromptBuilder) to block attribute access on module objects and calls into dangerous modules.Pipeline.loads / Pipeline.load / Pipeline.from_dict, which accept unsafe=True) and the execute primitives (Pipeline.run / run_async / run_async_generator / stream) were still resolvable from the allowlisted haystack namespace. Bound as a custom_filters entry on an OutputAdapter or ConditionalRouter (which bypass the Jinja sandbox), Pipeline.loads(..., unsafe=True) let a pipeline loaded in default safe mode load a nested pipeline whose own filters (allow_deserialization_module, deserialize_callable) bind under the nested unsafe context, disarming the process-wide allowlist with "*" and invoking os.system. All of these entry points are now marked as deserializer-internal, so they can never be produced by deserializing untrusted data. unsafe=True still bypasses the check by design; there are no public API changes.Pipeline.load / Pipeline.loads / Pipeline.from_dict, without unsafe=True). Because the deserialization allowlist admits the whole haystack namespace, the deserializer's own allowlist-administration function (allow_deserialization_module) and its resolution helpers (deserialize_callable, deserialize_type, import_class_by_name) were themselves resolvable from serialized data. A malicious pipeline could register allow_deserialization_module as a Jinja custom_filters entry (on an OutputAdapter or ConditionalRouter), call it with "*" to disarm the allowlist process-wide, and then use the equally-resolvable deserialize_callable to resolve and invoke os.system. Loading alone was enough to trigger this: a Jinja filter called with constant arguments runs while the component is being constructed, so the pipeline never had to be run. The same attribute walk could also reach the deserializer's mutable control-plane state directly — for example a filter bound to _extra_allowed_modules.append — to widen the allowlist persistently and stage a later attack. Relatedly, the handle resolver walked attribute names freely, so a handle could descend into object internals such as <function>.__globals__ (a live module namespace, and via it __builtins__ and eval/exec) or <type>.__subclasses__ — classic sandbox-escape gadgets that stay inside an allowlisted module. The fix refuses to deserialize the deserialization control plane as a whole: the allowlist administration and resolution helpers (marked at definition time), everything defined in haystack.core.serialization_security, and any bound method of the mutable allowlist/context state. It also refuses to traverse into dunder and frame/code attributes while resolving a handle. This applies to both the callable- and class-resolution paths, and is bypassed only when the pipeline is loaded with unsafe=True.FileSystemToolResultStore.read() so it only reads references that resolve within the configured store root. This closes a boundary gap where callers could previously pass an arbitrary filesystem path to read() instead of a store-scoped reference returned by write().Fixed the serialization of PDFMinerToDocument. The component did not define to_dict, so the default serialization fell back to reading the init parameters from same-named attributes. Since the layout parameters are stored in self.layout_params, they were silently serialized with their default values, for example a component created with char_margin=0.5 was serialized with char_margin=2.0. Custom layout parameters are now preserved when a pipeline is serialized and loaded again.
Cancel and await sibling retrieval tasks when a concurrent call fails in MultiRetriever, MultiQueryTextRetriever, or MultiQueryEmbeddingRetriever.
Fixed an infinite recursion in CSVDocumentSplitter when nested row and column blocks were split together.
Comparing two Document objects with == now takes all metadata into account. Previously, two documents with different metadata could be considered equal if the metadata contained keys with the same names as document fields (such as id or content).
Document.from_dict(document.to_dict()) now correctly rebuilds any document. Previously, if the metadata contained keys with the same names as document fields (such as id or meta), this either raised an error or silently lost those metadata entries.
Fixed DocumentNDCGEvaluator producing NDCG scores outside the documented 0.0 to 1.0 range when the same document appeared more than once. A document retrieved multiple times used to be counted multiple times, pushing the score above 1.0; a ground truth document listed multiple times used to inflate the ideal gain, keeping a perfect retrieval below 1.0. Each distinct relevant document is now counted once, with the same relevance, in both the actual and ideal gain, so scores stay within range.
Fixed AnswerBuilder returning referenced documents in a scrambled order instead of ascending source-index order. The referenced document indices were collected in a set and iterated directly, so documents were emitted in the set's internal hash-table order (e.g. citations [3] [10] [50] yielded documents ordered 10, 3, 50). This order was deterministic but did not match the intuitive source order. The referenced documents are now returned sorted by their source index.
Fixed serialize_type and deserialize_type to correctly round-trip Callable types that declare an explicit parameter list, such as Callable[[int, str], bool]. Previously the parameter list was dropped during serialization (producing a malformed string like typing.Callable[, bool]) and could no longer be deserialized. This affected components that serialize type annotations, for example ConditionalRouter and OutputAdapter using a Callable output type.
Fix DocumentMAPEvaluator to include missed relevant documents in the average precision denominator and avoid crediting duplicate retrievals of the same document.
Fixed DocumentSplitter producing chunks that were not present in the source document when split_threshold was set together with split_overlap. Merging a below-threshold trailing segment into the previous split re-appended the overlapping units, duplicating text. The overlap is now added only once.
Fixed EmbeddingBasedDocumentSplitter.run_async embedding through the synchronous path while recursively splitting chunks longer than max_length. Only the first pass was async: the recursion called the sync splitting helper, so the embedder's blocking run ran on the event loop for every over-long chunk. The recursion now embeds through run_async as well.
Fixed JSONConverter raising a KeyError instead of logging its intended "Failed to extract text, skipping it" warning when a source is a ByteStream without a file_path in its meta (for example ByteStream.from_string(...), the exact usage shown in the component's own docstring examples). Affected error paths: invalid UTF-8 content, a jq_schema filter that fails to apply, and malformed JSON content.
Fixed LinkContentFetcher rotating the User-Agent on a cursor shared by every URL in the same run()/run_async() call. The URLs are fetched concurrently, so a retry triggered by one of them advanced the user agent for the others, and each completed fetch reset the cursor for the requests still in flight — most retries went out with the un-rotated user agent. Each fetch now walks the user_agents list on its own, so a URL rotates exactly as documented no matter how many other URLs are fetched alongside it.
Fixed MarkdownHeaderSplitter silently dropping a trailing header that has no body text. With keep_headers=True (the default), a header at the end of the document whose only content is whitespace was buffered to prepend to the next chunk, but with no following chunk it was never emitted, so the split documents no longer reconstructed the original text. Such trailing headers are now emitted as a final chunk.
Fixed MarkdownHeaderSplitter collapsing blank lines that follow a header with no body text. With keep_headers=True, such headers were re-joined with a single newline when prepended to the next chunk, so the split documents did not reconstruct the original text. Chunk content is now sliced from the original text and is byte-exact.
Fixed MarkdownHeaderSplitter including surrounding whitespace in the header and parent_headers metadata fields. The header text is now stripped; chunk content still keeps the header line's original whitespace.
Fixed schema-based serialization of lists, tuples and sets holding mixed types. Previously the schema was derived from the first element only, so deserializing such a value raised an AttributeError or silently returned mis-typed data (for example an Agent State field or a pipeline breakpoint input holding [Document(...), "text", 3]). Mixed-type arrays now record one schema per position using the JSON Schema prefixItems keyword and round-trip correctly. Homogeneous arrays keep the exact same output as before, so existing snapshots still load.
Fixed MSGToDocument raising a KeyError when converting a ByteStream source that has no file_path in its meta (for example a bare ByteStream(data=...), rather than a file path or a stream produced via ByteStream.from_file_path). Attachments extracted from such a source no longer include a parent_file_path key, since there is no source file path to record.
Pipeline connections now always convert values in the same way. When a component output is connected to an input that accepts multiple types, Haystack is sometimes able to automatically convert the value, and more than one conversion may be possible. For example, a ChatMessage with text "hello" connected to an input annotated str | list[str] can be delivered either as plain text ("hello") or as a list containing the text (["hello"]). Previously the conversion strategy was chosen non-deterministically, so the same pipeline could return a different value across runs. The conversion strategy is now selected using a fixed priority: first, wrapping a value in a list or unwrapping a single-element list; second, converting between ChatMessage and str; and last, combining both conversions.
Fixed normalize_metadata (used by all file converters) returning the same dictionary object for every source when meta is None or a single dictionary. Each source now receives an independent copy, so mutating one source's metadata downstream no longer leaks into the others.
OpenAIResponsesChatGenerator no longer mutates the parameters schema of the Tool objects passed to it. Previously every run wrote additionalProperties: False into the user's live Tool.parameters, silently altering the tool for any other generator that shared the same Tool instance and making serialization round trips unstable.
OpenAIResponsesChatGenerator no longer raises IndexError when it is warmed up with an empty tools list.
Fixed the parent of the haystack.agent.step.tool spans when an Agent step invokes several tools. The parent span is now resolved once before the tools run, so all tool calls of a step appear as siblings. Previously each span asked the tracer for the currently active span from inside its own concurrent invocation, which made the tool calls after the first one appear nested under a sibling tool call.
Fixed the haystack.pipeline.output_data tracing tag being empty. The tag was set at the start of Pipeline.run/run_async from the still-empty outputs, and since tracing backends coerce a tag value when it is set, the recorded output was always an empty dictionary. It is now set once the run completes so it reflects the final pipeline outputs. The tag is also gated behind content tracing (HAYSTACK_CONTENT_TRACING_ENABLED), consistent with the component-level input/output tags.
Fixed resuming a Pipeline from a pipeline_snapshot that was taken on a component's second or later visit, which failed with PipelineComponentsBlockedError: Cannot run pipeline - all components are blocked. A snapshot stored only the values of the pipeline's inputs and dropped the information about which component had sent each one, so on resume every restored input looked like it came from outside the pipeline, and such an input can only trigger a component on its first visit. Snapshots now record the sender of each input. Snapshots created by earlier versions of Haystack behave as before, so re-create them to resume anywhere in a looping pipeline.
Fixed a resumed Pipeline passing malformed inputs to the component the snapshot was taken on, whenever that component ran more than once after the resume, for example inside a loop. Every visit after the first reused the handling meant only for the paused visit and skipped the regular input consumption, so a variadic component could receive a bare value where it expected a list, raising errors such as TypeError: object of type 'int' has no len() from a BranchJoiner. This affected snapshots taken at any visit count, including the first.
Fixed QueryExpander returning duplicate queries when the chat generator repeats an expansion. Generated queries are now deduplicated while preserving first-seen order, so repeated expansions no longer trigger redundant retrievals or consume the requested expansion budget. Both run and run_async are affected.
RecursiveDocumentSplitter's word-mode fixed-size fallback no longer counts a run of whitespace (e.g. a double space, tab, or page break) as a word, so it no longer produces chunks smaller than split_length. It also no longer emits a whitespace-only chunk when the text ends in whitespace right after a chunk boundary; that trailing whitespace is now attached to the previous chunk instead.
This changes the exact chunk boundaries and chunk count produced by the word-unit fallback for any text containing such whitespace runs. Documents already split and indexed under the old behavior will produce different chunks if re-split after upgrading, so re-index any document store that relies on stable chunk boundaries from this fallback path.
Fixed an issue where PipelineBase.remove_component did not reset auto-variadic socket flags (is_lazy_variadic and wrap_input_in_list) on input sockets when components or connections were removed.
Fixed Pipeline.remove_component leaving dangling references to the removed component on the sockets of its neighboring components. Previously, removing a component reset only its own sockets, so a surviving neighbor kept the removed component's name in its input socket's senders (or output socket's receivers). This corrupted introspection and validation: Pipeline.inputs() hid a now-unconnected mandatory input, and feeding that input directly could raise a spurious "already connected" error. The removed component's name is now stripped from its neighbors' sockets as well.
SentenceWindowRetriever.run and SentenceWindowRetriever.run_async now validate an explicitly provided window_size=0 instead of treating it as unset and falling back to the constructor value.
Fixed the schema-aware serialization helper used for pipeline snapshots and Agent State (_serialize_value_with_schema) so it no longer silently passes unsupported objects through as if they were serialized. Values such as datetime, bytes, complex and arbitrary objects without a to_dict method were previously stored unchanged and mislabeled as strings, which broke JSON storage and round-tripping of snapshots. Unsupported values now raise a SerializationError, and the callers that build snapshots (pipeline breakpoints and State.to_dict) catch it to omit only the offending field while keeping the rest of the payload resumable.
Added support for serializing and deserializing frozenset values in _serialize_value_with_schema. A frozenset now round-trips back to a frozenset instead of being dropped.
Fixed serialize_type/deserialize_type for typing.Literal. Previously a Literal type hint was serialized with its values rendered as bare tokens (e.g. typing.Literal[yes, no]), which failed to deserialize, and values that looked like type names (e.g. Literal["int", "str"]) were silently turned into types on the round-trip. The values are now serialized with repr() and read back with ast.literal_eval, so a Literal type used by a component (such as OutputAdapter or ConditionalRouter) round-trips correctly through pipeline serialization.
Fixed an AttributeError: 'str' object has no attribute 'items' raised by create_tool_from_function, the @tool decorator, and ComponentTool when a tool parameter is named properties. Keys inside a JSON schema properties mapping are property names and are no longer misinterpreted as schema keywords when stripping the auto-generated title keywords.
Fixed create_tool_from_function, the @tool decorator, and ComponentTool corrupting a tool's JSON schema when the string title appears as a name rather than as a schema keyword. Stripping the auto-generated title keywords no longer deletes entries of $defs, definitions, patternProperties, dependentSchemas or dependentRequired (which would leave a $ref dangling or silently drop a validation rule), and no longer edits title keys inside default, const, enum or examples values, which are instance data and part of the tool's contract.
Fixed _ToolsetWrapper.__getitem__ (used when combining Toolsets with +) raising IndexError for negative indices, unlike a plain Toolset. Indexing a combined toolset now behaves consistently with a list of Tools, as documented.
Fixed serialization of types that contain ... (Ellipsis), such as variadic tuples (tuple[int, ...]) and Callable[..., X]. Previously serialize_type rendered the ... as the literal string "Ellipsis", which deserialize_type then rejected as a non-type builtin, so a component using such a type (for example OutputAdapter(output_type=tuple[int, ...])) could be serialized but not deserialized, breaking Pipeline.loads() / Pipeline.load(). These types now round-trip correctly, and pipelines serialized by older versions (which emitted "Ellipsis") can still be loaded.
Fixed ConfirmationHook applying a Human-in-the-Loop decision to the wrong tool call when a custom ConfirmationStrategy returns a decision with a missing or incorrect tool_call_id. Each decision is now bound to the tool call for which its strategy ran, and ID-bearing decisions are no longer matched to a different call by name. Haystack's existing requirement of exactly one decision per tool call is now explicitly enforced. Each matched decision is consumed after use, so a missing, unused, or reused decision raises a ValueError instead of being silently misapplied.
DocumentJoiner and AnswerJoiner now resolve top_k consistently and validate it. Previously, a runtime top_k=0 was treated as "unset" and silently fell back to the instance's top_k, instead of returning an empty list as requested. Both components now:
ValueError at initialization if top_k is not None and is less than or equal to 0.ValueError at runtime if top_k passed to run() is negative.run() is called with top_k=0, regardless of the instance's configured top_k.Fixes MetaFieldRanker silently treating a runtime top_k=0 as unset and falling back to the value configured at initialization. Runtime values that are not greater than zero now raise a ValueError as documented.
Fixed PythonCodeSplitter losing identifying context for oversized functions, methods, or classes. When a unit is too large and falls back to line-based secondary splitting, only the first resulting piece naturally retains the source def/class line; every piece now includes a qualified_name field in meta identifying the function, method, or class it came from.
Fixed RecursiveDocumentSplitter not setting the source_id meta field on the chunks it produces. It wrote only parent_id, while every other splitter in the library (DocumentSplitter, CSVDocumentSplitter, EmbeddingBasedDocumentSplitter, HierarchicalDocumentSplitter, MarkdownHeaderSplitter and PythonCodeSplitter) writes source_id. Components that follow that convention therefore rejected its output: SentenceWindowRetriever reads source_id by default and raises when it is absent, so it failed with "The retrieved documents must have 'source_id' in their metadata." on a pipeline that worked with any other splitter. Chunks now carry source_id as well as parent_id, which keeps its previous value for callers already reading it.
Tool functions defined in a module using from __future__ import annotations are now inspected correctly by Agent. Postponed annotations are stored as strings, so a parameter annotated with State was not recognized and the live State object was not injected into the tool call. The annotations are now resolved before they are inspected.
MarkdownHeaderSplitter and CSVDocumentSplitter now deep-copy the metadata of the document they split, matching DocumentSplitter. Previously they copied it shallowly, so nested values such as a list under meta["tags"] were shared between every chunk and with the input document, and editing one chunk's metadata changed all the others. HierarchicalDocumentSplitter had the same problem on its root node, which kept references into the input document's metadata.
Keep an Agent's execution counter in sync with step_count restored by a before_run hook, so restarted Agents continue from the saved step instead of resetting the count.
@Aarkin7, @anakin87, @anxkhn, @aquib8112, @Aryan-Pardeshi, @atikulmunna, @bharadwaj-pendyala, @bilgeyucel, @bogdankostic, @camgrimsec, @chuenchen309, @davidpavlovschi, @davidsbatista, @DhanushPillay, @DivyaNarahari97, @erikos, @GovindhKishore, @hxaxd, @immuhammadfurqan, @iridescentWen, @jaideeppyne, @julian-risch, @kacperlukawski, @KXHXK, @LHMQ878, @LK-maker-007, @lntutor, @manjunathbhaskar, @mittalpk, @MVS-source, @onatozmenn, @otiscuilei, @pcbeingused333, @rautaditya2606, @sjrl, @sohumt123, @Solaris-star, @TimurRakhmatullin86, @vidigoat, @vinkiYu, @winklemad, @yaodong-shen
Fixed a remote code execution vulnerability that could be triggered by loading an untrusted pipeline in default safe mode ( Pipeline.load / Pipeline.l…
exit_reason is now a reserved state key on Agent. If you defined a custom state_schema key named exit_reason, rename it: the Agent now raises a ValueError at initialization when a reserved key is redefined.
Agent.state_schema now contains the user-provided state schema, exactly as passed to __init__. Previously it contained the resolved schema, which also included messages and the keys the Agent manages internally (step_count, token_usage, exit_reason, ...). If you were reading agent.state_schema to inspect the effective runtime schema, use the new public attribute agent.resolved_state_schema instead.
DocumentMAPEvaluator scores can change because average precision now uses all unique, valid ground-truth comparison values as its denominator and credits each value at most once. Re-baseline evaluations that relied on the previous scores.
PipelineSnapshot.pipeline_state.inputs changed shape. It used to store one flattened value per socket, {component: {socket: value}}. It now stores the pipeline's internal inputs, keeping the component that sent each one in the order it arrived: {component: {socket: [{"sender": ..., "value": ...}]}}. PipelineState gained an inputs_format field recording which of the two shapes a snapshot uses. The same applies to BreakpointException.inputs, which returns that field.
You are affected if you read pipeline_state.inputs (or BreakpointException.inputs) directly, for example to display or post-process a snapshot. Resuming a pipeline with Pipeline.run(pipeline_snapshot=...) is not affected, and neither is code that only passes snapshots around or persists them.
To adapt, read the input from the list and take its value:
inputs = snapshot.pipeline_state.inputs["serialized_data"]
# before
value = inputs["my_component"]["my_socket"]
# now
value = inputs["my_component"]["my_socket"][0]["value"]A socket that received inputs from several senders has one list item per input, each recording the sender that produced it.
Snapshots written by earlier versions of Haystack have inputs_format set to None and keep the flattened shape, so branch on that field if you need to handle both.
Loading a serialized OutputAdapter or ConditionalRouter whose unsafe init parameter is set to true now raises DeserializationError unless the pipeline is loaded in unsafe mode. Pipelines that legitimately rely on an unsafe OutputAdapter/ConditionalRouter embedded in serialized data must now load with Pipeline.load(..., unsafe=True) (or Pipeline.loads / Pipeline.from_dict with unsafe=True).
Passing window_size=0 to SentenceWindowRetriever.run or SentenceWindowRetriever.run_async now raises a ValueError instead of silently using the window_size set in the constructor. You are affected if you pass window_size=0 at runtime, either directly or from an upstream component in a pipeline. If you were relying on 0 to mean "use the value from the constructor", omit the argument (or pass None) instead:
retriever = SentenceWindowRetriever(document_store=document_store, window_size=3)
# Before: silently used window_size=3
retriever.run(retrieved_documents=docs, window_size=0)
# After: omit the argument to use the constructor value
retriever.run(retrieved_documents=docs)InMemoryDocumentStore.get_metadata_field_unique_values (and its async counterpart)'s search_term parameter now matches against the metadata field's own value (case-insensitive substring) instead of the document's content. Callers relying on the previous content-matching behavior will need to filter documents by content themselves before calling this method.
The Agent now warms up its hooks before every run, not only the first one, as it already does for Tools and Toolsets. If your hook has a warm_up() that does expensive setup (opening a client, loading a model), make it return early once done, for example if self._client is not None: return.
Haystack can call warm_up() on Tools and Toolsets more than once, for example before every run. Previously Toolset absorbed repeated calls with an internal _is_warmed_up flag; that flag is gone and every call now reaches your warm_up(). If your custom Tool or Toolset does expensive work there (connecting to a server, loading a model), or relied on the _is_warmed_up attribute, guard with your own state and return early, for example if self._client is not None: return.
Added a link_format parameter to both PyPDFToDocument and PDFMinerToDocument components, matching the existing functionality in DOCXToDocument. Links are parsed from PDF annotations and appended at the bottom of the page content.
Added experimental context compaction for the Agent. CompactionHook runs before LLM calls and shortens the conversation when it reaches a configured fraction of the model's context window.
The first built-in strategy, SlidingWindowCompactor, preserves leading system messages, the latest user task, and as much complete recent conversation as the target allows. It removes complete historical turns first, and only when removing every historical turn is insufficient does it remove individual Agent steps from the current task. It replaces removed history with a short omission note, left where the removed messages used to sit: directly after the leading system messages when only historical turns were removed, and directly after the latest user message when the current task's own steps were removed. Only one note is ever present, because a later compaction folds an earlier one into its replacement.
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor
hook = CompactionHook(
compactor=SlidingWindowCompactor(),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)
agent = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-nano"),
tools=[web_search],
hooks={"before_llm": [hook]},
)The hook uses provider-reported context usage when available and locally estimates the request otherwise, including tool schemas. Leave headroom above compact_at for the next reply and its tool results.
SlidingWindowCompactor treats an assistant message and its following tool results as one step, so a tool call is never separated from its results. Historical turns are likewise kept or removed in full, so an assistant reply is not retained without the user message it answers. It can also land above the requested target rather than under it, because leading system messages and the current task are never removed and min_keep_steps holds on to the newest Agent steps whatever their size, so a long system prompt or one large tool result can leave the conversation well over the target. Compaction is lossy: removed messages cannot be recovered or summarized by this strategy. Implement the Compactor protocol to provide a custom strategy.
CompactionHook and SlidingWindowCompactor emit an ExperimentalWarning and may change without a deprecation cycle.
Agent now returns an exit_reason output reporting why the run stopped, making it easier to route the Agent's output downstream (for example with a ConditionalRouter). It is one of: "text" (the model returned a reply with no tool calls), the name of the tool that satisfied a tool exit condition (in which case last_message is that tool's result), or "max_agent_steps" (the Agent hit max_agent_steps before meeting an exit condition). The reason is also available to hooks via state.get("exit_reason"), so an after_run hook can, for instance, append a fallback answer when the step budget is exhausted.
Add OpenAITokenCounter, which uses OpenAI's input token counting API to return model-specific counts for Haystack ChatMessage objects and optional tool schemas. Unlike local estimates, it supports OpenAI's exact accounting for request formatting, images, files, and tools.
Here is an example:
from haystack.dataclasses import ChatMessage
from haystack.token_counters import OpenAITokenCounter
counter = OpenAITokenCounter("gpt-5-mini")
count = counter.count([ChatMessage.from_user("Hello!")])Added haystack.token_counters: a TokenCounter protocol for estimating how many tokens a list of ChatMessage objects occupies, with two implementations.
Providers report token usage only after a call, and only for the call as a whole, so anything that needs a size beforehand - deciding whether a conversation still fits a model's context window, or how much of it to drop - has to estimate one.
from haystack.dataclasses import ChatMessage
from haystack.token_counters import ApproximateTokenCounter, TiktokenCounter
messages = [ChatMessage.from_user("Hello, how are you?")]
# No dependencies: estimates from text length.
ApproximateTokenCounter(chars_per_token=4.0).count(messages)
# Closer for OpenAI models; needs: pip install tiktoken
TiktokenCounter(encoding="o200k_base").count(messages)ApproximateTokenCounter needs nothing installed and estimates from text length at a configurable chars_per_token. TiktokenCounter counts with OpenAI's byte-pair encoder, which is closer for OpenAI models but requires tiktoken and drifts on other providers; it raises at construction when the dependency is missing, and loads its encoding on first use.
Neither can measure an image or a file, since a tokenizer only sees text and providers derive an image's cost from its dimensions. Both charge a flat tokens_per_image and tokens_per_file instead, counting images a tool returned inside its result as well as those a message carries directly. Raise those values if you send large images or long documents.
Tool schemas are sent alongside the messages and consume tokens too, so count takes an optional tools argument to have them included:
counter.count(messages, tools=[my_tool])Implement TokenCounter to count differently - for instance against a provider's own token-counting endpoint, which is the only way to have images counted exactly.
Added the experimental ToolResultPruningCompactor. It reduces Agent context usage by replacing older, large tool results with short placeholders while preserving tool-call/result structure. Results from a configurable number of recent tool-calling Agent steps remain intact, including parallel results from those steps.
from haystack.hooks.compaction import CompactionHook, ToolResultPruningCompactor
compaction_hook = CompactionHook(
compactor=ToolResultPruningCompactor(
min_keep_steps=2,
min_tokens=200,
),
context_window=400_000,
compact_at=0.7,
compact_to=0.4,
)Add an Agent.clone() method that returns a new Agent with the same configuration, optionally replacing some init parameters: variant = agent.clone(system_prompt="Answer in German.").
Added AgentTool, a Tool that wraps a Haystack Agent, allowing it to be used as a tool by another Agent. It is a building block for multi-agent systems: an Agent specialized in one task becomes a tool that another Agent can delegate to. The calling Agent only sees the final reply, so all the steps the wrapped Agent takes stay out of its context. Sensible defaults make this work out of the box: the task is delegated as a single user message and comes back as text.
Example:
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.tools import AgentTool, ComponentTool
from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
researcher = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4-mini"),
system_prompt="You are a research specialist. Investigate the task and report your findings.",
tools=[
ComponentTool(
component=SerperDevWebSearch(
top_k=3,
),
name="web_search",
description="Search the web for current information on any topic",
),
],
)
research = AgentTool(
agent=researcher,
name="research",
description="Research a question on the web and report the findings",
)
coordinator = Agent(
chat_generator=OpenAIResponsesChatGenerator(model="gpt-5.4"),
tools=[research],
system_prompt="You coordinate specialists. Delegate research questions, then answer the user.",
)
result = coordinator.run([ChatMessage.from_user("What are the latest developments in the Haystack framework?")])
print(result["last_message"].text)Haystack components that use a document store now provide close and close_async methods for releasing resources. These methods are available on: AutoMergingRetriever, CacheChecker, DocumentWriter, FilterRetriever, and SentenceWindowRetriever. If the underlying Document Store does not implement the corresponding method, calling close or close_async has no effect.
Add a content-free haystack.agent.hook tracing span for every Agent hook invocation. Each span identifies the hook point, hook name, and hook type, allowing hook latency and failures to be attributed without tracing the potentially large Agent State. CompactionHook also adds its configured compaction strategy, estimated context size, whether compaction was triggered, its token target, and whether the compactor returned a replacement.
DOCXLinkFormat to a reusable LinkFormat Enum in haystack/components/converters/utils.py. DOCXLinkFormat is now an alias for backward compatibility.Agent now tracks an approximate current context-window size in its internal State under context_tokens, refreshed after every LLM call with that reply's prompt-plus-completion tokens (normalized across the prompt_tokens/completion_tokens and input_tokens/output_tokens key conventions). Unlike token_usage, which accumulates across the whole run, context_tokens is replaced each call. Hooks can read it via state.get("context_tokens") — for example, a before_llm hook that triggers context compaction once the value crosses a threshold. It is a best-effort snapshot: it is 0 when the generator does not report usage, and does not count messages appended after the latest call until the next call refreshes it.before_run hooks can now read state.data["tools"]. The key was previously written only once the first step had started, so a before_run hook hit a KeyError. It holds a snapshot of the tools available at that point, refreshed before every LLM call, so with a dynamic toolset such as SearchableToolset a before_run hook sees only the tools discovered so far.strict_datetime_comparison keyword argument to document_matches_filter, InMemoryDocumentStore, and MetadataRouter. When enabled, timezone-naive and timezone-aware datetimes never match each other. By default, mixed-awareness datetimes continue to be reconciled by copying the timezone from the aware value to the naive one, and this behavior is now consistent across equality, membership, and ordering operators.filters parameter to InMemoryDocumentStore.get_metadata_field_unique_values (sync and async), allowing the set of documents considered when computing unique metadata field values to be restricted.InMemoryDocumentStore.get_metadata_field_unique_values and its async counterpart now support pagination via from_ and size parameters, matching the behavior of other Document Stores (e.g. Chroma).MockChatGenerator's response_fn can now be tool-aware. If the callable accepts a second positional argument, it also receives the tools passed to run/run_async (a ToolsType or None), so a dynamic mock can build tool calls whose arguments follow the tool's parameter schema or route between the available tools. Existing single-argument response_fn callables are unaffected and keep receiving only the messages.State.to_dict now accepts a skip_keys parameter to exclude specific keys from the output.ConfirmationStrategy run to ConfirmationHook. Each haystack.agent.hook.human_in_the_loop.strategy span identifies the tool call it confirms and records the strategy type and the applied confirm, modify, or reject decision. When content tracing is enabled, spans also carry the arguments the strategy was run with and the ToolExecutionDecision it returned under haystack.agent.hook.human_in_the_loop.strategy.input and haystack.agent.hook.human_in_the_loop.strategy.output; chat messages, the confirmation strategy context, and the Agent State are not recorded by the hook.LLMEvaluator, LLMRanker, QueryExpander, LLMMetadataExtractor, LLMDocumentContentExtractor and LLMMessagesRouter now wrap their internal ChatGenerator calls in a haystack.chat_generator.run tracing span. These components do not return ChatMessage objects, so the LLM token usage carried in reply.meta["usage"] was previously lost to tracers. The new span exposes the generator's replies via the haystack.component.output tag, so token usage is now visible in traces (requires content tracing to be enabled). When the generator runs across threads, the span is nested under the component's span.+ operator (toolset_a + toolset_b) and passing a Toolset to add() (toolset_a.add(toolset_b)). Pass Toolsets as a list wherever tools are accepted instead: Agent(tools=[toolset_a, toolset_b]).Pipeline.load / Pipeline.loads / Pipeline.from_dict, without unsafe=True). A malicious pipeline could either (a) set unsafe: true on an OutputAdapter or ConditionalRouter to disable the Jinja sandbox entirely, or (b) register the thread_safe_import import primitive as a Jinja custom_filters entry to import os and execute arbitrary commands — bypassing the deserialization allowlist and Jinja sandbox. The fix denies import primitives during callable deserialization, refuses to honor a component's unsafe flag while loading in safe mode, and hardens the Jinja sandbox (OutputAdapter, ConditionalRouter, PromptBuilder, ChatPromptBuilder) to block attribute access on module objects and calls into dangerous modules.Pipeline.loads / Pipeline.load / Pipeline.from_dict, which accept unsafe=True) and the execute primitives (Pipeline.run / run_async / run_async_generator / stream) were still resolvable from the allowlisted haystack namespace. Bound as a custom_filters entry on an OutputAdapter or ConditionalRouter (which bypass the Jinja sandbox), Pipeline.loads(..., unsafe=True) let a pipeline loaded in default safe mode load a nested pipeline whose own filters (allow_deserialization_module, deserialize_callable) bind under the nested unsafe context, disarming the process-wide allowlist with "*" and invoking os.system. All of these entry points are now marked as deserializer-internal, so they can never be produced by deserializing untrusted data. unsafe=True still bypasses the check by design; there are no public API changes.Pipeline.load / Pipeline.loads / Pipeline.from_dict, without unsafe=True). Because the deserialization allowlist admits the whole haystack namespace, the deserializer's own allowlist-administration function (allow_deserialization_module) and its resolution helpers (deserialize_callable, deserialize_type, import_class_by_name) were themselves resolvable from serialized data. A malicious pipeline could register allow_deserialization_module as a Jinja custom_filters entry (on an OutputAdapter or ConditionalRouter), call it with "*" to disarm the allowlist process-wide, and then use the equally-resolvable deserialize_callable to resolve and invoke os.system. Loading alone was enough to trigger this: a Jinja filter called with constant arguments runs while the component is being constructed, so the pipeline never had to be run. The same attribute walk could also reach the deserializer's mutable control-plane state directly — for example a filter bound to _extra_allowed_modules.append — to widen the allowlist persistently and stage a later attack. Relatedly, the handle resolver walked attribute names freely, so a handle could descend into object internals such as <function>.__globals__ (a live module namespace, and via it __builtins__ and eval/exec) or <type>.__subclasses__ — classic sandbox-escape gadgets that stay inside an allowlisted module. The fix refuses to deserialize the deserialization control plane as a whole: the allowlist administration and resolution helpers (marked at definition time), everything defined in haystack.core.serialization_security, and any bound method of the mutable allowlist/context state. It also refuses to traverse into dunder and frame/code attributes while resolving a handle. This applies to both the callable- and class-resolution paths, and is bypassed only when the pipeline is loaded with unsafe=True.FileSystemToolResultStore.read() so it only reads references that resolve within the configured store root. This closes a boundary gap where callers could previously pass an arbitrary filesystem path to read() instead of a store-scoped reference returned by write().Fixed the serialization of PDFMinerToDocument. The component did not define to_dict, so the default serialization fell back to reading the init parameters from same-named attributes. Since the layout parameters are stored in self.layout_params, they were silently serialized with their default values, for example a component created with char_margin=0.5 was serialized with char_margin=2.0. Custom layout parameters are now preserved when a pipeline is serialized and loaded again.
Cancel and await sibling retrieval tasks when a concurrent call fails in MultiRetriever, MultiQueryTextRetriever, or MultiQueryEmbeddingRetriever.
Fixed an infinite recursion in CSVDocumentSplitter when nested row and column blocks were split together.
Comparing two Document objects with == now takes all metadata into account. Previously, two documents with different metadata could be considered equal if the metadata contained keys with the same names as document fields (such as id or content).
Document.from_dict(document.to_dict()) now correctly rebuilds any document. Previously, if the metadata contained keys with the same names as document fields (such as id or meta), this either raised an error or silently lost those metadata entries.
Fixed DocumentNDCGEvaluator producing NDCG scores outside the documented 0.0 to 1.0 range when the same document appeared more than once. A document retrieved multiple times used to be counted multiple times, pushing the score above 1.0; a ground truth document listed multiple times used to inflate the ideal gain, keeping a perfect retrieval below 1.0. Each distinct relevant document is now counted once, with the same relevance, in both the actual and ideal gain, so scores stay within range.
Fixed AnswerBuilder returning referenced documents in a scrambled order instead of ascending source-index order. The referenced document indices were collected in a set and iterated directly, so documents were emitted in the set's internal hash-table order (e.g. citations [3] [10] [50] yielded documents ordered 10, 3, 50). This order was deterministic but did not match the intuitive source order. The referenced documents are now returned sorted by their source index.
Fixed serialize_type and deserialize_type to correctly round-trip Callable types that declare an explicit parameter list, such as Callable[[int, str], bool]. Previously the parameter list was dropped during serialization (producing a malformed string like typing.Callable[, bool]) and could no longer be deserialized. This affected components that serialize type annotations, for example ConditionalRouter and OutputAdapter using a Callable output type.
Fix DocumentMAPEvaluator to include missed relevant documents in the average precision denominator and avoid crediting duplicate retrievals of the same document.
Fixed DocumentSplitter producing chunks that were not present in the source document when split_threshold was set together with split_overlap. Merging a below-threshold trailing segment into the previous split re-appended the overlapping units, duplicating text. The overlap is now added only once.
Fixed EmbeddingBasedDocumentSplitter.run_async embedding through the synchronous path while recursively splitting chunks longer than max_length. Only the first pass was async: the recursion called the sync splitting helper, so the embedder's blocking run ran on the event loop for every over-long chunk. The recursion now embeds through run_async as well.
Fixed JSONConverter raising a KeyError instead of logging its intended "Failed to extract text, skipping it" warning when a source is a ByteStream without a file_path in its meta (for example ByteStream.from_string(...), the exact usage shown in the component's own docstring examples). Affected error paths: invalid UTF-8 content, a jq_schema filter that fails to apply, and malformed JSON content.
Fixed LinkContentFetcher rotating the User-Agent on a cursor shared by every URL in the same run()/run_async() call. The URLs are fetched concurrently, so a retry triggered by one of them advanced the user agent for the others, and each completed fetch reset the cursor for the requests still in flight — most retries went out with the un-rotated user agent. Each fetch now walks the user_agents list on its own, so a URL rotates exactly as documented no matter how many other URLs are fetched alongside it.
Fixed MarkdownHeaderSplitter silently dropping a trailing header that has no body text. With keep_headers=True (the default), a header at the end of the document whose only content is whitespace was buffered to prepend to the next chunk, but with no following chunk it was never emitted, so the split documents no longer reconstructed the original text. Such trailing headers are now emitted as a final chunk.
Fixed MarkdownHeaderSplitter collapsing blank lines that follow a header with no body text. With keep_headers=True, such headers were re-joined with a single newline when prepended to the next chunk, so the split documents did not reconstruct the original text. Chunk content is now sliced from the original text and is byte-exact.
Fixed MarkdownHeaderSplitter including surrounding whitespace in the header and parent_headers metadata fields. The header text is now stripped; chunk content still keeps the header line's original whitespace.
Fixed schema-based serialization of lists, tuples and sets holding mixed types. Previously the schema was derived from the first element only, so deserializing such a value raised an AttributeError or silently returned mis-typed data (for example an Agent State field or a pipeline breakpoint input holding [Document(...), "text", 3]). Mixed-type arrays now record one schema per position using the JSON Schema prefixItems keyword and round-trip correctly. Homogeneous arrays keep the exact same output as before, so existing snapshots still load.
Fixed MSGToDocument raising a KeyError when converting a ByteStream source that has no file_path in its meta (for example a bare ByteStream(data=...), rather than a file path or a stream produced via ByteStream.from_file_path). Attachments extracted from such a source no longer include a parent_file_path key, since there is no source file path to record.
Pipeline connections now always convert values in the same way. When a component output is connected to an input that accepts multiple types, Haystack is sometimes able to automatically convert the value, and more than one conversion may be possible. For example, a ChatMessage with text "hello" connected to an input annotated str | list[str] can be delivered either as plain text ("hello") or as a list containing the text (["hello"]). Previously the conversion strategy was chosen non-deterministically, so the same pipeline could return a different value across runs. The conversion strategy is now selected using a fixed priority: first, wrapping a value in a list or unwrapping a single-element list; second, converting between ChatMessage and str; and last, combining both conversions.
Fixed normalize_metadata (used by all file converters) returning the same dictionary object for every source when meta is None or a single dictionary. Each source now receives an independent copy, so mutating one source's metadata downstream no longer leaks into the others.
OpenAIResponsesChatGenerator no longer mutates the parameters schema of the Tool objects passed to it. Previously every run wrote additionalProperties: False into the user's live Tool.parameters, silently altering the tool for any other generator that shared the same Tool instance and making serialization round trips unstable.
OpenAIResponsesChatGenerator no longer raises IndexError when it is warmed up with an empty tools list.
Fixed the parent of the haystack.agent.step.tool spans when an Agent step invokes several tools. The parent span is now resolved once before the tools run, so all tool calls of a step appear as siblings. Previously each span asked the tracer for the currently active span from inside its own concurrent invocation, which made the tool calls after the first one appear nested under a sibling tool call.
Fixed the haystack.pipeline.output_data tracing tag being empty. The tag was set at the start of Pipeline.run/run_async from the still-empty outputs, and since tracing backends coerce a tag value when it is set, the recorded output was always an empty dictionary. It is now set once the run completes so it reflects the final pipeline outputs. The tag is also gated behind content tracing (HAYSTACK_CONTENT_TRACING_ENABLED), consistent with the component-level input/output tags.
Fixed resuming a Pipeline from a pipeline_snapshot that was taken on a component's second or later visit, which failed with PipelineComponentsBlockedError: Cannot run pipeline - all components are blocked. A snapshot stored only the values of the pipeline's inputs and dropped the information about which component had sent each one, so on resume every restored input looked like it came from outside the pipeline, and such an input can only trigger a component on its first visit. Snapshots now record the sender of each input. Snapshots created by earlier versions of Haystack behave as before, so re-create them to resume anywhere in a looping pipeline.
Fixed a resumed Pipeline passing malformed inputs to the component the snapshot was taken on, whenever that component ran more than once after the resume, for example inside a loop. Every visit after the first reused the handling meant only for the paused visit and skipped the regular input consumption, so a variadic component could receive a bare value where it expected a list, raising errors such as TypeError: object of type 'int' has no len() from a BranchJoiner. This affected snapshots taken at any visit count, including the first.
Fixed QueryExpander returning duplicate queries when the chat generator repeats an expansion. Generated queries are now deduplicated while preserving first-seen order, so repeated expansions no longer trigger redundant retrievals or consume the requested expansion budget. Both run and run_async are affected.
RecursiveDocumentSplitter's word-mode fixed-size fallback no longer counts a run of whitespace (e.g. a double space, tab, or page break) as a word, so it no longer produces chunks smaller than split_length. It also no longer emits a whitespace-only chunk when the text ends in whitespace right after a chunk boundary; that trailing whitespace is now attached to the previous chunk instead.
This changes the exact chunk boundaries and chunk count produced by the word-unit fallback for any text containing such whitespace runs. Documents already split and indexed under the old behavior will produce different chunks if re-split after upgrading, so re-index any document store that relies on stable chunk boundaries from this fallback path.
Fixed an issue where PipelineBase.remove_component did not reset auto-variadic socket flags (is_lazy_variadic and wrap_input_in_list) on input sockets when components or connections were removed.
Fixed Pipeline.remove_component leaving dangling references to the removed component on the sockets of its neighboring components. Previously, removing a component reset only its own sockets, so a surviving neighbor kept the removed component's name in its input socket's senders (or output socket's receivers). This corrupted introspection and validation: Pipeline.inputs() hid a now-unconnected mandatory input, and feeding that input directly could raise a spurious "already connected" error. The removed component's name is now stripped from its neighbors' sockets as well.
SentenceWindowRetriever.run and SentenceWindowRetriever.run_async now validate an explicitly provided window_size=0 instead of treating it as unset and falling back to the constructor value.
Fixed the schema-aware serialization helper used for pipeline snapshots and Agent State (_serialize_value_with_schema) so it no longer silently passes unsupported objects through as if they were serialized. Values such as datetime, bytes, complex and arbitrary objects without a to_dict method were previously stored unchanged and mislabeled as strings, which broke JSON storage and round-tripping of snapshots. Unsupported values now raise a SerializationError, and the callers that build snapshots (pipeline breakpoints and State.to_dict) catch it to omit only the offending field while keeping the rest of the payload resumable.
Added support for serializing and deserializing frozenset values in _serialize_value_with_schema. A frozenset now round-trips back to a frozenset instead of being dropped.
Fixed serialize_type/deserialize_type for typing.Literal. Previously a Literal type hint was serialized with its values rendered as bare tokens (e.g. typing.Literal[yes, no]), which failed to deserialize, and values that looked like type names (e.g. Literal["int", "str"]) were silently turned into types on the round-trip. The values are now serialized with repr() and read back with ast.literal_eval, so a Literal type used by a component (such as OutputAdapter or ConditionalRouter) round-trips correctly through pipeline serialization.
Fixed an AttributeError: 'str' object has no attribute 'items' raised by create_tool_from_function, the @tool decorator, and ComponentTool when a tool parameter is named properties. Keys inside a JSON schema properties mapping are property names and are no longer misinterpreted as schema keywords when stripping the auto-generated title keywords.
Fixed create_tool_from_function, the @tool decorator, and ComponentTool corrupting a tool's JSON schema when the string title appears as a name rather than as a schema keyword. Stripping the auto-generated title keywords no longer deletes entries of $defs, definitions, patternProperties, dependentSchemas or dependentRequired (which would leave a $ref dangling or silently drop a validation rule), and no longer edits title keys inside default, const, enum or examples values, which are instance data and part of the tool's contract.
Fixed _ToolsetWrapper.__getitem__ (used when combining Toolsets with +) raising IndexError for negative indices, unlike a plain Toolset. Indexing a combined toolset now behaves consistently with a list of Tools, as documented.
Fixed serialization of types that contain ... (Ellipsis), such as variadic tuples (tuple[int, ...]) and Callable[..., X]. Previously serialize_type rendered the ... as the literal string "Ellipsis", which deserialize_type then rejected as a non-type builtin, so a component using such a type (for example OutputAdapter(output_type=tuple[int, ...])) could be serialized but not deserialized, breaking Pipeline.loads() / Pipeline.load(). These types now round-trip correctly, and pipelines serialized by older versions (which emitted "Ellipsis") can still be loaded.
Fixed ConfirmationHook applying a Human-in-the-Loop decision to the wrong tool call when a custom ConfirmationStrategy returns a decision with a missing or incorrect tool_call_id. Each decision is now bound to the tool call for which its strategy ran, and ID-bearing decisions are no longer matched to a different call by name. Haystack's existing requirement of exactly one decision per tool call is now explicitly enforced. Each matched decision is consumed after use, so a missing, unused, or reused decision raises a ValueError instead of being silently misapplied.
DocumentJoiner and AnswerJoiner now resolve top_k consistently and validate it. Previously, a runtime top_k=0 was treated as "unset" and silently fell back to the instance's top_k, instead of returning an empty list as requested. Both components now:
ValueError at initialization if top_k is not None and is less than or equal to 0.ValueError at runtime if top_k passed to run() is negative.run() is called with top_k=0, regardless of the instance's configured top_k.Fixes MetaFieldRanker silently treating a runtime top_k=0 as unset and falling back to the value configured at initialization. Runtime values that are not greater than zero now raise a ValueError as documented.
Fixed PythonCodeSplitter losing identifying context for oversized functions, methods, or classes. When a unit is too large and falls back to line-based secondary splitting, only the first resulting piece naturally retains the source def/class line; every piece now includes a qualified_name field in meta identifying the function, method, or class it came from.
Fixed RecursiveDocumentSplitter not setting the source_id meta field on the chunks it produces. It wrote only parent_id, while every other splitter in the library (DocumentSplitter, CSVDocumentSplitter, EmbeddingBasedDocumentSplitter, HierarchicalDocumentSplitter, MarkdownHeaderSplitter and PythonCodeSplitter) writes source_id. Components that follow that convention therefore rejected its output: SentenceWindowRetriever reads source_id by default and raises when it is absent, so it failed with "The retrieved documents must have 'source_id' in their metadata." on a pipeline that worked with any other splitter. Chunks now carry source_id as well as parent_id, which keeps its previous value for callers already reading it.
Tool functions defined in a module using from __future__ import annotations are now inspected correctly by Agent. Postponed annotations are stored as strings, so a parameter annotated with State was not recognized and the live State object was not injected into the tool call. The annotations are now resolved before they are inspected.
MarkdownHeaderSplitter and CSVDocumentSplitter now deep-copy the metadata of the document they split, matching DocumentSplitter. Previously they copied it shallowly, so nested values such as a list under meta["tags"] were shared between every chunk and with the input document, and editing one chunk's metadata changed all the others. HierarchicalDocumentSplitter had the same problem on its root node, which kept references into the input document's metadata.
Keep an Agent's execution counter in sync with step_count restored by a before_run hook, so restarted Agents continue from the saved step instead of resetting the count.
@Aarkin7, @anakin87, @anxkhn, @aquib8112, @Aryan-Pardeshi, @atikulmunna, @bharadwaj-pendyala, @bilgeyucel, @bogdankostic, @camgrimsec, @chuenchen309, @davidpavlovschi, @davidsbatista, @DhanushPillay, @DivyaNarahari97, @erikos, @GovindhKishore, @hxaxd, @immuhammadfurqan, @iridescentWen, @jaideeppyne, @julian-risch, @kacperlukawski, @KXHXK, @LHMQ878, @LK-maker-007, @lntutor, @manjunathbhaskar, @mittalpk, @MVS-source, @onatozmenn, @otiscuilei, @pcbeingused333, @rautaditya2606, @sjrl, @sohumt123, @Solaris-star, @TimurRakhmatullin86, @vidigoat, @vinkiYu, @winklemad, @yaodong-shen
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
A few small, intentional breaking changes come with it but our Migration Guide and Upgrading to Haystack 3.0 make it easy to upgrade.
Haystack 3.0 is a major release for building production-grade agents with full control and flexibility. It ships a wave of new capabilities: a more capable Agent with hooks and first-class skills, built-in run introspection, first-class async for serving, a leaner core, and safer pipeline loading.
A few small, intentional breaking changes come with it but our Migration Guide and Upgrading to Haystack 3.0 make it easy to upgrade.
AgentThe Agent gained a general-purpose hooks system and now owns tool execution end to end (the standalone ToolInvoker has been removed). Hooks at before_run, before_llm, before_tool, after_tool, on_exit, and after_run let you shape behavior, enforce guardrails, and add human-in-the-loop checkpoints without touching the agent's internals:
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.hooks import hook
@hook
def audit_tool_calls(state):
pending = state.data["messages"][-1].tool_calls
print(f"about to run: {[tc.tool_name for tc in pending]}")
agent = Agent(
chat_generator=OpenAIChatGenerator(),
tools=[...],
hooks={"before_tool": [audit_tool_calls]},
)
Built on this foundation:
SkillToolset discovers skills through progressive disclosure, so the model sees only names and one-line descriptions until it loads one, keeping context lean.tools=... to run / run_async so one reusable Agent serves different teams, tenants, and tasks.@tool routes async def callables to a Tool's new async_function.before_tool hook (ConfirmationHook). ⚠️ToolResultOffloadHook) writes large results to a store and leaves a compact pointer in the conversation.Agents now expose step_count, token_usage, and tool_call_counts as built-in state. React to them to compact context when the window fills, cap runaway tool loops, or route to a cheaper approach past a budget threshold. Tracing now emits dedicated step-level spans (haystack.agent.step with nested .llm / .tool children) tagged with the tools actually used, so you can see exactly what your agent did. ⚠️
Pipeline and AsyncPipeline are now one class — no more switching between them. A single Pipeline exposes run, run_async, run_async_generator, and stream; serialized pipelines, SuperComponents, and PipelineTools load as Pipeline instances. ⚠️
from haystack import Pipeline
pipeline = Pipeline()
result = pipeline.run(data) # synchronous
result = await pipeline.run_async(data) # asynchronous
Concurrent tool calls and token-by-token streaming come standard: Pipeline.stream() yields StreamingChunks as they're produced and exposes the final output on handle.result — the lower latency and streaming UX serving apps need. Components and Pipeline also get a symmetric lifecycle — warm_up to acquire, close to release — so long-running services don't leak connections, GPU memory, or file handles. External resources (and API keys) are now created at warm_up, not in __init__. ⚠️
Legacy Generators are gone, haystack-experimental is no longer a core dependency, and 30 components now live in independently released packages in haystack-core-integrations: Sentence Transformers, local & API Hugging Face, Whisper, spaCy/langdetect, Tika and Azure OCR, SerperDev/SearchApi, OpenAPI connectors, and the Datadog/OpenTelemetry tracers. As a result, there are fewer transitive dependencies to audit and we can ship independent of the core release cycle. Migration is an install plus an import change:
# pip install sentence-transformers-haystack
# Before: from haystack.components.embedders import SentenceTransformersTextEmbedder
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
The full old → new import table is in MIGRATION.md.
OpenAIGenerator, AzureOpenAIGenerator, HuggingFaceAPIGenerator, and HuggingFaceLocalGenerator have been removed in favor of their Chat Generator counterparts. To ease the switch, all Chat Generators now accept a plain str for messages:
# Before
from haystack.components.generators import OpenAIGenerator
text = OpenAIGenerator().run("What is NLP?")["replies"][0] # str
# After
from haystack.components.generators.chat import OpenAIChatGenerator
reply = OpenAIChatGenerator().run("What is NLP?")["replies"][0] # ChatMessage
text = reply.text # str; metadata in reply.meta
DALLEImageGenerator was also renamed to OpenAIImageGenerator. ⚠️
Pipeline deserialization (Pipeline.load / loads / from_dict) is now gated by a trusted-module allowlist (haystack, haystack_integrations, haystack_experimental, builtins, typing, collections by default), and dangerous builtins like eval, exec, open, and getattr can no longer be resolved. Allowlist custom modules when needed:
Pipeline.load(fp, allowed_modules=["mypkg.*"]) # or HAYSTACK_DESERIALIZATION_ALLOWLIST / allow_deserialization_module(...)
Pipeline.load(fp, unsafe=True) # only if you fully trust the source
Newly added mock components mean no API keys, no network, no flaky CI for testing and prototyping. MockChatGenerator returns predefined responses, MockTextEmbedder and MockDocumentEmbedder return stable, hash-derived embeddings.
Agent, PromptBuilder, and ChatPromptBuilder now treat every Jinja2 variable as required (required_variables=None restores the old behavior); a new {% insert %} tag interleaves runtime messages. ⚠️State injection by name — tools must declare inputs_from_state explicitly to read a State value; same-named parameters no longer fill in automatically. ⚠️Document.id — computed from canonical, key-sorted JSON of meta, so documents with non-empty meta get different IDs than in 2.x. ⚠️configure_logging attaches to Haystack's own loggers; importing Haystack no longer reconfigures structlog process-wide. ⚠️OpenTelemetryConnector / DatadogConnector or call tracing.enable_tracing(...). ⚠️See the Upgrade Notes below for the full list.
AsyncPipeline has been removed. Its asynchronous capabilities are now part of the single Pipeline class, which provides both a synchronous run method and the asynchronous run_async, run_async_generator, and stream methods (mirroring how components expose run and run_async).
To migrate, replace AsyncPipeline with Pipeline:
# Before
from haystack import AsyncPipeline
pipeline = AsyncPipeline()
result = await pipeline.run_async(data)
# After
from haystack import Pipeline
pipeline = Pipeline()
result = await pipeline.run_async(data)
Serialized pipelines, SuperComponents, and PipelineTools are loaded as Pipeline instances.
Pipeline.run runs synchronously and blocks until completion; in an async context use await pipeline.run_async(...). The former AsyncPipeline.run was a synchronous wrapper around the concurrent engine, so to preserve that behavior use asyncio.run(pipeline.run_async(...)). Note that Pipeline.run executes components sequentially and does not accept concurrency_limit.
Both synchronous and asynchronous runs are traced under a single haystack.pipeline.run operation name, distinguished by a haystack.pipeline.execution_mode tag (sync or async). Previously, asynchronous runs used the haystack.async_pipeline.run operation name.
continue_run is now a reserved key in Agent.state_schema (set by an on_exit hook to keep the Agent running). Passing it via the state_schema argument now raises ValueError. Rename any conflicting state key (e.g. my_continue_run) to migrate.
Agent no longer validates exit_conditions against tool names at initialization. Exit conditions are now evaluated at runtime, so a condition naming a tool that is loaded later — e.g. a tool passed at runtime or one discovered by SearchableToolset — works as expected. Consequently, an unknown exit-condition name no longer raises a ValueError at construction.
Tool support is now validated against the tools resolved for each run, not only the tools provided at initialization. Passing tools at runtime via run(tools=...) to a chat generator that does not support tools now raises a TypeError instead of silently ignoring them.
Agent now treats every Jinja2 template variable in user_prompt and system_prompt as required by default. The default of the required_variables init parameter has changed from None (all variables optional) to "*" (all variables required). This aligns Agent with LLM, PromptBuilder, and ChatPromptBuilder.
To check if you're affected: look for Agent(...) calls that pass a user_prompt or system_prompt containing template variables without passing required_variables. If those Agents relied on missing variables being silently rendered as empty strings, the behavior depends on how the missing variable was reaching the Agent:
agent.run() directly without providing a required variable now raises ValueError.Pipeline.run raises ValueError("Missing mandatory input '<var>' for component '<name>'.").PipelineComponentsBlockedError.Migration options:
required_variables=["var1", "var2"].required_variables=None.Components in Haystack that use external resources now consistently create those resources during warm-up rather than in __init__. As a result, some components that previously raised errors during initialization (for example, because of a missing API key) now raise them during warm_up instead. Similar changes will be rolled out to components in Haystack Core Integrations in the future.
step_count, token_usage, and tool_call_counts are now reserved keys in Agent.state_schema. Passing any of them via the state_schema argument now raises ValueError. Rename the conflicting state key (e.g. my_token_usage) to migrate.
Confirmation strategies now receive the model-requested tool arguments in tool_params rather than the fully-prepared arguments. Values injected from State via a tool's inputs_from_state mapping (and the State object injected into State-typed parameters) are no longer included in what is presented for confirmation — that injection now happens only at tool execution time. If your ConfirmationUI or ConfirmationPolicy displayed or inspected those state-injected values, it will now see only the arguments the model provided.
The hash used to auto-generate Document.id is now computed from a canonical (key-sorted) JSON serialization of meta. Documents with empty meta are unaffected, but most other documents will get different IDs than they did before:
meta (the serialization changes from dict's repr to JSON);meta contains non-JSON-serializable values such as datetime or custom classes (these are now serialized via str(...) rather than repr(...), e.g. "2024-01-01 00:00:00" instead of "datetime.datetime(2024, 1, 1, 0, 0)").If you rely on auto-generated IDs to match documents already persisted in a DocumentStore, you will need to re-ingest the affected documents (or pass the previous id explicitly when constructing the Document).
Pipeline deserialization (Pipeline.load / Pipeline.loads / Pipeline.from_dict) now refuses to import classes from modules outside a trusted-module allowlist. By default the allowlist contains haystack, haystack_integrations, haystack_experimental, builtins, typing, and collections. Pipelines that reference custom components or callables in other packages will fail to load with a DeserializationError until the additional modules are added to the allowlist.
To restore loading of such pipelines, extend the allowlist via one of:
Pipeline.load(fp, allowed_modules=["mypkg.*"]);from haystack.core.serialization import allow_deserialization_module;HAYSTACK_DESERIALIZATION_ALLOWLIST="mypkg.*,otherpkg.*";Pipeline.load(fp, unsafe=True).During pipeline deserialization, default_from_dict now validates the keys of init_parameters against the parent class's __init__ signature before recursing into any nested {"type": "...", "init_parameters": {...}} dictionary. A nested dict whose key is not an accepted parameter name on the parent class is rejected with a DeserializationError before the nested type is imported. Classes whose constructor takes **kwargs are exempt, since their accepted parameter set cannot be statically determined.
This may surface pre-existing YAML bugs — e.g. typos, leftovers from renamed or removed parameters, or stale snapshots from older Haystack versions. The fix is to update the YAML so each nested-component key matches a real __init__ parameter on the parent class.
PromptBuilder and ChatPromptBuilder now treat every Jinja2 template variable as required by default. Previously, variables were optional by default unless explicitly listed in required_variables.
To check if you're affected: look for PromptBuilder(...) or ChatPromptBuilder(...) calls in your code that do not pass required_variables. If those components relied on missing variables being silently rendered as empty strings, the behavior depends on how the missing variable was reaching the builder:
builder.run() directly without providing a required variable now raises ValueError.Pipeline.run raises ValueError("Missing mandatory input '<var>' for component '<name>'.").PipelineComponentsBlockedError.Migration options:
required_variables=["var1", "var2"].required_variables=None.Human-in-the-Loop tool confirmation on Agent is now expressed as a before_tool hook instead of a dedicated concept. The confirmation_strategies and confirmation_strategy_context parameters have been removed from Agent.__init__, Agent.run, and Agent.run_async. To migrate, wrap your confirmation strategies in the new ConfirmationHook, register it under the before_tool hook point, and pass any request-scoped resources through the generic hook_context run argument instead of confirmation_strategy_context. The Human-in-the-Loop module has also moved from haystack.human_in_the_loop to haystack.hooks.human_in_the_loop, so that it lives alongside the other built-in hooks (such as tool result offloading); update your imports to the new location:
from haystack.components.agents import Agent
from haystack.hooks.human_in_the_loop import (
AlwaysAskPolicy,
BlockingConfirmationStrategy,
ConfirmationHook,
RichConsoleUI,
)
confirmation_hook = ConfirmationHook(
confirmation_strategies={
"my_tool": BlockingConfirmationStrategy(
confirmation_policy=AlwaysAskPolicy(), confirmation_ui=RichConsoleUI()
)
}
)
agent = Agent(chat_generator=..., tools=[...], hooks={"before_tool": [confirmation_hook]})
agent.run(messages=[...], hook_context={"websocket": ws})
The agent-specific breakpoint API has been removed. The AgentBreakpoint, ToolBreakpoint, and AgentSnapshot dataclasses are no longer exported from haystack.dataclasses, and the break_point, snapshot, and snapshot_callback parameters have been removed from Agent.run and Agent.run_async. Pipeline.run no longer accepts AgentBreakpoint for its break_point argument, and the agent_snapshot field has been removed from PipelineSnapshot. Pipeline-level breakpoints via Breakpoint and PipelineSnapshot continue to work as before, but pausing and resuming execution inside an Agent (at the chat generator or tool invoker) is no longer supported.
AzureOCRDocumentConverter has been moved out of Haystack into the azure-form-recognizer-haystack integration package. Install the new package with pip install azure-form-recognizer-haystack and update your imports.
Before:
from haystack.components.converters import AzureOCRDocumentConverter
After:
from haystack_integrations.components.converters.azure_form_recognizer import AzureOCRDocumentConverter
The DatadogTracer has been moved out of Haystack into the datadog-haystack integration package. It is no longer auto-enabled when ddtrace is installed; instead, use the new DatadogConnector component to enable Datadog tracing in your pipeline. Install the new package with pip install datadog-haystack.
Before:
import ddtrace
from haystack import tracing
from haystack.tracing.datadog import DatadogTracer
tracing.enable_tracing(DatadogTracer(ddtrace.tracer))
After:
from haystack import Pipeline
from haystack_integrations.components.connectors.datadog import DatadogConnector
pipe = Pipeline()
pipe.add_component("tracer", DatadogConnector())
Alternatively, you can still enable the tracer manually:
import ddtrace
from haystack import tracing
from haystack_integrations.tracing.datadog import DatadogTracer
tracing.enable_tracing(DatadogTracer(ddtrace.tracer))
OpenAIGenerator, AzureOpenAIGenerator, HuggingFaceAPIGenerator, and HuggingFaceLocalGenerator have been removed. Use the Chat Generators instead: OpenAIChatGenerator, AzureOpenAIChatGenerator, HuggingFaceAPIChatGenerator, and HuggingFaceLocalChatGenerator. As of v3.0, all ChatGenerators accept a plain str as input and normalise it to a user message.
Before:
from haystack.components.generators import OpenAIGenerator
gen = OpenAIGenerator()
text = gen.run("What is NLP?")["replies"][0] # str
After:
from haystack.components.generators.chat import OpenAIChatGenerator
gen = OpenAIChatGenerator()
reply = gen.run("What is NLP?")["replies"][0] # ChatMessage
text = reply.text # str; metadata is in reply.meta
DALLEImageGenerator has been renamed to OpenAIImageGenerator and moved to haystack.components.generators.openai_image_generator. The rename reflects that OpenAI retired the DALL-E model family but the component works with newer image generation models.
Before:
from haystack.components.generators import DALLEImageGenerator
generator = DALLEImageGenerator()
After:
from haystack.components.generators import OpenAIImageGenerator
generator = OpenAIImageGenerator()
haystack-experimental is no longer a core dependency of Haystack and is no longer installed automatically with haystack-ai. If your code imports from haystack_experimental (directly or through an integration that relies on it), you must now install it explicitly, for example with pip install haystack-experimental. Installations that do not use haystack_experimental are unaffected.
HuggingFaceAPIChatGenerator, HuggingFaceAPITextEmbedder, HuggingFaceAPIDocumentEmbedder, and HuggingFaceTEIRanker have been moved out of Haystack into the huggingface-api-haystack integration package. Install the new package with pip install huggingface-api-haystack and update your imports.
Before:
from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
from haystack.components.embedders import HuggingFaceAPITextEmbedder, HuggingFaceAPIDocumentEmbedder
from haystack.components.rankers import HuggingFaceTEIRanker
After:
from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
from haystack_integrations.components.embedders.huggingface_api import (
HuggingFaceAPITextEmbedder,
HuggingFaceAPIDocumentEmbedder,
)
from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker
DocumentLanguageClassifier and TextLanguageRouter have been moved out of Haystack into the langdetect-haystack integration package. Install the new package with pip install langdetect-haystack and update your imports.
Before:
from haystack.components.classifiers import DocumentLanguageClassifier
from haystack.components.routers import TextLanguageRouter
After:
from haystack_integrations.components.classifiers.langdetect import DocumentLanguageClassifier
from haystack_integrations.components.routers.langdetect import TextLanguageRouter
The NamedEntityExtractor component (along with the NamedEntityAnnotation and NamedEntityExtractorBackend classes) has been removed from Haystack and moved into dedicated integration packages, one per backend.
For the Hugging Face backend, install transformers-haystack and update your imports:
Before:
from haystack.components.extractors import NamedEntityExtractor
extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER")
After:
from haystack_integrations.components.extractors.transformers import TransformersNamedEntityExtractor
extractor = TransformersNamedEntityExtractor(model="dslim/bert-base-NER")
For the spaCy backend, install spacy-haystack and update your imports:
Before:
from haystack.components.extractors import NamedEntityExtractor
extractor = NamedEntityExtractor(backend="spacy", model="en_core_web_trf")
After:
from haystack_integrations.components.extractors.spacy import SpacyNamedEntityExtractor
extractor = SpacyNamedEntityExtractor(model="en_core_web_trf")
The OpenAPIConnector, OpenAPIServiceConnector and OpenAPIServiceToFunctions components have been removed from Haystack and moved into the dedicated openapi-haystack integration package.
Install the package and update your imports:
Before:
from haystack.components.connectors import OpenAPIConnector, OpenAPIServiceConnector
from haystack.components.converters import OpenAPIServiceToFunctions
After:
from haystack_integrations.components.connectors.openapi import OpenAPIConnector, OpenAPIServiceConnector
from haystack_integrations.components.converters.openapi import OpenAPIServiceToFunctions
These components are a legacy way to connect Haystack to external APIs. For most use cases, consider using the MCPTool instead, which is the modern, standardized way to give pipelines and agents access to external tools and services.
The OpenTelemetryTracer has been moved out of Haystack into the opentelemetry-haystack integration package, and the opentelemetry-sdk dependency is no longer installed with Haystack. OpenTelemetry tracing is no longer auto-enabled when opentelemetry-sdk is installed; instead, use the new OpenTelemetryConnector component to enable OpenTelemetry tracing in your pipeline. Install the new package with pip install opentelemetry-haystack.
Before:
from opentelemetry import trace
from haystack import tracing
from haystack.tracing import OpenTelemetryTracer
tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer("my_application")))
After:
from opentelemetry import trace
from haystack import tracing
from haystack_integrations.tracing.opentelemetry import OpenTelemetryTracer
tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer("my_application")))
Alternatively, add the OpenTelemetryConnector to your pipeline to enable tracing:
from haystack import Pipeline
from haystack_integrations.components.connectors.opentelemetry import OpenTelemetryConnector
pipe = Pipeline()
pipe.add_component("tracer", OpenTelemetryConnector())
Breaking change: haystack.tracing.auto_enable_tracing has been removed (and is no longer called on import haystack). Since Haystack no longer ships a built-in tracing backend, there is nothing to auto-enable. Enable tracing explicitly instead, for example by adding the OpenTelemetryConnector component to your pipeline, or by calling haystack.tracing.enable_tracing(...) with your tracer. The HAYSTACK_AUTO_TRACE_ENABLED environment variable no longer has any effect.
SearchApiWebSearch has been moved out of Haystack into the searchapi-haystack integration package. Install the new package with pip install searchapi-haystack and update your imports.
Before:
from haystack.components.websearch import SearchApiWebSearch
After:
from haystack_integrations.components.websearch.searchapi import SearchApiWebSearch
The Sentence Transformers components have been moved out of Haystack into the sentence-transformers-haystack integration package. This includes SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder, SentenceTransformersSparseTextEmbedder, SentenceTransformersSparseDocumentEmbedder, SentenceTransformersDocumentImageEmbedder, SentenceTransformersSimilarityRanker, and SentenceTransformersDiversityRanker. Install the new package with pip install sentence-transformers-haystack and update your imports.
Before:
from haystack.components.embedders import (
SentenceTransformersTextEmbedder,
SentenceTransformersDocumentEmbedder,
SentenceTransformersSparseTextEmbedder,
SentenceTransformersSparseDocumentEmbedder,
)
from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder
from haystack.components.rankers import SentenceTransformersSimilarityRanker, SentenceTransformersDiversityRanker
After:
from haystack_integrations.components.embedders.sentence_transformers import (
SentenceTransformersTextEmbedder,
SentenceTransformersDocumentEmbedder,
SentenceTransformersSparseTextEmbedder,
SentenceTransformersSparseDocumentEmbedder,
SentenceTransformersDocumentImageEmbedder,
)
from haystack_integrations.components.rankers.sentence_transformers import (
SentenceTransformersSimilarityRanker,
SentenceTransformersDiversityRanker,
)
Removed the unused serialize_class_instance and deserialize_class_instance functions from haystack.utils.base_serialization. These were internal helpers not used anywhere in Haystack. If you were importing them directly, inline their logic: use {"type": generate_qualified_class_name(type(obj)), "data": obj.to_dict()} to serialize, and obj_class.from_dict(data["data"]) (after resolving obj_class with import_class_by_name(data["type"])) to deserialize.
SerperDevWebSearch has been moved out of Haystack into the serperdev-haystack integration package. Install the new package with pip install serperdev-haystack and update your imports.
Before:
from haystack.components.websearch import SerperDevWebSearch
After:
from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
TikaDocumentConverter has been moved out of Haystack into the tika-haystack integration package. Install the new package with pip install tika-haystack and update your imports.
Before:
from haystack.components.converters import TikaDocumentConverter
After:
from haystack_integrations.components.converters.tika import TikaDocumentConverter
Removed the ToolInvoker component. Code that imports ToolInvoker from haystack.components.tools or uses it as a standalone Pipeline component must be updated.
To execute tools in an agentic loop, pass the tools directly to haystack.components.agents.Agent. The Agent now owns tool execution, including tool/toolset warm-up, state injection, streaming callback passthrough, and sync/async tool invocation. The previous tool_invoker_kwargs Agent parameter has been removed; use tool_concurrency_limit and tool_streaming_callback_passthrough instead.
Tool results are now always serialized to a string using json.dumps (with ensure_ascii=False, falling back to str only when the result is not JSON-serializable). The ToolInvoker's convert_result_to_json_string parameter, which defaulted to False and selected str-based serialization, has been removed along with the component. As a result, non-string tool results now appear as JSON rather than Python repr output: for example, a tool returning {"message": "hi"} now produces the string {"message": "hi"} instead of {'message': 'hi'}. Update any code or tests that assert on the previous str-based format.
HuggingFaceLocalChatGenerator, ExtractiveReader, TransformersZeroShotDocumentClassifier, TransformersTextRouter, and TransformersZeroShotTextRouter have been moved out of Haystack into the transformers-haystack integration package. Install the new package with pip install transformers-haystack and update your imports.
Before:
from haystack.components.classifiers import TransformersZeroShotDocumentClassifier
from haystack.components.generators.chat import HuggingFaceLocalChatGenerator
from haystack.components.readers import ExtractiveReader
from haystack.components.routers import TransformersTextRouter, TransformersZeroShotTextRouter
After:
from haystack_integrations.components.classifiers.transformers import TransformersZeroShotDocumentClassifier
from haystack_integrations.components.generators.transformers import TransformersChatGenerator
from haystack_integrations.components.readers.transformers import TransformersExtractiveReader
from haystack_integrations.components.routers.transformers import (
TransformersTextRouter,
TransformersZeroShotTextRouter,
)
The legacy TransformersSimilarityRanker component has been removed. Use SentenceTransformersSimilarityRanker instead, which provides the same functionality along with async support.
Before:
from haystack.components.rankers import TransformersSimilarityRanker
ranker = TransformersSimilarityRanker(model="cross-encoder/ms-marco-MiniLM-L-6-v2")
After:
from haystack.components.rankers import SentenceTransformersSimilarityRanker
ranker = SentenceTransformersSimilarityRanker(model="cross-encoder/ms-marco-MiniLM-L-6-v2")
The user_prompt and system_prompt parameters have been removed from Agent.run / Agent.run_async and LLM.run / LLM.run_async. Both prompts must now be set at initialization time on the component; they can no longer be overridden per-run, including when the component is used inside a pipeline (Pipeline.run(data={"agent": {"user_prompt": ...}}) or Pipeline.run(data={"llm": {"user_prompt": ...}}) is no longer supported).
system_prompt and user_prompt both accept either a plain string template or an explicit Jinja2 message template. Plain string templates are rendered as a single message with the expected role (system for system_prompt, user for user_prompt). Explicit Jinja2 message templates must contain a single message block and render to exactly one message with the matching role.
Before:
agent = Agent(chat_generator=..., tools=[...], system_prompt="Default system prompt.")
agent.run(messages=[...], system_prompt="Per-run override.")
After:
# Construct a new Agent or LLM with the desired prompt.
agent = Agent(chat_generator=..., tools=[...], system_prompt="Default system prompt.")
agent.run(messages=[...])
# If you need to build prompts at runtime, construct an Agent without
# init prompts and pass the prompt messages through the messages input.
agent = Agent(chat_generator=..., tools=[...])
agent.run(messages=[ChatMessage.from_system("Runtime system prompt."), ChatMessage.from_user("...")])
LocalWhisperTranscriber and RemoteWhisperTranscriber have been moved out of Haystack into the whisper-haystack integration package. Install the new package with pip install whisper-haystack and update your imports.
Before:
from haystack.components.audio import LocalWhisperTranscriber
from haystack.components.audio import RemoteWhisperTranscriber
After:
from haystack_integrations.components.audio.whisper import LocalWhisperTranscriber
from haystack_integrations.components.audio.whisper import RemoteWhisperTranscriber
LocalWhisperTranscriber additionally requires the openai-whisper package (and ffmpeg), which you can install with pip install "openai-whisper>=20231106".
Tools now read a value from the Agent's State by name only when they declare an explicit inputs_from_state mapping. Previously, when a tool had no inputs_from_state, the Agent would implicitly inject a State value into any tool parameter whose name happened to match a State key, on any call where the model did not already supply that argument (LLM-provided arguments always took precedence). This implicit name-matching has been removed. The change applies to every tool type, since ComponentTool, PipelineTool, MCPTool, and others all derive from the base Tool class.
This is a breaking change. If you relied on a tool parameter being filled from a same-named State key, add an explicit mapping, for example inputs_from_state={"documents": "documents"} to feed the documents state key into the tool's documents parameter.
Auto-injection of the full State object into a parameter annotated as State is unchanged and continues to work without any mapping.
The raise_on_invalid_filter_syntax utility function has been removed. Its implementation was incorrect and never used across Haystack and Haystack Core Integrations.
haystack.logging.configure_logging now attaches its formatting handler to Haystack's own logger namespaces (haystack, haystack_integrations and haystack_experimental) instead of the root logger. This makes Haystack a better-behaved library when it runs next to other services in the same process: the log records of the host application and other libraries are no longer reformatted or duplicated by Haystack. To restore the previous behavior of formatting every log record in the process, call configure_logging(logger_name="").
Importing Haystack no longer configures structlog process-wide. The import-time setup now only installs Haystack's own scoped logging handler (so Haystack's logs are still formatted) and leaves the global structlog configuration untouched, so the host application's own native structlog loggers are no longer reformatted by merely importing Haystack. structlog is configured only when you call configure_logging(configure_structlog=True).
The Agent component now emits a different shape of tracing spans. Previously each iteration of the agent loop produced two child spans via Pipeline._run_component — one for the chat generator and one for the tool invoker — each carrying haystack.component.name and haystack.component.type tags. The agent now opens a single haystack.agent.step span per loop iteration with two nested children: haystack.agent.step.llm (the chat generator call) and haystack.agent.step.tool (the tool invocation, only emitted when tool calls happen). These new spans do NOT carry haystack.component.* tags; instead they expose new content tags haystack.agent.step.llm.input/.output and haystack.agent.step.tool.input/.output.
Custom tracer backends or SpanHandler implementations that dispatched on component_type == "ToolInvoker" or component_type.endswith("ChatGenerator") for Agent-internal spans will need to be updated to dispatch on the new operation names (haystack.agent.step.llm / haystack.agent.step.tool) instead. The Langfuse integration's DefaultSpanHandler is affected — see MIGRATION.md for a concrete example of a custom SpanHandler that maps the new operations to Langfuse chain / generation / tool observations.
Added an after_tool hook point to the Agent. Hooks registered under after_tool run after tools execute, once their result messages are in state.data["messages"], and before the exit check and the next LLM call. Use it to rewrite the freshly produced tool-result messages, for example to offload, redact, truncate, or summarize results before the next LLM call sees them. It does not run on the plain-text exit step, where no tools run. Register it like any other hook: hooks={"after_tool": [my_hook]}.
Added hooks to the Agent. Pass hooks as a dictionary mapping a hook point to a list of hooks the Agent runs at that point. Each hook receives the live State and influences the run by mutating it in place; hooks for a hook point run in list order, and the same hook can be registered under multiple hook points. Valid hook points are:
before_llm: Runs before each chat-generator call.before_tool: Runs after the model requests tool calls, before any tools run. After these hooks run, the Agent re-reads the current last message from state["messages"]. If that message contains tool calls, those calls are executed. If it does not, no tools run for that step, no tool-based exit condition is triggered, and the Agent loops back to the next LLM call unless max_agent_steps has been reached.on_exit: Runs when the Agent is about to stop on an exit condition. An on_exit hook can keep the Agent running by setting the continue_run control flag (state.set("continue_run", True)), usually alongside a message telling the model what to do next. on_exit hooks run when the Agent stops on an exit condition, but not when it stops because max_agent_steps is reached.A hook is any object with a run(state) method (optionally run_async(state)); use the @hook decorator to build one from a function. This enables patterns such as building run-time system context, retrieving memories, and requiring a tool to be called before finishing.
The example below registers one hook at each placement to show what each can do:
from datetime import datetime, timezone
from typing import Annotated
from haystack.components.agents import Agent
from haystack.components.agents.state import State, replace_values
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.hooks import hook
from haystack.tools import tool
@tool
def search(query: Annotated[str, "The search query"]) -> str:
"""Search the web."""
# Placeholder: would call a real search API
return "Fusion startups reported net-energy-gain milestones this year."
@hook
def build_context(state: State) -> None:
# before_llm: build run-time system context once, before the first model call.
if state.get("step_count") == 0:
now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
system = ChatMessage.from_system(f"You are a research assistant. The current time is {now}.")
state.set("messages", [system, *state.data["messages"]], handler_override=replace_values)
@hook
def audit_tool_calls(state: State) -> None:
# before_tool: see which tools the model is about to run.
pending = state.data["messages"][-1].tool_calls
print(f"about to run: {[tc.tool_name for tc in pending]}")
@hook
def require_search(state: State) -> None:
# on_exit: keep going until the agent has actually searched.
if state.get("tool_call_counts", {}).get("search", 0) == 0:
state.set("messages", [ChatMessage.from_system("Search before answering.")])
state.set("continue_run", True)
agent = Agent(
chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
tools=[search],
hooks={
"before_llm": [build_context],
"before_tool": [audit_tool_calls],
"on_exit": [require_search],
},
)
result = agent.run(messages=[ChatMessage.from_user("What are the latest developments in fusion energy?")])
print(result["last_message"].text)
Class-based hooks may also implement the optional lifecycle methods warm_up / warm_up_async and close / close_async. The Agent calls them from its own warm_up / warm_up_async and close / close_async, so a hook can defer opening clients or reading credentials until warm-up and release them on close. When a class-based hook should be serializable, store serializable constructor arguments on the hook and rebuild runtime clients from those values. For example, an on_exit hook can grade the Agent's answer with its own LLM and ask it to improve a weak answer before finishing, warming the judge's client during the Agent's warm-up:
from typing import Any
from haystack.core.serialization import default_from_dict, default_to_dict
class GradeFinalAnswer:
"""Grade the Agent's answer with an LLM and ask it to improve a weak answer before finishing."""
def __init__(self, model: str = "gpt-5.4-nano"):
self.model = model
self._judge = OpenAIChatGenerator(model=self.model)
def warm_up(self) -> None:
# Warm up the judge's own client during the Agent's warm-up.
self._judge.warm_up()
def run(self, state: State) -> None:
answer = state.data["messages"][-1].text or ""
verdict = self._judge.run(
messages=[ChatMessage.from_user(f"Reply with only PASS or FAIL. Is this answer complete?\n\n{answer}")]
)["replies"][0].text or ""
if "FAIL" in verdict.upper():
state.set("messages", [ChatMessage.from_user("Your answer was incomplete. Please improve it.")])
state.set("continue_run", True)
def to_dict(self) -> dict[str, Any]:
return default_to_dict(self, model=self.model)
@classmethod
def from_dict(cls, data: dict[str, Any]) -> "GradeFinalAnswer":
return default_from_dict(cls, data)
agent = Agent(chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"), hooks={"on_exit": [GradeFinalAnswer()]})
result = agent.run(messages=[ChatMessage.from_user("Explain how vaccines work.")])
print(result["last_message"].text)
Add native async tool invocation. Tool now accepts an optional async_function (a coroutine function) alongside the existing function field. When Agent.run_async invokes a tool, it now awaits the async_function of Tool if available.
@tool / create_tool_from_function automatically routes async def callables to async_function, so simply decorating an async def produces an async tool:
from typing import Annotated
from haystack.tools import tool
@tool
async def weather(city: Annotated[str, "The name of the city"]) -> str:
"""Get the weather for a city."""
...
ComponentTool automatically wires an async invoker for components that define run_async (__haystack_supports_async__ is True). PipelineTool enables the async path when wrapping an AsyncPipeline and falls back to the threaded sync path when wrapping a regular Pipeline.
Added before_run and after_run hook points to the Agent. Hooks registered under before_run run exactly once per run, after the state is initialized and before the first LLM call — use them to rewrite the initial messages or seed state without re-running on every step like before_llm does. Hooks registered under after_run run exactly once per run, after the step loop has ended and before the Agent builds its return value, regardless of whether the run stopped on an exit condition or because max_agent_steps was reached (unlike on_exit); mutations to the state are reflected in the returned messages, last_message, and state_schema outputs. Register them like any other hook: hooks={"before_run": [my_hook], "after_run": [my_other_hook]}.
Added a new {% insert %} tag to the Jinja2 string templates used by ChatPromptBuilder. The tag is a placeholder that evaluates an expression to a ChatMessage or a list of ChatMessage objects and expands it into the prompt, so messages provided at runtime can be interleaved with literal {% message %} blocks. For example, you can wrap the runtime messages with a system message above and a templated user message below, then pass the messages (and any template variables) at run time:
from haystack.components.builders import ChatPromptBuilder
from haystack.dataclasses import ChatMessage
template = """
{% message role="system" %}You are a helpful assistant.{% endmessage %}
{% insert messages %}
{% message role="user" %}{{ query }}{% endmessage %}
"""
builder = ChatPromptBuilder(template=template)
result = builder.run(
messages=[ChatMessage.from_user("Hi"), ChatMessage.from_assistant("Hello!")],
query="What's the weather?",
)
# result["prompt"] -> [system, user "Hi", assistant "Hello!", user "What's the weather?"]
All content types (tool calls, tool call results, images, reasoning, name and meta) round trip without loss. A missing or empty value expands to nothing.
The expression can be a plain variable ({% insert messages %}), a slice or index ({% insert messages[-1:] %}, {% insert messages[-1] %}), or a combination of variables ({% insert previous + current %}). Multiple {% insert %} tags can be used in a single template, so the runtime messages can be split, reordered, or repeated across different positions.
Added MockChatGenerator, a Chat Generator that returns predefined responses without calling any API. It is a deterministic, zero-cost drop-in replacement for real Chat Generators in tests, smoke tests, and quick prototypes. It supports a fixed response, a list of responses cycled across calls (useful to drive Agent-like loops), a response_fn callable for input-dependent replies, and an echo mode (the default) that returns the last user message. It implements the full Chat Generator interface, including run, run_async, streaming callbacks, and serialization.
Added MockTextEmbedder and MockDocumentEmbedder, embedders that return deterministic embeddings without calling any API. They are zero-cost drop-in replacements for real embedders in tests, smoke tests, and quick prototypes. By default each embedding is derived from a stable hash of the (prepared) text, so the same text always yields the same unit-length embedding and different texts yield different embeddings, making the mocks usable in retrieval pipelines and reproducible across runs and processes. A fixed embedding vector or a custom embedding_fn callable can be provided instead. Both implement the full embedder interface, including run, run_async, and serialization.
Added a reasoning_mode flattened generation kwarg to OpenAIResponsesChatGenerator, which is merged into the reasoning dictionary sent to the OpenAI Responses API. This lets you set the reasoning mode (for example standard or pro, supported since GPT-5.6) without having to construct the nested reasoning dict yourself.
Added an include_reasoning_encrypted_content flattened generation kwarg to OpenAIResponsesChatGenerator. Setting it to True appends reasoning.encrypted_content to the include list sent to the OpenAI Responses API, so reasoning items can be reused across multi-turn conversations when the Responses API is used statelessly (for example when store is False or zero data retention is enabled).
Added a run_async method to LLMRanker, QueryExpander, LLMMessagesRouter and LLMDocumentContentExtractor so they can run natively in an AsyncPipeline. The method delegates to the chat generator's run_async method when available. If the chat generator only implements a synchronous run method, it is executed in a thread to avoid blocking the event loop. LLMDocumentContentExtractor processes documents concurrently with asyncio, bounded by max_workers.
Added a run_async method to RemoteWhisperTranscriber and OpenAIImageGenerator so they can run natively in an AsyncPipeline. Both components now hold an AsyncOpenAI client alongside the existing synchronous client and call the OpenAI API without blocking the event loop.
Added SkillToolset, a Toolset that lets an Agent discover and read "skills" through progressive disclosure, similar to how Claude Code and Codex expose skills. A skill is a directory containing a SKILL.md file with YAML frontmatter (name and description) and a markdown body of instructions, optionally bundling additional reference files. SkillToolset is backed by a SkillStore; use FileSystemSkillStore to load skills from a local directory and add the toolset to an Agent:
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.tools import SkillToolset
from haystack.skill_stores.file_system import FileSystemSkillStore
skills_toolset = SkillToolset(FileSystemSkillStore("skills/"))
agent = Agent(chat_generator=OpenAIChatGenerator(), tools=skills_toolset)
Skills are discovered when the toolset is warmed up (the Agent does this automatically before a run). The names and descriptions of all discovered skills are baked into the load_skill tool description, so the model can see which skills exist without any system prompt injection. The toolset exposes two tools: load_skill returns a skill's full instructions on demand, and read_skill_file reads a file bundled with a skill (with path-traversal protection). read_skill_file returns text files as strings, images as ImageContent, and PDFs as FileContent, so an Agent backed by a multimodal chat generator can read a skill's visual assets — for example a reference screenshot or a showcase PDF — directly.
Custom stores can back SkillToolset with any storage system (a database, a remote API, ...) by implementing the SkillStore protocol.
Added tool result offloading for the Agent via the new haystack.hooks.tool_result_offloading module. ToolResultOffloadHook is an after_tool hook that writes selected tool results to a store and replaces them in the conversation with a compact pointer (a reference plus a short preview). The next LLM call sees the reference instead of the full result, which helps manage the context window and is a step towards letting an Agent operate on offloaded results with follow-up tools (e.g. a bash tool that reads the referenced files).
Configure what gets offloaded, per tool, via offload_strategies:
"*" to an OffloadPolicy. More specific keys win over "*"; a tool with no matching key is not offloaded.AlwaysOffload, NeverOffload, and OffloadOverChars (offload when the result exceeds a character threshold).OffloadPolicy protocol (it provides default to_dict/from_dict, so a stateless policy only needs a should_offload method).Choose where results are stored:
FileSystemToolResultStore writes results to the local file system.ToolResultStore protocol to target other backends.hook_context (hook_context={RESULT_STORE_CONTEXT_KEY: per_request_store}) so concurrent users write to separate locations and never read each other's results.What is offloaded:
before_tool human-in-the-loop rejections) are left in context.from typing import Annotated
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.hooks.tool_result_offloading import (
FileSystemToolResultStore,
OffloadOverChars,
ToolResultOffloadHook,
)
from haystack.tools import tool
@tool
def search(query: Annotated[str, "The search query"]) -> str:
"""Search the web and return the (potentially large) results."""
return f"... large result for {query} ..."
offload_hook = ToolResultOffloadHook(
store=FileSystemToolResultStore(root="tool_results"),
offload_strategies={"*": OffloadOverChars(4000)},
)
agent = Agent(
chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
tools=[search],
hooks={"after_tool": [offload_hook]},
)
agent.run(messages=[ChatMessage.from_user("Summarize today's tech news")])
Added AsyncPipeline.stream(), a convenient way to stream LLM chunks from an async application, such as an API endpoint. It runs the pipeline and returns a handle that can be iterated with async for to receive StreamingChunk objects from streaming-capable components as they are produced. After iteration ends, handle.result holds the final pipeline output (the same dict returned by run_async). By default every streaming-capable component is forwarded; pass streaming_components to stream only specific components. If the consumer abandons iteration, the underlying pipeline run is cancelled automatically; pass cancel_on_abandon=False to let it run to completion.
import asyncio
from haystack import AsyncPipeline
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
pipe = AsyncPipeline()
pipe.add_component(
"prompt_builder",
ChatPromptBuilder(template=[ChatMessage.from_user("Tell me about {{topic}}")]),
)
pipe.add_component("llm", OpenAIChatGenerator())
pipe.connect("prompt_builder.prompt", "llm.messages")
async def main():
handle = pipe.stream(data={"prompt_builder": {"topic": "Italy"}})
async for chunk in handle:
print(chunk.content, end="", flush=True)
return handle.result
result = asyncio.run(main())
Components and pipelines now have a consistent resource lifecycle for acquiring and releasing resources such as HTTP clients and connections. In addition to the existing warm_up, components can now implement warm_up_async to acquire asynchronous resources, and close/close_async to release them. Pipeline now implements the same lifecycle methods. In addition to the existing warm_up, warm_up_async() runs async warm-up on the serving event loop (falling back to the synchronous warm_up), while close()/close_async() release synchronous and asynchronous resources respectively. Closing is always explicit; pipelines are never closed automatically after a run.
Added a shared parameter to InMemoryDocumentStore. When True (the default, matching previous behavior), documents live in process-global storage shared across instances that use the same index. When False, documents are kept instance-local and freed when the instance is garbage collected. Use shared=False for stores that are created frequently (for example, one per request in a served application) to avoid unbounded growth of the process-global storage.
Pipeline.load / Pipeline.loads / Pipeline.from_dict now accept two new keyword arguments:
allowed_modules: list[str] | None — additional module patterns that may be imported during this deserialization call. Patterns are matched as prefixes ("mypkg" matches mypkg and any submodule) or, if they contain */?/[, using fnmatch rules.unsafe: bool = False — when set to True, the deserialization allowlist is bypassed entirely. Only use this when you fully trust the source of the serialized data.A new public helper, haystack.core.serialization.allow_deserialization_module(pattern), extends the process-wide allowlist. The HAYSTACK_DESERIALIZATION_ALLOWLIST environment variable (comma-separated patterns) is read at runtime on every deserialization call.
Added ConfirmationHook, a before_tool Agent hook that applies Human-in-the-Loop confirmation strategies to pending tool calls. It confirms, modifies, or rejects the tool calls the model requested before they run by rewriting the conversation in the Agent's State. Its confirmation_strategies mapping accepts a single tool name, a tuple of tool names, or the wildcard "*" that applies to any tool without a more specific entry, so you can set a default strategy for all tools and override individual ones.
Agent hooks may now declare an allowed_hook_points attribute listing the hook points they support. The Agent validates it at construction and raises a ValueError if such a hook is registered under an unsupported hook point. For example, ConfirmationHook sets allowed_hook_points = ("before_tool",), so registering it under before_llm or on_exit now fails fast instead of silently doing nothing. Hooks that do not declare the attribute can still be registered under any hook point.
haystack.logging.configure_logging gained three parameters: logger_name to choose which logger(s) the formatting handler is attached to, propagate to control whether Haystack's loggers propagate their records to ancestor loggers, and configure_structlog to control whether the call configures the process-global structlog (taking over any existing configuration). Set propagate=False to let Haystack fully own the output of its own logs and avoid duplicate log lines when the host application also configures the root logger.
Adds a status field to each result produced by ContextRelevanceEvaluator and FaithfulnessEvaluator. The field is evaluated for valid results and error for generation or parsing failures continued with raise_on_failure=False.
Components that delegate to sub-components in their run_async method (LLMMetadataExtractor, EmbeddingBasedDocumentSplitter, FallbackChatGenerator, TextEmbeddingRetriever, MultiRetriever, MultiQueryTextRetriever and MultiQueryEmbeddingRetriever) now use a shared utility to run the sub-component. If the sub-component only implements a synchronous run method, it is executed in a thread to avoid blocking the event loop. Notably, LLMMetadataExtractor and EmbeddingBasedDocumentSplitter previously fell back to their fully synchronous run method in this case, which blocked the event loop for the duration of the call.
Duplicate tool names are now detected at the start of each Agent step (before the chat generator call) instead of only at tool execution, so the error surfaces earlier and the LLM is never sent duplicate tool schemas.
Pipeline.run now accepts break_point and pipeline_snapshot at the same time. This enables a stepped debugging experience: run until a breakpoint, then resume from the resulting snapshot with a new breakpoint on the next component, pausing again for inspection at each step. The only rejected combination is a break_point targeting the same component and visit count as the snapshot's break point, since it would trigger again before the resumed component runs and the pipeline could not make any progress.
ChatMessage.from_dict now also accepts the format Pydantic produces when it auto-serializes ChatMessage as a plain dataclass (e.g. via model_dump on a Pydantic model with ChatMessage fields). In this format, content parts appear without their wrapping key (for example {"tool_name": "search", "arguments": {}} instead of {"tool_call": {"tool_name": "search", "arguments": {}}}) and are identified by their required field names. This makes it possible to round-trip ChatMessage objects that were implicitly serialized as part of larger Pydantic models.
Removed duplicated class-import logic between core/serialization.py and utils/type_serialization.py, including the deserialization-allowlist and builtin-type-safety checks, by sharing a single internal implementation. No change to public behavior or to the security checks themselves.
Agent now exposes three new outputs that are populated automatically during a run and made available alongside messages and last_message in the result dict:
step_count (int): the number of steps the agent ran.token_usage (dict[str, Any]): aggregated token usage summed across every LLM call in the runtool_call_counts (dict[str, int]): number of times each tool was invoked, keyed by tool name.These fields are added to Agent.state_schema automatically so that tools registered via inputs_from_state can read them mid-run. They are exposed only as Agent outputs so cannot be passed in as inputs to Agent.run / Agent.run_async.
LLM now exposes a token_usage output alongside messages and last_message. Because LLM never invokes tools and always runs exactly one step, step_count and tool_call_counts inherited from Agent are not exposed on LLM.
The haystack.tools package now imports its heavier modules lazily. Importing the package no longer eagerly pulls in ComponentTool, PipelineTool, and SearchableToolset (and their transitive dependencies such as Pipeline and InMemoryDocumentStore); these are resolved on first access instead. This reduces import time when those tools are not used. All public names remain importable from haystack.tools exactly as before.
The Agent now emits one haystack.agent.step.tool tracing span per tool call instead of a single span grouping every tool call in a step. Each span carries the tool's name and description as tags, plus the call arguments and result when content tracing is enabled. This matches the OpenTelemetry and Langfuse convention of a single tool call per span, so traces render one observation per tool invocation.
LoggingTracer now serializes the log records it emits when a span closes, so a span's operation name and its tags stay contiguous even when spans are opened and closed from parallel threads (for example, the Agent running tool calls concurrently).
Streaming-capable components (OpenAIChatGenerator, OpenAIResponsesGenerator, HuggingFaceAPIChatGenerator, HuggingFaceLocalChatGenerator, Agent) now accept a synchronous streaming callback in asynchronous contexts (run_async). A warning is logged because the callback runs synchronously on the event loop and may block it, but the run proceeds. Async callbacks are still preferred for performance.
import asyncio
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage, StreamingChunk
def print_chunk(chunk: StreamingChunk) -> None:
print(chunk.content, end="", flush=True)
async def main():
llm = OpenAIChatGenerator()
# previously this raised; now it logs a warning and streams as expected
await llm.run_async(
[ChatMessage.from_user("Tell me about Italy")],
streaming_callback=print_chunk,
)
asyncio.run(main())
Simplified the pipeline scheduler by removing the DEFER_LAST component priority. Components that previously got DEFER_LAST (those with unresolved lazy-variadic sockets) now share the DEFER priority and are tie-broken via topological order, matching the behavior of all other deferred components. This should not materially change how components are scheduled in a pipeline.
ToolCallResult can now carry FileContent parts, in addition to TextContent and ImageContent. A Tool can return a file (such as a PDF) as its result so a multimodal chat generator that supports file inputs (for example OpenAIResponsesChatGenerator) passes it straight to the model. Combine this with a tool's outputs_to_string={"raw_result": True} to keep the content parts intact instead of converting them to a string.
Toolset gained two methods: get_selectable_tools() returns every tool available for name-based selection (ignoring any active selection restriction, e.g. the one used by SearchableToolset), and spawn() returns an isolated, run-scoped copy of the Toolset. Subclasses with additional run-scoped state can override spawn().
SearchableToolset now exposes its full catalog of tools via SearchableToolset.get_selectable_tools().
Toolset.warm_up() is now idempotent: warming up a toolset more than once no longer re-warms its tools. Calling Toolset.add() after the toolset has been warmed up now warms up the newly added tool (or toolset) immediately, so it is ready to use without an extra warm_up() call.
Removed the use of Pipeline._run_component inside Agent.run and Agent.run_async. The chat generator and tool invoker are now invoked directly via their run / run_async methods, decoupling the Agent from the Pipeline internals.
Pipeline.load / Pipeline.loads / Pipeline.from_dict). The module allowlist was enforced against a string prefix of the serialized handle, while the callable/class resolvers walked attributes from the deepest importable module. Because an allowlisted package can expose another module as an attribute (e.g. a module-scope import os makes haystack.utils.auth.os the standard-library os module), a handle such as haystack.utils.auth.os.system passed the allowlist and resolved to os.system. The allowlist is now enforced against the module each object is actually resolved from — every module hop during attribute resolution is re-checked, and the resolved callable's/class's real module must be on the allowlist. Legitimate handles (including harmless builtins such as builtins.print) continue to resolve.Pipeline.from_dict. Deserialization is now gated by an allowlist of trusted module namespaces (see the upgrade note for how to extend it). In addition, default_from_dict now refuses to recurse into nested {"type": "..."} dictionaries keyed by parameter names that the parent class does not actually accept — blocking attempts to smuggle untrusted classes into unused parameter slots.eval, exec, compile, __import__, open, and getattr can no longer be resolved during deserialization, even though builtins is on the default allowlist. Attempting to deserialize one as a callable, a type annotation, or a nested {"type": ...} class reference raises a DeserializationError. The block can be bypassed with unsafe=True when the source of the serialized data is fully trusted.Agent now correctly executes tools supplied only at runtime via run(tools=...) / run_async(tools=...) when no tools were provided at initialization. Previously the run stopped after the first LLM call because the step guard checked the init-time tools instead of the tools resolved for the run.
Initializing an Agent no longer warms up a SearchableToolset. Previously construction could iterate the tools, and SearchableToolset warms itself up when iterated, so it was warmed up too early. Its warm-up now happens only via Agent.warm_up() or at run time.
The haystack.agent.run tracing span's haystack.agent.tools tag now reflects the tools actually used for the run. Previously it always reported the init-time tools, so it was inconsistent with the run when tools were overridden at runtime via run(tools=...) / run_async(tools=...).
Fixed a bug in Agent (and the underlying tool invocation) where parallel tool calls in a single step did not respect read/write dependencies on State. Tool arguments were prepared once, up front, from the initial state, so a tool reading a State key via inputs_from_state never observed a write made by another tool in the same step via outputs_to_state. For example, two calls to a retrieval tool that both reads and writes the documents key would each see the original documents instead of the second call seeing the first call's results.
Tool calls within a step are now scheduled into batches based on their inputs_from_state and outputs_to_state mappings. Calls that only read, or that touch disjoint keys, still run in parallel; a call that reads a key another call writes is run in a later batch, after that write has been merged into State, with its arguments re-prepared so it sees the updated value. Tools that receive the live State object are treated as reading and writing every key and run on their own. The order the LLM requested the calls in no longer affects correctness.
AnswerBuilder now treats a [0] document reference as out of range instead of silently attaching the last document. References are 1-based, so [0] produced a negative index that bypassed the out-of-range guard, marking an unrelated document as referenced with a wrong source_index. The same applied to expanded reference ranges starting at 0 (e.g. [0-1]).
Fixed a task leak in AsyncPipeline when running components concurrently. Previously, if one component raised an error while sibling components were still running, those in-flight tasks were neither awaited nor cancelled and kept running in the background until the event loop was torn down. They are now cancelled and drained before the original error is re-raised. The same cleanup now also applies when iteration of run_async_generator is stopped early (e.g. the consumer breaks out of the loop and closes the generator) or the run is cancelled: any tasks still in flight are cancelled instead of leaking. Note that cancellation only interrupts components that run natively async. Sync components are offloaded to a worker thread, which cannot be interrupted and runs to completion in the background; its outputs are discarded, so pipeline state stays consistent, but the component's side effects still complete.
ComponentTool no longer adds a top-level description key to the generated parameters JSON schema. The wrapped component's docstring was emitted inside the parameters schema, where LLM providers (OpenAI, Anthropic, Google) do not use it, and for tools wrapping a SuperComponent it produced a confusing auto-generated summary. The parameters schema now only carries per-parameter descriptions, matching plain Tool and function-based tools. The tool-level description is unchanged.
Fixed CSVToDocument in conversion_mode="row" crashing the entire batch when a CSV row has more fields than the header (ragged rows, e.g. an unquoted comma inside a value). Surplus values are now stored under an explicit extra_columns metadata key instead of the None key, which previously broke Document id generation and discarded results from all sources.
Declare the meta output of LLMEvaluator, ContextRelevanceEvaluator, and FaithfulnessEvaluator, and the individual_scores output of ContextRelevanceEvaluator. These outputs were already returned but not declared, so they could not be connected to other components in a Pipeline.
Fixed DocumentRecallEvaluator returning wrong scores when the configured document_comparison_field is missing or empty on some documents. Those documents were considered a match for each other, so unrelated documents could count as correctly retrieved. They are now ignored when computing the score.
Improved the validation and compatibility layer of Document:
embedding is a list of floats, while it was a NumPy array in 1.x, so a NumPy embedding is converted to a list for backward compatibility. The conversion only happened when embedding was passed as a keyword argument: passed positionally, the array was silently left as is, potentially causing downstream issues.content type was validated only when passed as a keyword argument.content type validation was also skipped when the value was falsy, such as 0 or [], and failed later with an unrelated error.Fix FilterPolicy.MERGE in InMemoryBM25Retriever and InMemoryEmbeddingRetriever so initialization filters are combined with runtime comparison filters instead of being silently overwritten.
Fixed a TypeError raised when filtering documents with the ordering operators (>, >=, <, <=) where both the filter value and the document meta value are datetime objects but one is timezone-aware and the other is naive. The naive/aware reconciliation is now applied to any pair of datetime operands, matching the behavior already used for ISO 8601 string dates.
Fixed GeneratedAnswer.from_dict and ExtractedAnswer.from_dict mutating their input dictionary in place. They replaced nested values (documents, document, offsets and meta["all_messages"]) directly inside the passed dictionary, so deserializing the same dictionary a second time received already-parsed objects and raised an AttributeError. Both methods now copy their input before deserializing and are side-effect free.
Fixed component_to_dict serialization validation not detecting non-string keys in nested dictionaries. The check only inspected the top-level dictionary, so a non-string key inside a nested init_parameters value passed validation and could later fail during marshalling; nested dictionaries are now validated too.
Fixed CountUniqueMetadataByFilterTest.test_count_unique_metadata_by_filter_with_multiple_filters in the document store testing mixins: it called count_documents_by_filter instead of count_unique_metadata_by_filter. The test now exercises the intended method with a compound filter, matching its async counterpart.
Fixed _deepcopy_with_exceptions crashing when a value is a namedtuple (or any typing.NamedTuple). The list/tuple/set branch rebuilt the container with type(obj)(<generator>), but a namedtuple's __new__ expects its fields as positional arguments rather than a single iterable, so copying a component input or parameter that contained a namedtuple raised a TypeError. Namedtuples are now rebuilt by unpacking their deep-copied fields.
Fixed default_from_dict (and therefore component_from_dict) mutating the caller's data dictionary in place when deserializing nested objects such as Secret or ComponentDevice. The serialized sub-dictionaries were being replaced by their deserialized instances inside the input dict; the input is now left unchanged, so the same data can be safely deserialized more than once.
Fixed deserialize_callable failing for functions decorated with @tool when the decorated function is asynchronous. Such tools store the callable in async_function with function set to None, which previously caused deserialization to raise a DeserializationError. The underlying coroutine function is now resolved correctly.
Fixed DocumentCleaner wiping the middle page of a 3-page document when remove_repeated_substrings=True. Header/footer detection compares the pages between the first and last, which is a single page for a 3-page document; its own longest ngram was then treated as a repeated header/footer and removed. Detection now requires at least two pages to compare, so unique content is preserved while genuine repeated headers/footers are still removed.
Fixed DocumentTypeRouter misrouting documents whose MIME type contains a regex metacharacter. A declared type such as the standard IANA image/svg+xml was compiled as a regex, so the + was treated as a quantifier and the document fell into unclassified instead of its own bucket. Declared MIME types are now matched by exact equality first, falling back to regex matching so patterns like audio/.* keep working.
EmbeddingBasedDocumentSplitter now sets `spl
Note truncated.
Nothing published for this version
anyio is installed transitively through httpx and openai; versions before 4.14.2 are affected by CVE-2026-63374 (GHSA-82r6-8w77-94w6).
anyio>=4.14.2. anyio is installed transitively through httpx and openai; versions before 4.14.2 are affected by CVE-2026-63374 (GHSA-82r6-8w77-94w6).certifi>=2026.10.19. certifi is installed transitively through httpx and posthog; earlier versions trust eMudhra/emSign certificate authorities whose private keys were compromised (GHSA-6q48-6c7w-9gw2). If you pin certifi, raise the pin to at least 2026.10.19.anyio is installed transitively through httpx and openai ; versions before 4.14.2 are affected by CVE-2026-63374 ( GHSA-82r6-8w77-94w6 ).
anyio>=4.14.2. anyio is installed transitively through httpx and openai; versions before 4.14.2 are affected by CVE-2026-63374 (GHSA-82r6-8w77-94w6).certifi>=2026.10.19. certifi is installed transitively through httpx and posthog; earlier versions trust eMudhra/emSign certificate authorities whose private keys were compromised (GHSA-6q48-6c7w-9gw2). If you pin certifi, raise the pin to at least 2026.10.19.…the Datadog and OpenTelemetry tracers — are now deprecated and will be removed in 3.0.
This release begins the migration of many components out of haystack core and into dedicated integration packages, in preparation for Haystack 3.0. Components with heavy or optional dependencies — including all SentenceTransformers embedders and rankers, the Hugging Face API components, the legacy Generators, TikaDocumentConverter, AzureOCRDocumentConverter, the Whisper transcribers, the OpenAPI connectors, the spaCy and Transformers extractors/classifiers/routers, SerperDevWebSearch, SearchApiWebSearch, DocumentLanguageClassifier/TextLanguageRouter, and the Datadog and OpenTelemetry tracers — are now deprecated and will be removed in 3.0.
Each component continues to work as before for now, and moving to the new package is a one-line import change once you install it. See the Deprecation Notes below for the full list and per-component migration snippets. For example:
# Before
from haystack.components.embedders import SentenceTransformersTextEmbedder
# After: pip install sentence-transformers-haystack
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
ConditionalRouterConditionalRouter now accepts an output_passthrough: True flag on a route. When set, the route's output is treated as a plain variable name rather than a Jinja2 template, and the value is passed straight through from the pipeline inputs. This lets you route complex, non-basic types such as dataclasses and Pydantic models without the Jinja2 rendering silently converting them to their string representation.
from haystack.components.routers import ConditionalRouter
routes = [
{
"condition": "{{query.intent == 'search'}}",
"output": "query", # variable name, not a Jinja2 template
"output_name": "search_query",
"output_type": ParsedQuery,
"output_passthrough": True,
},
]
router = ConditionalRouter(routes)
result = router.run(query=query)
assert result["search_query"] is query # same object, type preserved
DocumentNDCGEvaluator now matches documents by their content field by default instead of their auto-generated id. Previously, ground truth and retrieved documents were matched only if they had identical id values, which rarely happened in practice since IDs are generated independently for each Document instance. As a result, NDCG scores computed with this evaluator may change for existing pipelines. To keep the previous id-based matching behavior, pass document_comparison_field="id" when constructing the evaluator.run_async) to LLMEvaluator, FaithfulnessEvaluator, and ContextRelevanceEvaluator. This allows concurrent evaluation loops inside async applications like FastMCP or FastAPI without blocking the main event loop, while automatically falling back to thread workers for synchronous chat generators.MarkdownToDocument. When initialized with extract_frontmatter=True, YAML frontmatter at the beginning of a Markdown file is removed from the converted content and added to Document.meta.Added document_comparison_field parameter to DocumentNDCGEvaluator, consistent with DocumentMAPEvaluator, DocumentMRREvaluator, and DocumentRecallEvaluator. Users can now match documents by "content", "id", or any "meta.<key>" field when calculating NDCG scores.
Add output_passthrough option to ConditionalRouter. When output_passthrough: True is set in a route, the output field is treated as a plain variable name instead of a Jinja2 template, and the value is passed directly from the pipeline inputs to the route output. This allows routing of complex non-basic types such as dataclasses and Pydantic models without unwanted Jinja2 template processing.
Without output_passthrough, the router renders output as a Jinja2 template, which converts the value to its string representation. Custom types cannot survive that round-trip:
# Without output_passthrough — the object is silently converted to a string
routes = [
{
"condition": "{{True}}",
"output": "{{query}}",
"output_name": "out",
"output_type": ParsedQuery,
}
]
router = ConditionalRouter(routes)
result = router.run(query=ParsedQuery(text="hello", intent="search", entities=[]))
# result["out"] == "ParsedQuery(text='hello', intent='search', entities=[])"
# ^^^ str, not ParsedQuery — the object was destroyed
Set output_passthrough: True to skip Jinja2 entirely and pass the value directly from kwargs:
from haystack.components.routers import ConditionalRouter
from dataclasses import dataclass, field
@dataclass
class ParsedQuery:
text: str
intent: str # "search" | "chat"
entities: list[str] = field(default_factory=list)
routes = [
{
"condition": "{{query.intent == 'search'}}",
"output": "query", # variable name, not a Jinja2 template
"output_name": "search_query",
"output_type": ParsedQuery,
"output_passthrough": True,
},
{
"condition": "{{query.intent == 'chat'}}",
"output": "query",
"output_name": "chat_query",
"output_type": ParsedQuery,
"output_passthrough": True,
},
]
router = ConditionalRouter(routes)
query = ParsedQuery(text="What is Haystack?", intent="search", entities=["Haystack"])
result = router.run(query=query)
assert isinstance(result["search_query"], ParsedQuery) # type preserved
assert result["search_query"] is query # same object, no copying
Added an opt-in expand_reference_ranges parameter to AnswerBuilder. When enabled, reference ranges like [6-10] and comma-separated ranges like [1-3,7-9] are expanded to the corresponding document indices in RAG answers. The feature is disabled by default to preserve existing parsing behavior.
AzureOCRDocumentConverter is deprecated and will be removed from Haystack in version 3.0. It is moving to the azure-form-recognizer-haystack package. To continue using it, install the package with pip install azure-form-recognizer-haystack and update your import as follows:
from haystack_integrations.components.converters.azure_form_recognizer import AzureOCRDocumentConverter
DatadogTracer is deprecated and will be removed from Haystack in version 3.0. It is moving to the datadog-haystack package. To continue using it, install the package with pip install datadog-haystack and add the DatadogConnector component to your pipeline to enable tracing, or update your import as follows:
from haystack_integrations.tracing.datadog import DatadogTracer
Note that, starting with Haystack 3.0, Datadog tracing is no longer auto-enabled when ddtrace is installed. Use the DatadogConnector component to enable it.
OpenAIGenerator, AzureOpenAIGenerator, HuggingFaceAPIGenerator, and HuggingFaceLocalGenerator have been deprecated and will be removed in Haystack 3.0. Generators living in Haystack Core Integrations will also be removed in Haystack 3.0.
Their chat counterparts (OpenAIChatGenerator, AzureOpenAIChatGenerator, HuggingFaceAPIChatGenerator, HuggingFaceLocalChatGenerator) are the replacement. Starting from Haystack 2.30.0, all ChatGenerators also accept a plain str as input to make the transition easier.
How to migrate:
Direct usage (running a generator from Python code)
Before:
from haystack.components.generators import OpenAIGenerator
gen = OpenAIGenerator()
result = gen.run("What is NLP?")
text = result["replies"][0] # str
meta = result["meta"][0] # dict with model metadata
After:
from haystack.components.generators.chat import OpenAIChatGenerator
gen = OpenAIChatGenerator()
result = gen.run("What is NLP?") # str input accepted directly
reply = result["replies"][0] # ChatMessage
text = reply.text # str
meta = reply.meta # dict with model metadata (now on the message)
System prompt
Before:
from haystack.components.generators import OpenAIGenerator
gen = OpenAIGenerator(system_prompt="You are concise.")
result = gen.run("What is NLP?")
After:
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
gen = OpenAIChatGenerator()
result = gen.run([
ChatMessage.from_system("You are concise."),
ChatMessage.from_user("What is NLP?"),
])
Pipeline usage
Pipelines that connected PromptBuilder (output: str) to a legacy Generator continue to work unchanged when you swap in a ChatGenerator. The Haystack pipeline type system automatically converts str to list[ChatMessage] at the connection edge.
Before:
from haystack.components.generators import OpenAIGenerator
from haystack.components.builders import PromptBuilder
pipeline.add_component("prompt_builder", PromptBuilder(template=prompt_template))
pipeline.add_component("llm", OpenAIGenerator())
pipeline.connect("prompt_builder", "llm") # str -> str
After, minimal change (smart connection still works):
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.builders import PromptBuilder
pipeline.add_component("prompt_builder", PromptBuilder(template=prompt_template))
pipeline.add_component("llm", OpenAIChatGenerator())
pipeline.connect("prompt_builder", "llm") # str -> list[ChatMessage], auto-converted
Alternatively, use ChatPromptBuilder:
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.builders import ChatPromptBuilder
from haystack.dataclasses import ChatMessage
template = [ChatMessage.from_user(prompt_template)]
pipeline.add_component("prompt_builder", ChatPromptBuilder(template=template))
pipeline.add_component("llm", OpenAIChatGenerator())
pipeline.connect("prompt_builder.prompt", "llm.messages")
HuggingFaceAPIChatGenerator, HuggingFaceAPITextEmbedder, HuggingFaceAPIDocumentEmbedder, and HuggingFaceTEIRanker are deprecated and will be removed from Haystack in version 3.0. They are moving to the huggingface-api-haystack package. To continue using them, install the package with pip install huggingface-api-haystack and update your imports as follows:
from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder
from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder
from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker
DocumentLanguageClassifier and TextLanguageRouter are deprecated and will be removed from Haystack in version 3.0. They are moving to the langdetect-haystack package. To continue using them, install the package with pip install langdetect-haystack and update your imports as follows:
from haystack_integrations.components.classifiers.langdetect import DocumentLanguageClassifier
from haystack_integrations.components.routers.langdetect import TextLanguageRouter
OpenAPIConnector, OpenAPIServiceConnector and OpenAPIServiceToFunctions are deprecated and will be removed from Haystack in version 3.0. They are moving to the openapi-haystack package. To continue using them, install the package with pip install openapi-haystack and update your imports as follows:
from haystack_integrations.components.connectors.openapi import OpenAPIConnector
from haystack_integrations.components.connectors.openapi import OpenAPIServiceConnector
from haystack_integrations.components.converters.openapi import OpenAPIServiceToFunctions
These components are a legacy way to connect Haystack to external APIs. For most use cases, consider using the MCPTool instead, which is the modern, standardized way to give pipelines and agents access to external tools and services.
OpenTelemetryTracer is deprecated and will be removed from Haystack in version 3.0. It is moving to the opentelemetry-haystack package. To continue using it, install the package with pip install opentelemetry-haystack and add the OpenTelemetryConnector component to your pipeline to enable tracing, or update your import as follows:
from haystack_integrations.tracing.opentelemetry import OpenTelemetryTracer
Note that, starting with Haystack 3.0, OpenTelemetry tracing is no longer auto-enabled when opentelemetry-sdk is installed. Use the OpenTelemetryConnector component to enable it.
SearchApiWebSearch is deprecated and will be removed from Haystack in version 3.0. It is moving to the searchapi-haystack package. To continue using it, install the package with pip install searchapi-haystack and update your import as follows:
from haystack_integrations.components.websearch.searchapi import SearchApiWebSearch
SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder, SentenceTransformersDocumentImageEmbedder, SentenceTransformersSparseTextEmbedder, SentenceTransformersSparseDocumentEmbedder, SentenceTransformersDiversityRanker, and SentenceTransformersSimilarityRanker are deprecated and will be removed from Haystack in version 3.0. They are moving to the sentence-transformers-haystack package. To continue using them, install the package with pip install sentence-transformers-haystack and update your imports as follows:
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersDocumentEmbedder
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersDocumentImageEmbedder
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersSparseTextEmbedder
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersSparseDocumentEmbedder
from haystack_integrations.components.rankers.sentence_transformers import SentenceTransformersDiversityRanker
from haystack_integrations.components.rankers.sentence_transformers import SentenceTransformersSimilarityRanker
SerperDevWebSearch is deprecated and will be removed from Haystack in version 3.0. It is moving to the serperdev-haystack package. To continue using it, install the package with pip install serperdev-haystack and update your import as follows:
from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
The spacy backend of NamedEntityExtractor is deprecated and will be removed from Haystack in version 3.0. It is moving to the spacy-haystack package and being renamed to SpacyNamedEntityExtractor. To continue using it, install the package with pip install spacy-haystack and update your import as follows:
from haystack_integrations.components.extractors.spacy import SpacyNamedEntityExtractor
TikaDocumentConverter is deprecated and will be removed from Haystack in version 3.0. It is moving to the tika-haystack package. To continue using it, install the package with pip install tika-haystack and update your import as follows:
from haystack_integrations.components.converters.tika import TikaDocumentConverter
TransformersZeroShotDocumentClassifier, TransformersTextRouter, TransformersZeroShotTextRouter, HuggingFaceLocalChatGenerator, NamedEntityExtractor, and ExtractiveReader are deprecated and will be removed from Haystack in version 3.0. They are moving to the transformers-haystack package. Some of them are also being renamed. To continue using them, install the package with pip install transformers-haystack and update your imports as follows:
from haystack_integrations.components.classifiers.transformers import TransformersZeroShotDocumentClassifier
from haystack_integrations.components.routers.transformers import TransformersTextRouter
from haystack_integrations.components.routers.transformers import TransformersZeroShotTextRouter
# HuggingFaceLocalChatGenerator was renamed to TransformersChatGenerator
from haystack_integrations.components.generators.transformers import TransformersChatGenerator
# NamedEntityExtractor (Hugging Face backend) was renamed to TransformersNamedEntityExtractor
from haystack_integrations.components.extractors.transformers import TransformersNamedEntityExtractor
# ExtractiveReader was renamed to TransformersExtractiveReader
from haystack_integrations.components.readers.transformers import TransformersExtractiveReader
LocalWhisperTranscriber and RemoteWhisperTranscriber are deprecated and will be removed from Haystack in version 3.0. They are moving to the whisper-haystack package. To continue using them, install the package with pip install whisper-haystack and update your imports as follows:
from haystack_integrations.components.audio.whisper import LocalWhisperTranscriber
from haystack_integrations.components.audio.whisper import RemoteWhisperTranscriber
ChatPromptBuilder to cover cases where specially crafted template variables could still be interpreted as structured content (e.g., images, tool calls) instead of plain text. Protection now relies on two independent mechanisms.DocumentToImageContent and LLMDocumentContentExtractor. When root_path is set, a file_path in document metadata that escapes the root (via ../ or an absolute path) now raises a ValueError before any file is read, preventing attacker-controlled metadata from reading arbitrary files on the host.repr() of a Secret built via Secret.from_token(...) no longer includes the raw token. Previously the dataclass-generated repr printed the token verbatim, so any path that formats a component's locals — exception tracebacks, print(), Jupyter echo, log aggregators — could leak the API key. The token is now rendered as <redacted>.DocumentJoiner now raises a clear ValueError when the provided weights sum to zero, instead of failing with an opaque ZeroDivisionError while normalizing them.document_matches_filter raising a FilterError when comparing a string date in Document.meta against a datetime object using ordering operators (>, >=, <, <=).FilterError that lists the valid operators, instead of a cryptic KeyError. For example, a typo such as {"field": "meta.year", "operator": "gt", "value": 2000} (instead of ">") previously surfaced as KeyError: 'gt'. This applies to both comparison operators and logical operators (AND, OR, NOT).TypeError in AnswerJoiner when running with sort_by_score=True and at least one answer had a score of None. As documented, an answer without a score is now treated as if its score were negative infinity and sorted last, instead of raising TypeError: '<' not supported between instances of 'float' and 'NoneType'.ZeroDivisionError in InMemoryDocumentStore.bm25_retrieval that occurred at query time when every stored document had empty (but not None) content. Such a tokenless corpus has no vocabulary and an average document length of zero, which made all three BM25 algorithms divide by zero. Retrieval now scores every candidate as 0.0 in this case: unscaled BM25Okapi returns the documents with score 0.0, while BM25L and BM25Plus return an empty list (non-positive scores are filtered). Corpora with at least one non-empty document are unaffected.>= and < metadata filter operators returning wrong results for datetime strings that represent the same moment in time but are formatted differently (for example "2025-01-01" vs "2025-01-01T00:00:00", or the same instant expressed with different timezone offsets). Equality was previously checked by raw string comparison instead of comparing the parsed datetimes, so >= evaluated to False and < evaluated to True for equal datetimes. This caused boundary documents to be silently dropped from date range queries in InMemoryDocumentStore and any other component relying on document_matches_filter.DocumentJoiner when using join_mode="distribution_based_rank_fusion" with documents that have score=None. The score normalization now treats a missing score as 0 (consistent with how the mean/standard-deviation are computed), instead of raising TypeError: unsupported operand type(s) for -: 'NoneType' and 'float'.DocumentSplitter now raises a clear ValueError at initialization when split_overlap is greater than or equal to split_length. Previously this configuration was accepted and only failed later at run time with an opaque error from the underlying windowing helper (the window step became zero or negative).FaithfulnessEvaluator and ContextRelevanceEvaluator to exclude failed queries (score nan) from the aggregate mean score instead of silently returning nan. A warning is now logged when one or more queries are skipped.FileTypeRouter silently routing MIME types containing + (such as image/svg+xml, application/ld+json, and every application/*+xml / application/*+json) into the unclassified bucket. Entries in mime_types were being compiled as regex, so the + was interpreted as a quantifier and the type never matched itself. Each source's MIME type is now checked against mime_types by exact equality first, falling back to the existing regex match — so literal MIMEs route correctly and patterns like audio/.* keep working unchanged.GeneratedAnswer.from_dict raising an IndexError when the serialized meta contained an empty all_messages list. Deserialization now guards against the empty list (consistent with to_dict) and round-trips correctly.HuggingFaceLocalGenerator so that when multiple stop_words are configured the generator returns exactly N replies instead of N×M replies. Previously the list comprehension created a cross-product, duplicating replies and leaving some stop words unstripped.human_in_the_loop confirmation strategies (_run_confirmation_strategies and _run_confirmation_strategies_async) raising an unhandled KeyError when a tool call references a tool name that isn't in the tools list (e.g. the chat model hallucinated it). The call now passes through unmodified to ToolInvoker, which already raises a clean ToolNotFoundException (respecting raise_on_failure) for this case.HTMLToDocument now skips ByteStream objects with empty content instead of passing them to trafilatura. This prevents noisy lxml parse error logs (such as "Document is empty") when a fetcher emits an empty stream.Pipeline.connect() where any list[T] -> T connection was accepted without warning (e.g. list[Document] -> Document) and only the first list element was forwarded at runtime, dropping the rest. The conversion is now restricted to inner types str and ChatMessage, matching the original intent; any other list[T] -> T wiring now raises PipelineConnectError at connect() time. As a defense-in-depth measure, the runtime UNWRAP conversion also raises ValueError (wrapped in PipelineRuntimeError) when given a multi-element list, so any future regression of the connect-time gate cannot silently drop items. This also affects e.g. a generator using n>1 whose replies are wired into a single-str or single-ChatMessage consumer — that pipeline now raises instead of silently using replies[0].LLMEvaluator.to_dict not serializing the raise_on_failure parameter, causing it to silently reset to True after a pipeline round-trip.InMemoryDocumentStore.load_from_disk reconstructing documents with the plain Document constructor instead of Document.from_dict. Documents containing a blob (ByteStream) or a sparse_embedding (SparseEmbedding) were loaded with those fields as raw dictionaries, which later crashed repr(), to_dict(), equality comparison, save_to_disk of the reloaded store, and any component accessing document.blob.data.MetaFieldGroupingRanker raising a TypeError when sort_docs_by points to a non-numeric metadata field (for example ISO date strings) and some documents are missing that field. Documents that miss the field are now placed at the end of their group, regardless of the field's type.EmbeddingBasedDocumentSplitter to the PreProcessors index page, and add MarkdownHeaderSplitter and SpacyNamedEntityExtractor to the sidebar navigation. These components had documentation pages but were missing from navigation, making them undiscoverable by users browsing the docs.top_k_per_retriever: Allows specifying the maximum number of documents to return per retrievertop_k: Allows specifying the maximum number of documents to be retrieved from combined results of all retrieversTypeError when filtering documents on a nested metadata field (e.g. meta.user.age) where an intermediate value is not a dictionary (for example None or a scalar). Such intermediate values are now treated as a missing field (None) instead of raising, which previously crashed filter_documents for stores like InMemoryDocumentStore.OpenAIResponsesChatGenerator dropping encrypted_content from reasoning items in streaming mode. Two issues were addressed: _convert_streaming_chunks_to_chat_message was discarding all reasoning extras except id and type; and _convert_response_chunk_to_streaming_chunk had no handler for the response.output_item.done event for reasoning items, which is the only event that carries encrypted_content. Both are now fixed, so encrypted_content is preserved end-to-end and multi-turn conversations with store=False and include=["reasoning.encrypted_content"] work correctly.RecursiveDocumentSplitter silently ignoring split_overlap when none of the configured separators match the input text. In that code path the component fell back to fixed-size chunking but returned the result directly without calling _apply_overlap, so every chunk after the first was missing the expected overlap prefix. The fix applies _apply_overlap to the fallback chunks before returning them, making behaviour consistent with the separator-matched code path. All three split units ("char", "word", and "token") are affected and are now covered by regression tests.RecursiveDocumentSplitter producing incorrect split_idx_start metadata values when split_unit="word" (or "token") is used together with split_overlap > 0. Previously, self.split_overlap (a word/token count) was subtracted directly from a character-offset counter, causing every chunk after the first to report a wrong start position in the original document. The fix uses the actual character length of the overlap suffix, obtained from _get_overlap(), so the offset is always correct regardless of split_unit.RecursiveDocumentSplitter not populating the _split_overlap metadata when split_unit is "word" or "token" and split_overlap is greater than 0. The overlap length was computed with a word/token count while the offsets it is compared against are character positions, so it became negative and the overlap metadata was silently dropped. The overlap is now measured in characters, matching the ranges it records.serialize_type dropping NoneType when it appears as a regular argument of a typing generic. Types such as typing.Dict[str, None], typing.Tuple[int, None], typing.List[None] and unions with more than two members like typing.Union[str, int, None] were serialized incorrectly (for example to typing.Dict[str]), which produced malformed type strings that could not be deserialized again. typing.Optional[X] is still serialized as typing.Optional[X] without a redundant trailing None.SuperComponent.run and SuperComponent.run_async raising ValueError: The truth value of ... is ambiguous whenever a non-scalar input (numpy arrays, pandas DataFrames/Series, torch tensors, or any object whose __ne__ returns a non-scalar) was passed. The internal sentinel filter is now an identity check (is not _delegate_default) instead of value equality (!= _delegate_default), so it no longer invokes __ne__ on user-provided values.TopPSampler that silently disabled filtering:
top_p=0.0 to run() was silently replaced by the value set in the constructor because of a falsy-value check. The override is now honored, returning the single highest-scoring document, consistent with TopPSampler(top_p=0.0).InputSocket.__post_init__ crashing with IndexError when a Variadic input uses a bare Iterable without a type argument (e.g. Annotated[Iterable, HAYSTACK_VARIADIC_ANNOTATION]). Now raises ComponentError with a clear message instead of an unhelpful IndexError.FallbackChatGenerator to use the standard component_to_dict serialization path. This ensures custom chat generator components without an explicit to_dict method are no longer silently omitted from the serialized chat_generators list.HierarchicalDocumentSplitter now validates its block_sizes and split_overlap parameters at construction time. Previously, an empty block_sizes set silently produced no splits, and a split_overlap too large relative to the smallest block size raised a confusing error referencing split_length, a parameter that doesn't exist on this component. HierarchicalDocumentSplitter now raises a clear ValueError in both cases, using its own parameter names and identifying the offending value.HTMLToDocument and MarkdownToDocument now accept an encoding parameter (default "utf-8") and honour ByteStream.meta["encoding"] at run time, mirroring the behaviour of TextFileToDocument. Previously both converters hardcoded decode("utf-8"), causing UnicodeDecodeError for non-UTF-8 sources whose encoding was supplied via ByteStream metadata.InMemoryDocumentStore.embedding_retrieval producing NaN cosine similarity scores when a document (or the query) had a zero-norm embedding. Zero-norm vectors are now handled without dividing by zero, so such documents receive a score of 0.0 instead of NaN (which silently corrupted ranking).0, False, and empty strings when meta_fields_to_embed is used by sentence-transformer embedders and rankers.QueryExpander now ignores malformed responses where queries is not a list, so a string response is no longer split into single-character queries.@Aarkin7, @Amnah199, @anakin87, @ATOM00blue, @axelray-dev, @Ayushhgit, @bilgeyucel, @bogdankostic, @camgrimsec, @charliesheh, @davidsbatista, @ErenAta16, @Goodnight77, @GovindhKishore, @greymoth-jp, @gyx09212214-prog, @hoangsonww, @HotThoughts, @i-anubhav-anand, @immuhammadfurqan, @jdoughty04, @jialiuyang, @julian-risch, @Kunal-Somani, @milljer, @mustafakhokhar, @NIK-TIGER-BILL, @Osamaali313, @oyinkanchekwas, @rautaditya2606, @ritikraj2425, @RitwijParmar, @santino18727-debug, @shr8769, @sjrl, @spideyashith, @Srivatsa03, @SyedShahmeerAli12, @vedjaw, @vidigoat
One column per quarter.