Add snapshot_callback support to pipeline.run (with agent support)

[mpangrazzi]

Related Issues

• fixes #https://github.com/deepset-ai/haystack-private/issues/236

Proposed Changes:

NOTE: Reimplementation of #10250

Added a snapshot_callback parameter to Pipeline.run() and Agent.run() that allows users to provide a custom handler for pipeline snapshots instead of the default file-saving behavior. Currently, when a breakpoint is triggered or an error occurs during pipeline execution, snapshots are always saved to JSON files on disk.

This is limiting for users who want to e.g. save snapshots to a database or send snapshots to a remote service.

How did you test it?

unit tests, manual verification

Checklist

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

[vercel]

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

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
haystack-docs	Ignored	Preview	Jan 8, 2026 10:20am

[sjrl]

@mpangrazzi thanks for implementing this! If I recall a number of users also requested a way to turn off the file saving behavior and I think you mentioned you'd look at adding a something like a boolean toggle for this when working on this feature. Is that something you are still planning on doing?

[mpangrazzi]

@sjrl yes definitely! But I would do that in a separate PR. So, with this one we introduce snapshot_callback to let users be able e.g. to save snapshots in a database or so. Then I'll open a new one which will probably add a boolean flag / env var to enable or disable the default behaviour (ie dumping snapshots in files). WDYT?

[sjrl]

@sjrl yes definitely! But I would do that in a separate PR. So, with this one we introduce snapshot_callback to let users be able e.g. to save snapshots in a database or so. Then I'll open a new one which will probably add a boolean flag / env var to enable or disable the default behaviour (ie dumping snapshots in files). WDYT?

Sounds good! Especially the env var idea.

[sjrl]

Looks good!

Makes me wonder if in the future if we should refactor Breakpoint to drop the snapshot_file_path field and always use the callback feature. Then we could create a default snapshot_callback that uses the current logic to save to disk.

[davidsbatista]

LGTM, just minor suggestions.

[mpangrazzi]

@sjrl @davidsbatista thanks!