Python: Preserve method tool invocation limits

[Barry (barry166)]

Motivation & Context

FunctionTool.__get__ creates a fresh shallow copy each time a decorated instance method is accessed. Invocation counters therefore reset when callers retrieve the method again, so max_invocations and max_invocation_exceptions are not enforced for the documented method-tool usage pattern. This fixes the reproduced behavior in #8904.

Description & Review Guide

• What are the major changes? Cache bound method tools in each owner's instance dictionary, preserving copy-on-bind behavior and isolating equal or unhashable owners. Keep the original uncached binding behavior for slots-only owners without an instance dictionary.
• What is the impact of these changes? Repeated access on owners with an instance dictionary shares invocation and exception counters. The owner-local cache can be garbage-collected, and pickle/deepcopy recreate it empty. Slots-only owners remain callable; callers must retain the returned tool to preserve its counters. Regression tests cover identity isolation, owner lifetime, copying, pickle round trips, and JSON serialization.
• What do you want reviewers to focus on? Please verify owner lifetime, the documented slots-only fallback, and that serialization omits runtime bindings and restores an empty cache.

Related Issue

Fixes #8904

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Codex assisted with review analysis, implementation, regression tests, validation, the PR description, and review responses. The contributor's personal-review acknowledgement is pending.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Copilot review overview

🟡 Changes recommended

The cache leaks owner instances, breaks some valid owner types, aliases equal instances, and prevents pickle serialization.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Binding fails for unhashable or non-weak-referenceable owners · New
• Runtime cache breaks FunctionTool pickling · New

What changed in this PR

Fixes method-tool invocation limits by caching bound FunctionTool instances per owner.

Changes:

• Adds a weak-key bound-tool cache.
• Adds regression tests for invocation and exception limits.

File	Description
python/​packages/​core/​agent_framework/​_tools.py	Caches bound method tools.
python/​packages/​core/​tests/​core/​test_tools.py	Tests persistent method invocation counters.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Eduard van Valkenburg (eavanvalkenburg)]

Barry (@barry166) The current owner cache assumes every valid owner is hashable and weak-referenceable, so unhashable instances and slotted objects without weakref support can fail during tool binding. The cache also remains in inherited pickle state even though it is excluded from dictionary serialization, so pickling a FunctionTool can still fail or retain runtime-only cache state. Please use an owner strategy that supports the existing valid object surface and explicitly omit/recreate the cache across pickle, with regressions for both cases.

[Barry (barry166)]

Implemented in 556da45.

• Replaced the global weak-key cache with an owner-local cache. This supports unhashable and non-weak-referenceable owners with instance dictionaries, isolates equal owners, and removes the strong-reference leak.
• Preserved uncached binding for slots-only owners without an instance dictionary. These callers must retain the returned tool for persistent invocation limits; the limitation is documented in the descriptor and PR description.
• Runtime bindings are omitted during pickle/deepcopy and recreated on subsequent access. Added regressions for standalone/bound tool pickle, owner round trips, copying, lifetime, and JSON conversion.

Validation: 638 related tests passed, 1 skipped. Changed-file Ruff formatting/lint, strict source Pyright, and all five configured test typing checkers passed. Six new cases reproduce the original owner-compatibility/identity/lifetime failures when run against the previous descriptor implementation.

Synced with main in d2f3cae and reran the checks above. GitHub pull_request workflows currently require maintainer action before CI can run.

[Barry (barry166)]

Synced the branch with current main in c04dffbf. The sync introduced a runtime-only OpenTelemetry histogram on FunctionTool; I excluded it from pickle state and recreate it on restore so the existing serialization regressions continue to pass.

Validation on the merged branch:

• test_tools.py: 166 passed
• core unit suite: 8785 passed, 20 skipped, 2 xfailed
• Ruff formatting/lint and strict source Pyright
• test typing checks: ty, pyrefly, zuban, Pyright, and mypy

The PR is mergeable again. Public API compatibility and CLA are green; the remaining pull-request workflows still require maintainer action.