google / google/adk-python-community

feat(plugins): optional SeenRelay ambient measurement for repeated read-only tool calls

オープン
#183 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
主要言語
Python
スター
182
フォーク
75
PR マージ指標
30日以内にマージされた PR はありません

説明

## 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.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
python
領域
tooling
issue の種類
機能追加
難易度
5/5
見積もり時間
1週間以上
活発さ
活発
明瞭さ
おおむね明確
初心者へのやさしさ
45/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。