google / google/adk-python-community

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

Ouverte
#171 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
Python
Étoiles
182
Forks
75
Métriques de merge des PR
Aucune PR mergée en 30 j

Description

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

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

Commencez par lire le comportement existant de BasePlugin et du plugin de gouvernance, puis examinez les chemins proposés dans src/google/adk_community/plugins/authority_routing_plugin.py et tests/plugins/test_authority_routing_plugin.py. Ajoutez des tests déterministes pour le routage de posture, la gestion fail-closed, le garde-fou d'irréversibilité, les vérifications d'approbation et le comportement selon lequel la règle la plus restrictive l'emporte, ainsi que l'exemple exécutable sous contributing/samples/authority_routing/. La tâche est terminée lorsque le plugin est exporté et que l'exemple produit une sortie en direct sans identifiants.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
security
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
Calme
Clarté
Plutôt claire
Accessibilité débutants
45/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.