google / google/adk-python-community
feat(plugins): optional SeenRelay ambient measurement for repeated read-only tool calls
- Lingua principale
- Python
- Stelle
- 182
- Fork
- 75
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Descrizione
## Problem
ADK applications can execute the same deterministic, read-only tool validation more than once. Whether that repetition is actually worth optimizing is workload-specific, and short-circuiting tool execution before measuring equivalence would be unsafe.
## Proposal
Would an optional `SeenRelayAmbientPlugin` fit `google.adk_community.plugins` as a third-party integration for measuring exact repeated read-only tool validations before any reuse policy is considered?
The proposed initial integration is deliberately local and shadow-only:
- the application supplies an explicit allowlist of tool names it has classified as read-only validation operations;
- the plugin uses ADK `before_tool_callback`, `after_tool_callback`, and `on_tool_error_callback` lifecycle hooks;
- an exact local coordinate is derived from tool name plus JSON-serializable arguments;
- returned JSON is fingerprinted and compared only with prior local fingerprints;
- only bounded fingerprints and aggregate counters are retained in memory;
- raw tool arguments and raw results are not retained in the report/state;
- unsupported/non-JSON values fail open and preserve normal ADK behavior;
- the plugin always returns `None`, so it never replaces a tool result, short-circuits execution, mutates arguments, or handles failures;
- it performs no hosted SeenRelay `CHECK` or `OBSERVE` operation and authorizes no automatic reuse.
The optional Python dependency would be `seenrelay>=0.2.13,<1`; the default client package has no required dependencies and is MIT-licensed.
## Proposed scope
- `src/google/adk_community/plugins/seenrelay_ambient_plugin.py`
- export from `google.adk_community.plugins`
- `seenrelay` optional dependency extra
- focused plugin tests
No active validation suppression, network reuse policy, tool mutation, or result caching is proposed.
## Compatibility evidence
A compatibility candidate was exercised against Google ADK 2.8.0 at exact source commit `6de43b05a07f8ca89909664b3a21049646d7336c` using the real ADK `PluginManager`. The compatibility suite passed cases covering authoritative execution on exact repeats, changed-result handling, distinct arguments, fail-open unsupported input, bounded state, raw-data non-retention, and tool-error behavior.
If this shape fits the community repository, I have a focused implementation and tests ready in my fork and can open the PR after maintainers confirm the placement/API direction.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Start with the proposed src/google/adk_community/plugins/seenrelay_ambient_plugin.py path, the google.adk_community.plugins export, and ADK's before_tool_callback, after_tool_callback, and on_tool_error_callback hooks. Review the focused plugin tests and compatibility evidence, then confirm the placement and API direction with maintainers. Done means an optional, local shadow-only integration with bounded non-raw state that preserves normal tool behavior.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- tooling
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Attiva
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 45/100