google / google/adk-python-community

feat(plugins): add AuthorityRoutingPlugin — pre-execution authority posture (ADVISE/EXECUTE/DEFER/STOP)

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

説明

## Problem

Tool schemas and permissions govern *access* — which tools exist and who may call them. They do not govern *authorization*: whether the agent was allowed to act **at all** for a given request, and within what scope. That gap is where three recurring agent failures live:

- **advice becomes action** — the user asked for a recommendation and the agent executed anyway;
- **scope expansion** — one bounded edit ballooned into a dependent workflow;
- **missing approval** — an approval was clearly required and the agent proceeded.

`AgentGovernancePlugin` (policy-as-code allow/deny) and the HITL approval gateway answer *"is this tool call permitted by policy?"*. Neither answers *"was the agent authorized to act at all, and within what scope?"* — and both require external infrastructure (a policy engine / an approval service).

## Proposal

Add `AuthorityRoutingPlugin`, a self-contained `BasePlugin` that assigns an **authority posture** to every tool call before it runs:

| Posture | Meaning |
| --- | --- |
| ADVISE | Recommendations only; no tool side effects. |
| EXECUTE | Act, within an explicitly bounded scope. |
| DEFER | Pause and request authorization when scope/approval is unclear. |
| STOP | Refuse when the work is not allowed. |

Two stages produce the final posture:

1. **Posture router** (optional, caller-supplied callable — typically a model call) returning a validated verdict with a scope statement.
2. **Deterministic guard** — an irreversibility keyword tripwire + an approval-state check — composed with the router under **most-restrictive-wins**: plain code can only make a posture *stricter*, never looser.

Design properties:

- **Fail-closed** — an unparseable or raised router verdict defaults to DEFER.
- **Guard-only mode** (no router) is fully deterministic and needs no model and no extra dependency.
- Complements, rather than duplicates, the existing governance plugins.

## Scope

- `src/google/adk_community/plugins/authority_routing_plugin.py` + export
- `tests/plugins/test_authority_routing_plugin.py` (deterministic, no credentials)
- `contributing/samples/authority_routing/` (runnable sample with live output)

Happy to adjust the API surface or placement to match maintainer preferences. I have an implementation ready and will open a PR referencing this issue.

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

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

調査の方向性

まず既存の BasePlugin と governance plugin の動作を読み、次に src/google/adk_community/plugins/authority_routing_plugin.py と tests/plugins/test_authority_routing_plugin.py にある提案されたパスを確認します。posture routing、fail-closed 処理、不可逆性トリップワイヤ、承認チェック、最も制限の厳しいものを優先する動作について決定論的なテストを追加し、contributing/samples/authority_routing/ に実行可能なサンプルも追加します。プラグインがエクスポートされ、サンプルが認証情報なしでライブ出力を生成すれば完了です。

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

評価

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

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

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