Agentes y permisos permanentes — Documentación

Sin humanos en el bucle — por diseño

CommandAGI está hecho para máquinas que funcionan sin supervisión. Un agente que tiene un permiso arma una unidad, ejecuta programas y envía comandos en tiempo real, desde el banco de trabajo, la API o MCP, sin una confirmación por cada acción. Lo que lo mantiene seguro no es una persona vigilando; es el permiso, los límites del driver y el registro.

Principales

Todo lo que actúa es un principal: agent:<name> o person:<name>. Un principal demuestra quién es con una credencial — nunca se limita a nombrarse. Una petición que solo dice quién es se rechaza.

Credencial de host — cagp_…, emitida una sola vez por commandagi grant token --principal agent:<name> (o al añadir un permiso). El host guarda solo su SHA-256. grant token la rota; grant forget la elimina.
Credencial de cuenta — cagc.<payload>.<signature>, firmada con la clave de tu cuenta (Ed25519) para agentes que se ejecutan en la nube. Nombra al principal, la cuenta, una caducidad y, opcionalmente, un host, y solo se acepta para permisos creados por esa cuenta. Revócala con grant revoke-credential.

Permisos permanentes

Un permiso permanente es la autoridad que una cuenta otorga a un principal, creada mediante un acto explícito de una persona. Ninguna herramienta ni ruta de agente crea o amplía un permiso; la clave de API de un agente se rechaza en todas las rutas que cambian la autoridad.

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

Un permiso nombra un mundo y, opcionalmente, unidades, canales y verbos — omitir uno significa todos. Puede caducar (--for 8h, --expires <ISO time>). Los permisos se guardan en ~/.commandagi/grants.json, se leen en cada acción y también pueden crearse en el banco de trabajo, en ajustes → permisos. Si el archivo de permisos está mal formado, no se acepta ningún permiso.

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" } ] }

El mismo comando crea otros tres tipos de permiso: --file PREFIX… (escribir archivos bajo una ruta), --outreach APP… --per-day N (enviar mensajes a través de apps conectadas) y --market VENUE… --symbol S --max-qty N --max-notional N --per-day N (colocar órdenes).

Los permisos se aplican a mundos físicos. Un mundo de simulación no necesita ninguno.

Verbos, armado y puesta en seguro

Un permiso puede dar cuatro verbos: open (abrir) un canal, arm (armar) una unidad, run (ejecutar) un programa, send (enviar) un comando.

Los drivers que mueven hardware se abren desarmados. Cualquier principal con un permiso sobre la unidad puede armarla. Una sesión armada que pasa cinco minutos inactiva se desarma sola.
Los drivers que solo reciben entrada — una shell, un kernel de Python, una entrega de trabajos — no necesitan armado; el permiso se comprueba en cada entrada.
Poner en seguro siempre está permitido. stop, disarm y close — y comandos de puesta en seguro como la retención de avance, la pausa, la parada de emergencia y la desactivación del par — están permitidos a cualquiera que tenga un permiso vigente sobre la unidad, a quien abrió la sesión y a la persona titular de la cuenta. Cancelar una orden pendiente también es poner en seguro.

Las reglas que sigue cada acción

Registrada antes de enviarse. Antes de llamar al driver, se añade al flujo de la ejecución una nota — el principal y la acción — y se vuelca a disco. Un proyecto de solo lectura rechaza la acción en lugar de actuar sin registro.
Una confirmación no es un estado. Una respuesta o un ok nunca implica que se alcanzó el estado ordenado. Los comandos quedan pendientes hasta que la máquina reporta un estado.
Lo desconocido se mantiene desconocido. Un enlace perdido se registra como state: unknown. Un flujo que terminó sin registro de fin se lee como interrumpido: estado desconocido.
Sin reintentos silenciosos. El sistema nunca reintenta un comando físico. Un agente puede decidir volver a intentarlo; esa decisión es un comando registrado por sí mismo.
Los límites son tarea del driver. Los límites declarados, los intervalos y los verbos permitidos los impone el driver, no una persona. Los flujos de entrada van a ritmo controlado: una acción cada vez, con al menos 30 ms de separación.
Lo simulado y lo físico nunca se mezclan. Una ejecución pertenece a un solo mundo, y la fuente de sus registros debe coincidir con el tipo del mundo.

Los hilos y su agente

Iniciar un hilo en un mundo físico otorga al agente del hilo (threads.agent, agent:mcp por defecto) todos los verbos sobre las unidades de ese mundo, durante un máximo de 24 horas, y los revoca cuando el hilo se cierra. Desactívalo con el ajuste "threads.agentControl": false.

Conecta un agente a todo esto por MCP: SDK y MCP.