Agents et autorisations permanentes — Documentation

Pas d’humain dans la boucle — par conception

CommandAGI est conçu pour des machines qui tournent sans surveillance. Un agent qui détient une autorisation arme une unité, lance des programmes et envoie des commandes en temps réel, par l’atelier, l’API ou MCP, sans confirmation pour chaque action. Ce qui assure la sécurité, ce n’est pas une personne qui regarde ; ce sont l’autorisation, les limites du pilote et l’enregistrement.

Mandants

Tout ce qui agit est un mandant : agent:<name> ou person:<name>. Un mandant prouve qui il est avec un justificatif — il ne se contente jamais de se nommer. Une demande qui ne fait que dire qui elle est est refusée.

Justificatif d’hôte — cagp_…, émis une seule fois par commandagi grant token --principal agent:<name> (ou lorsqu’une autorisation est ajoutée). L’hôte ne stocke que son SHA-256. grant token le renouvelle ; grant forget le supprime.
Justificatif de compte — cagc.<payload>.<signature>, signé avec la clé de votre compte (Ed25519) pour les agents qui tournent dans le cloud. Il nomme le mandant, le compte, une date d’expiration et, facultativement, un hôte. Il n’est accepté que pour les autorisations que ce compte a accordées. Révoquez-en un avec grant revoke-credential.

Autorisations permanentes

Une autorisation permanente est une autorité qu’un compte donne à un mandant, par un acte explicite d’une personne. Aucun outil ni aucune route d’agent ne crée ni n’élargit une autorisation ; la clé d’API d’un agent est refusée sur chaque route qui modifie l’autorité.

shell

commandagi grant add --principal agent:night-shift \
  --world shop --unit mill-1 --channel gcode \
  --verb open --verb arm --verb run --verb send \
  --for 8h --note "night shift"
commandagi grant list
commandagi grant revoke g-3f9a1c20b7de

Une autorisation nomme un monde et, facultativement, des unités, des canaux et des verbes. Si vous en omettez un, il vaut pour tous. Elle peut expirer (--for 8h, --expires <heure ISO>). Les autorisations sont conservées dans ~/.commandagi/grants.json, lues à chaque action, et peuvent aussi être créées dans l’atelier, sous paramètres → autorisations. Un fichier d’autorisations mal formé n’accorde aucune autorisation.

json

{ "grants": [ { "id": "g-3f9a1c20b7de", "principal": "agent:night-shift",
  "grantedBy": "acct:user:u_8f2k", "world": "shop", "units": ["mill-1"],
  "channels": ["gcode"], "verbs": ["open", "arm", "run", "send"],
  "expires": "2026-10-01T06:00:00Z", "note": "night shift" } ] }

La même commande crée trois autres types d’autorisation : --file PREFIX… (écrire des fichiers sous un chemin), --outreach APP… --per-day N (envoyer des messages par des applications connectées) et --market VENUE… --symbol S --max-qty N --max-notional N --per-day N (passer des ordres).

Les autorisations s’appliquent aux mondes physiques. Un monde de simulation n’en a pas besoin.

Verbes, armement et mise en sécurité

Une autorisation peut donner quatre verbes : ouvrir (open) un canal, armer (arm) une unité, lancer (run) un programme, envoyer (send) une commande.

Les pilotes qui déplacent du matériel s’ouvrent désarmés. Tout mandant qui a une autorisation sur l’unité peut l’armer. Une session armée restée inactive pendant cinq minutes se désarme seule.
Les pilotes qui ne font que recevoir une entrée — un shell, un noyau Python, un transfert de tâche — n’ont pas besoin d’armement ; l’autorisation est vérifiée à chaque entrée.
La mise en sécurité est toujours permise. stop, disarm et close, ainsi que les commandes de mise en sécurité comme la mise en attente de l’avance, la pause, l’arrêt d’urgence et la coupure du couple, sont permis à quiconque détient une autorisation non expirée sur l’unité, à la personne qui a ouvert la session et à la personne du compte. Annuler un ordre en attente est aussi une mise en sécurité.

Les règles que suit chaque action

Enregistrée avant l’envoi. Avant que le pilote soit appelé, une note — le mandant et l’action — est ajoutée au flux de l’exécution, puis écrite sur le disque. Un projet en lecture seule refuse l’action plutôt que d’agir sans enregistrement.
Un accusé de réception n’est pas un état. Une réponse ou un ok n’indique jamais que l’état commandé a été atteint. Les commandes restent en attente jusqu’à ce que la machine signale un état.
L’inconnu reste inconnu. Une liaison perdue est enregistrée comme state: unknown. Un flux qui se termine sans enregistrement de fin se lit interrompu : état inconnu.
Aucun nouvel essai silencieux. Une commande physique n’est jamais relancée par le système. Un agent peut décider de réessayer ; cette décision devient sa propre commande, enregistrée.
Les limites relèvent du pilote. Les limites, intervalles et verbes autorisés déclarés sont appliqués par le pilote, pas par une personne. Les flux d’entrée sont cadencés : une action à la fois, à au moins 30 ms d’intervalle.
Simulé et physique ne se mélangent jamais. Une exécution appartient à un seul monde, et la source de ses enregistrements doit correspondre au type de ce monde.

Conversations et leur agent

Démarrer une conversation dans un monde physique accorde à l’agent de la conversation (threads.agent, agent:mcp par défaut) chaque verbe sur les unités de ce monde, pour 24 heures au plus. Cette autorisation est révoquée lorsque la conversation se ferme. Désactivez-la avec le paramètre "threads.agentControl": false.

Suite

Connectez un agent à tout cela par MCP : SDK et MCP.

Agents et autorisations permanentes.