feat: add opt-in ToolCache for caching tool results in Agent loops

[lorenzozanee]

Related Issues

• fixes Cache tool results inside Agent loops (avoid duplicate identical tool calls) #11588

Proposed Changes:

Agent loops re-executed identical read-only tool calls with the same arguments. Add opt-in ToolCache with Tool(cacheable=True) so identical calls within TTL are served from cache.

How did you test it?

Added unit and integration tests for cache hit/miss, TTL and Agent integration; updated serialization expectations.

Notes for the reviewer

No breaking change — cacheable defaults to false and tool_cache defaults to None. Reviewers: @julian-risch @sjrl @lorenzozanee

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]

@lorenzozanee is attempting to deploy a commit to the deepset Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[github-actions]

Hi @lorenzozanee, thanks for your interest in contributing to Haystack! 🙏

⚠️ You currently have 5 open pull requests in this repository (#12513, #12497, #12495, #12469 and this one). Our review capacity is limited, so please hold off opening more PRs until we've had a chance to review your first 2 open PRs. This helps us give each contribution the attention it deserves. Thank you!

This is an automated message to help us keep the review queue healthy.

[HaystackBot]

Hi @lorenzozanee, thanks a lot for your contribution! 🙏

We noticed that the Contributor License Agreement (CLA) check (license/cla) hasn't passed yet, so we've temporarily moved this PR to draft and paused the review assignment.

To get your PR reviewed, please sign the CLA via the link in the license/cla check below (or in the CLA bot comment). As soon as the check turns green, this PR will automatically be marked ready for review again and a reviewer will be re-assigned.