refactor: Refactor agent breakpoint logic

[sjrl]

Related Issues

• partially addresses HITL: Resuming agent execution fails with KeyError: 'serialized_data' due to incomplete snapshot (original_input_data={}) haystack-experimental#399

Proposed Changes:

The way we save a pipeline and agent snapshot when an AgentBreakpoint is triggered needs to be refactored to so that using an Agent in a Pipeline with the BreakpointConfirmationStrategy in haystack-experimental works as expected.

• When we pass an AgentBreakpoint to the Pipeline.run() method we no longer auto inject the parent pipeline snapshot into the underlying Agents arguments. Instead when an Agent triggers a BreakpointException, that exception is caught by the Pipeline.run and the final pipeline snapshot construction is done at the pipeline level. This is similar to how we handled creating a pipeline snapshot when a PipelineRuntimeError occurred.
• Added a private convenience function PipelineSnapshot._from_agent_snapshot to help reduce duplicate code.
• Created a new utility function _should_trigger_tool_invoker_breakpoint which is used within Agent to determine whether the ToolBreakpoint should be passed to the Pipeline._run_component method.
• Added new property break_point to BreakpointException for easier access to the break point that caused the exception.

How did you test it?

Making sure existing tests pass.

Notes for the reviewer

Checklist

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

[vercel]

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

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
haystack-docs	Ignored	Preview	Dec 17, 2025 7:52am

[coveralls]

Pull Request Test Coverage Report for Build 20295604111

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 129 unchanged lines in 15 files lost coverage.
• Overall coverage increased (+0.02%) to 92.154%

---

Files with Coverage Reduction	New Missed Lines	%
components/converters/output_adapter.py	1	98.44%
components/extractors/llm_metadata_extractor.py	1	82.5%
components/extractors/named_entity_extractor.py	1	68.45%
core/component/component.py	1	99.44%
core/type_utils.py	1	94.2%
components/builders/chat_prompt_builder.py	2	98.21%
core/component/types.py	2	91.67%
utils/type_serialization.py	2	85.71%
components/agents/agent.py	5	96.8%
core/errors.py	7	88.16%

Totals
Change from base Build 20102232282:	0.02%
Covered Lines:	14129
Relevant Lines:	15332

---

💛 - Coveralls

[sjrl]

Hey @mpangrazzi and @davidsbatista I'd appreciate your review since this may impact https://github.com/deepset-ai/haystack-private/issues/236

[davidsbatista]

@sjrl good job!

• The breakpoint logic was moved to inside the run_component()method, before was kind of scattered in different points in the code. Also the Agent uses this mechanism.
• Plus, the BreakpointException and the PipelineRunTimeError the two exceptions that can create a PipelineSnapshoot are now at the same place

I did a first review and noticed essentially duplication of code (I can imagine you noticed as well but wanted to first see it works) - my comments are towards solutions for those duplication.

[sjrl]

Hey @mpangrazzi this is ready for another review!

[mpangrazzi]

Overall it looks good! I left some minor comments

[mpangrazzi]

👍