You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Python: [Bug]: max_invocations / max_invocation_exceptions are not enforced for tools defined as methods #8904
FunctionTool.__get__ returns copy.copy(self) on every attribute access for method tools. Each bound copy starts from the class-level invocation_count, which is never incremented, so the limit only works if the caller keeps one bound object. Accessing instance.method again, for example building tools=[svc.ping] per run, resets the count.
Expected: a tool decorated with @tool(max_invocations=1) on a method raises ToolException on the second call for the same instance. Actual: unlimited calls succeed, and Svc.ping.invocation_count stays at 0, so the documented "inspect/reset invocation_count" workflow does not work either.
This is different from #2329. That issue is about the counter being global on singleton tools; here the limit is not enforced at all.
Suggested fix: cache the bound copy per instance (e.g. weakref.WeakKeyDictionary on the descriptor), or move the counters into a shared mutable holder referenced by the copies.
Code Sample
import asyncio
from agent_framework import tool
class Svc:
@tool(max_invocations=1)
def ping(self, x: int) -> int:
return x
async def main():
s = Svc()
for i in range(3):
await s.ping.invoke(arguments={"x": i}) # all 3 succeed; 2nd should raise
print(Svc.ping.invocation_count) # 0
b = s.ping # reusing one bound object does enforce itawait b.invoke(arguments={"x": 0})await b.invoke(arguments={"x": 1}) # ToolException
asyncio.run(main())
🤖 Automated triage reproduction notes(agent-authored — trust but verify)
Agent analysis
FunctionTool.get in python/packages/core/agent_framework/_tools.py:722-749 creates a fresh shallow copy whenever a decorated instance method is accessed, while FunctionTool.call updates counters only on that copy. The bug occurs when callers retrieve instance.method again between calls, bypassing both max_invocations and max_invocation_exceptions. Minimal repro: decorate an instance method with either limit set to 1 and invoke it twice through separate instance.method lookups.
Thanks for reporting this and for the work in #8951. We will consider persistent invocation and exception limits across repeated method-tool lookups as a core MAF capability. The exact counter lifetime, reset/copy behavior and support for different owner types still need agreement: current docs define limits per FunctionTool instance and describe a fresh binding on each lookup. This is not a promise of implementation or timing, approval of the current cache design, or a request for competing implementation. We will plan the compatibility boundary using the existing PR before marking it ready or assigning additional work.
/plan Establish the accepted core counter/binding lifetime contract for #8904 through existing #8951, not competing implementation. Current main documents limits per FunctionTool instance and fresh descriptor bindings; retaining one binding already preserves counters. Core consideration now accepts investigating persistence across repeated lookups, not an unrestricted per-run/global cap or blanket cache-design approval. Compare fresh binding identity with owner-scoped counter state against cached binding identity. Define class access, invocation/exception counters, same/different/equal/unhashable owners, resets, shallow/deep copies and pickle semantics. Agree the slots-only/no-dict/no-weakref boundary: the current fallback does not preserve counters across lookups. Current 00338c8 addresses prior weak-key/pickle issues and prevents cache-name overwrites by raising; do not repeat resolved data-destruction findings, but decide whether that new binding failure for previously valid owners is acceptable or requires a non-colliding strategy. Cover GC, multiple/inherited descriptors, runtime metrics serialization, concurrency and documented batch overshoot without inventing strict security/rate-limit guarantees. Rebase the currently conflicted PR and run current-main-versus-candidate regressions; distinguish contributor-reported checks from new results. Update the exact public lifetime contract and consumer guidance. Keep #8911 per-run policy distinct. Estimate executable production scope after agreement; no ready label, new assignment or blanket PR approval yet.
/plan Establish the accepted core counter/binding lifetime contract for #8904 through existing #8951, not competing implementation. Current main documents limits per FunctionTool instance and fresh descriptor bindings; retaining one binding already preserves counters. Core consideration now accepts investigating persistence across repeated lookups, not an unrestricted per-run/global cap or blanket cache-design approval. Compare fresh binding identity with owner-scoped counter state against cached binding identity. Define class access, invocation/exception counters, same/different/equal/unhashable owners, resets, shallow/deep copies and pickle semantics. Agree the slots-only/no-dict/no-weakref boundary: the current fallback does not preserve counters across lookups. Current 00338c8b addresses prior weak-key/pickle issues and prevents cache-name overwrites by raising; do not repeat resolved data-destruction findings, but decide whether that new binding failure for previously valid owners is acceptable or requires a non-colliding strategy. Cover GC, multiple/inherited descriptors, runtime metrics serialization, concurrency and documented batch overshoot without inventing strict security/rate-limit guarantees. Rebase the currently conflicted PR and run current-main-versus-candidate regressions; distinguish contributor-reported checks from new results. Update the exact public lifetime contract and consumer guidance. Keep #8911 per-run policy distinct. Estimate executable production scope after agreement; no ready label, new assignment or blanket PR approval yet.
Method tools (@tool(max_invocations=...) on a method) lose their counters when the method is looked up again. Each instance.method lookup returns a fresh copy of the tool, and counters live on that copy. This was confirmed in current main: FunctionTool.__get__ (_tools.py ~L848-878) does copy.copy(self) and sets _instance. __call__ (~L910-940) increments invocation_count / invocation_exception_count only on that copy. The docstring (~L709-722) says limits are per tool instance and never reset automatically. The _instance and counters are not in DEFAULT_EXCLUDE, so check whether to_dict serializes them.
Per your direction, I did not read the #8951 diff or reviews. I also did not rebase it or run anything: this run is read-only and cannot execute code. So there are no new test results here, and any contributor-reported checks remain unverified.
Recommendation
Code change plus documentation is warranted, but only after the contract below is agreed. Today the limit works only if the caller keeps one bound object. The usual tools=[svc.method] pattern silently does not enforce it, and the class-level counter stays at 0. A documentation-only fix would just document a footgun. This is a bounded, owner-scoped fix, not a general per-run/global cap (that stays in #8911).
Proposed contract (for agreement)
Topic
Proposal
Lifetime
Counters belong to the (owner instance, descriptor) pair and live as long as the owner. They are not per-run and not global.
Class access
Svc.method returns the unbound descriptor. Its counters are never incremented by bound calls. Document this and the old Svc.ping.invocation_count expectation.
Counting
A call counts once on entry. Exceptions count once, including awaited failures, as today.
Owners
Identity-based, never __eq__/__hash__. Two equal owners have separate counters. Unhashable owners work.
Reset
Resetting through the retained bound tool resets the owner's shared state.
Copy/pickle
Shallow copy, deepcopy and pickle of the owner start with fresh counters, because they create a new owner. Counters must not travel in serialized runtime metrics.
Descriptors
Each descriptor on a class has independent state per owner. An inherited or overridden descriptor is keyed by the descriptor object, not the name.
Concurrency
Check-and-increment is not atomic across threads. Batch calls can overshoot, as already documented. It is not a security or rate-limit guarantee.
Fresh binding with owner-scoped state vs. cached binding
Cached binding: one bound object is stored and returned each time. Identity is stable, but it needs somewhere to store it (owner __dict__ or a weak map), and each choice has failure modes.
Fresh binding with shared state: each lookup is still a new copy, but all copies for one owner and descriptor point to one small counter holder. This keeps today's "bind returns a new object" behavior and avoids caching tool objects on the owner. I lean this way for compatibility. The holder still has to be stored per owner, so it has the same storage question below.
Slots-only / no-dict / no-weakref owners
These owners cannot hold either a cache or a weak-key entry. Counters cannot be preserved across lookups for them. The fallback keeps the current behavior: it works, but the caller must retain the bound tool. Document this boundary clearly instead of promising more.
I did not inspect it, so I only give the principle. Raising for owners that previously worked is a new failure. I would not accept that as the default. Prefer a non-colliding storage strategy (for example a name unique to the descriptor, or a framework-private holder). If no safe key exists, fall back to uncached binding rather than raise. I would accept raising only if you explicitly want fail-fast for pre-existing attribute clashes.
GC
State must not keep owners alive, so the owner must not be strongly referenced from a global map. Storing the holder on the owner, or using a weak map, both qualify. Tests should confirm the owner can be collected.
Proposed plan (nothing has been changed)
Agree the contract. The table above plus the three decisions below, recorded in the FunctionTool and tool() docstrings and the core package AGENTS.md. Keep the singleton caveat and the pointer to max_function_calls.
Implement owner-scoped state in __get__ per the agreed strategy, with the slots-only fallback and a non-raising answer for collisions. Keep __call__ semantics. Exclude runtime state from serialization.
Tests in python/packages/core/tests/core/test_tools.py:
repeated lookups share counters for both limits, sync and async;
class access;
equal and unhashable owners;
two owners and two descriptors on one class, plus an inherited/overridden one;
Scope estimate: small, roughly one function in _tools.py (and a small holder type), docstring updates, and a focused test file addition. Most of the effort is in the edge-case tests and the collision decision.
Decisions needed
Fresh binding with shared holder, or cached binding?
For slots-only owners and attribute-name collisions: fall back to uncached binding, or raise?
Should reset on a bound tool reset the owner-wide state? (My proposal: yes.)
Once these are answered, the plan above can be finalized.
Generated by Issue Planning for #8904 · copilot · auto · ~38 AIC · ⌖ ~1 AIC · ⊞ 4.8K · ◷
Activity
github-actions commentedon Sep 30, 2026
🤖 Automated triage reproduction notes (agent-authored — trust but verify)
Agent analysis
FunctionTool.get in python/packages/core/agent_framework/_tools.py:722-749 creates a fresh shallow copy whenever a decorated instance method is accessed, while FunctionTool.call updates counters only on that copy. The bug occurs when callers retrieve instance.method again between calls, bypassing both max_invocations and max_invocation_exceptions. Minimal repro: decorate an instance method with either limit set to 1 and invoke it twice through separate instance.method lookups.
python/packages/core/tests/core/test_tools.py1.19.01.19.0eavanvalkenburg commentedon Nov 3, 2026
Thanks for reporting this and for the work in #8951. We will consider persistent invocation and exception limits across repeated method-tool lookups as a core MAF capability. The exact counter lifetime, reset/copy behavior and support for different owner types still need agreement: current docs define limits per FunctionTool instance and describe a fresh binding on each lookup. This is not a promise of implementation or timing, approval of the current cache design, or a request for competing implementation. We will plan the compatibility boundary using the existing PR before marking it ready or assigning additional work.
eavanvalkenburg commentedon Nov 3, 2026
/plan Establish the accepted core counter/binding lifetime contract for #8904 through existing #8951, not competing implementation. Current main documents limits per FunctionTool instance and fresh descriptor bindings; retaining one binding already preserves counters. Core consideration now accepts investigating persistence across repeated lookups, not an unrestricted per-run/global cap or blanket cache-design approval. Compare fresh binding identity with owner-scoped counter state against cached binding identity. Define class access, invocation/exception counters, same/different/equal/unhashable owners, resets, shallow/deep copies and pickle semantics. Agree the slots-only/no-dict/no-weakref boundary: the current fallback does not preserve counters across lookups. Current 00338c8 addresses prior weak-key/pickle issues and prevents cache-name overwrites by raising; do not repeat resolved data-destruction findings, but decide whether that new binding failure for previously valid owners is acceptable or requires a non-colliding strategy. Cover GC, multiple/inherited descriptors, runtime metrics serialization, concurrency and documented batch overshoot without inventing strict security/rate-limit guarantees. Rebase the currently conflicted PR and run current-main-versus-candidate regressions; distinguish contributor-reported checks from new results. Update the exact public lifetime contract and consumer guidance. Keep #8911 per-run policy distinct. Estimate executable production scope after agreement; no ready label, new assignment or blanket PR approval yet.
eavanvalkenburg commentedon Nov 11, 2026
/plan Establish the accepted core counter/binding lifetime contract for #8904 through existing #8951, not competing implementation. Current main documents limits per FunctionTool instance and fresh descriptor bindings; retaining one binding already preserves counters. Core consideration now accepts investigating persistence across repeated lookups, not an unrestricted per-run/global cap or blanket cache-design approval. Compare fresh binding identity with owner-scoped counter state against cached binding identity. Define class access, invocation/exception counters, same/different/equal/unhashable owners, resets, shallow/deep copies and pickle semantics. Agree the slots-only/no-dict/no-weakref boundary: the current fallback does not preserve counters across lookups. Current 00338c8b addresses prior weak-key/pickle issues and prevents cache-name overwrites by raising; do not repeat resolved data-destruction findings, but decide whether that new binding failure for previously valid owners is acceptable or requires a non-colliding strategy. Cover GC, multiple/inherited descriptors, runtime metrics serialization, concurrency and documented batch overshoot without inventing strict security/rate-limit guarantees. Rebase the currently conflicted PR and run current-main-versus-candidate regressions; distinguish contributor-reported checks from new results. Update the exact public lifetime contract and consumer guidance. Keep #8911 per-run policy distinct. Estimate executable production scope after agreement; no ready label, new assignment or blanket PR approval yet.
github-actions commentedon Nov 11, 2026
Summary
Method tools (
@tool(max_invocations=...)on a method) lose their counters when the method is looked up again. Eachinstance.methodlookup returns a fresh copy of the tool, and counters live on that copy. This was confirmed in current main:FunctionTool.__get__(_tools.py~L848-878) doescopy.copy(self)and sets_instance.__call__(~L910-940) incrementsinvocation_count/invocation_exception_countonly on that copy. The docstring (~L709-722) says limits are per tool instance and never reset automatically. The_instanceand counters are not inDEFAULT_EXCLUDE, so check whetherto_dictserializes them.Per your direction, I did not read the #8951 diff or reviews. I also did not rebase it or run anything: this run is read-only and cannot execute code. So there are no new test results here, and any contributor-reported checks remain unverified.
Recommendation
Code change plus documentation is warranted, but only after the contract below is agreed. Today the limit works only if the caller keeps one bound object. The usual
tools=[svc.method]pattern silently does not enforce it, and the class-level counter stays at 0. A documentation-only fix would just document a footgun. This is a bounded, owner-scoped fix, not a general per-run/global cap (that stays in #8911).Proposed contract (for agreement)
Svc.methodreturns the unbound descriptor. Its counters are never incremented by bound calls. Document this and the oldSvc.ping.invocation_countexpectation.__eq__/__hash__. Two equal owners have separate counters. Unhashable owners work.Fresh binding with owner-scoped state vs. cached binding
__dict__or a weak map), and each choice has failure modes.Slots-only / no-dict / no-weakref owners
These owners cannot hold either a cache or a weak-key entry. Counters cannot be preserved across lookups for them. The fallback keeps the current behavior: it works, but the caller must retain the bound tool. Document this boundary clearly instead of promising more.
Commit 00338c8: raising on a name collision
I did not inspect it, so I only give the principle. Raising for owners that previously worked is a new failure. I would not accept that as the default. Prefer a non-colliding storage strategy (for example a name unique to the descriptor, or a framework-private holder). If no safe key exists, fall back to uncached binding rather than raise. I would accept raising only if you explicitly want fail-fast for pre-existing attribute clashes.
GC
State must not keep owners alive, so the owner must not be strongly referenced from a global map. Storing the holder on the owner, or using a weak map, both qualify. Tests should confirm the owner can be collected.
Proposed plan (nothing has been changed)
Agree the contract. The table above plus the three decisions below, recorded in the
FunctionToolandtool()docstrings and the core packageAGENTS.md. Keep the singleton caveat and the pointer tomax_function_calls.Implement owner-scoped state in
__get__per the agreed strategy, with the slots-only fallback and a non-raising answer for collisions. Keep__call__semantics. Exclude runtime state from serialization.Tests in
python/packages/core/tests/core/test_tools.py:to_dict/JSON;Regression comparison: run the same new tests against current main (expect failures that reproduce Python: [Bug]: max_invocations / max_invocation_exceptions are not enforced for tools defined as methods #8904) and against the candidate, plus the existing function-invocation tests. Report these as new results separate from contributor-reported ones.
Process: the existing PR has to be rebased first, since it is reported as conflicted. Keep Python: [Feature]: Scope tool invocation limits to the run/session instead of the FunctionTool instance #8911 out of scope. No ready label, assignment or PR approval until the contract is agreed.
Scope estimate: small, roughly one function in
_tools.py(and a small holder type), docstring updates, and a focused test file addition. Most of the effort is in the edge-case tests and the collision decision.Decisions needed
Once these are answered, the plan above can be finalized.