Pigeon : donner à tes agents IA juste ce qu'il faut, pas tout

Le problème : héritage total de permissions

Quand un agent lance un sous-agent, la pratique courante est de lui passer la même clé API. Résultat : le sous-agent peut faire tout ce que toi tu peux faire. S'il se fait pirater ou si son prompt se fait injecter, c'est la catastrophe — accès prod, base de paiements, merge sur main.

La solution : Pass signé et restreint

Pigeon fonctionne en deux temps :

1. ▸

   Délégation : au lieu de copier une clé, tu crées un Pass signé qui dit exactement ce que le sous-agent peut faire.

   parent = grant(subject="agent:orchestrator", 
                  capabilities=["deploy", "open_pr"],
                  resources=["environment:staging", "repo:acme/api"])
   
   worker = delegate(parent, 
                     subject="agent:pr-bot",
                     capabilities=["open_pr"],  # restreint
                     resources=["repo:acme/api"])
   

2. ▸

   Vérification : chaque fois qu'une action sensible arrive, tu appelles verify(). Si elle dépasse le Pass, elle est refusée avec une raison claire.

   result = verify(worker, action="open_pr", resource="repo:acme/api")
   # allowed = True
   
   denied = verify(worker, action="deploy", resource="environment:staging")
   # allowed = False, reason_code = "CAPABILITY_NOT_GRANTED"
   

Pourquoi c'est mieux qu'une simple liste blanche

• ▸Signé : le Pass est cryptographiquement lié au sujet et aux contraintes. Impossible de modifier.
• ▸Impossible d'escalader : un sous-agent ne peut pas ajouter de permissions, élargir les ressources, ou retirer une limite imposée par le parent. Pigeon le détecte et refuse.
• ▸Raison de refus explicite : au lieu d'un simple booléen, tu obtiens le code exact du problème (CAPABILITY_NOT_GRANTED, RESOURCE_NOT_ALLOWED, etc.) et les détails de ce qui a échoué.

Intégration MCP : point de contrôle pour les outils

Si tu utilises le protocole MCP (Model Context Protocol), tu peux placer Pigeon comme point de contrôle avant chaque appel d'outil :

from pigeon.integrations.mcp import execute_tool, pass_for_tool

parent = grant(subject="agent:github", 
               capabilities=["create_issue", "merge_pr"],
               resources=["mcp:github"])

tool_pass = pass_for_tool(parent, "create_issue", "mcp:github")
result = execute_tool(tool_pass, "create_issue", "mcp:github", 
                      {"title": "fix", "body": "auto"}, create_issue_fn)

Le client crée un Pass spécifique pour cet appel d'outil. Le serveur vérifie avant d'exécuter. Zéro surcharge.

Ce que Pigeon n'est pas

C'est une primitive légère, pas une plateforme complète. Il ne remplace pas un vrai système d'identité, un moteur de politiques, ou une gestion de clés. Il ne stoppe pas les injections de prompt. Il limite juste le rayon d'impact selon les dimensions que tu mets dans le Pass.

Installation rapide

pip install pigeon
git clone https://github.com/pigeonlabsHQ/pigeon.git
cd pigeon && python examples/01_infrastructure.py

Consulte SECURITY.md pour comprendre les limites exactes.