Agentes e concessões permanentes — Documentação

Nenhum humano no circuito — por design

O CommandAGI foi feito para máquinas que funcionam sem supervisão. Um agente que tem uma concessão arma uma unidade, executa programas e envia comandos em tempo real, pela bancada de trabalho, pela API ou pelo MCP, sem uma confirmação para cada ação. O que mantém isso seguro não é uma pessoa observando; são a concessão, os limites do driver e o registro.

Principais

Tudo que age é um principal: agent:<name> ou person:<name>. Um principal prova quem é com uma credencial — nunca apenas diz quem é. Um pedido que só diz quem é é recusado.

Credencial do host — cagp_…, emitida uma vez por commandagi grant token --principal agent:<name> (ou quando uma concessão é adicionada). O host guarda apenas o SHA-256 dela. grant token a renova; grant forget a remove.
Credencial da conta — cagc.<payload>.<signature>, assinada com a chave da sua conta (Ed25519) para agentes que rodam na nuvem. Ela nomeia o principal, a conta, uma validade e, opcionalmente, um host, e só é aceita para concessões que aquela conta fez. Revogue uma com grant revoke-credential.

Concessões permanentes

Uma concessão permanente é autoridade que uma conta dá a um principal, feita por um ato explícito de uma pessoa. Nenhuma rota de ferramenta ou agente cria ou amplia uma concessão; a chave de API de um agente é recusada em toda rota que muda autoridade.

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

Uma concessão nomeia um mundo e, opcionalmente, unidades, canais e verbos — deixar um deles de fora significa todos. Ela pode expirar (--for 8h, --expires <ISO time>). As concessões ficam em ~/.commandagi/grants.json, são lidas a cada ação, e também podem ser feitas na bancada de trabalho em configurações → concessões. Um arquivo de concessões malformado não honra concessão alguma.

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

O mesmo comando faz três outros tipos de concessão: --file PREFIX… (escrever arquivos sob um caminho), --outreach APP… --per-day N (enviar mensagens por aplicativos conectados) e --market VENUE… --symbol S --max-qty N --max-notional N --per-day N (fazer pedidos).

As concessões se aplicam a mundos físicos. Um mundo de simulação não precisa de nenhuma.

Verbos, armação e segurança

Uma concessão pode dar quatro verbos: abrir um canal, armar uma unidade, executar um programa, enviar um comando.

Drivers que movem hardware abrem desarmados. Qualquer principal com uma concessão sobre a unidade pode armá-la. Uma sessão armada que fica ociosa por cinco minutos se desarma sozinha.
Drivers que só recebem entrada — um shell, um kernel Python, uma entrega de job — não precisam de armação; a concessão é verificada a cada entrada.
A segurança é sempre permitida. stop, disarm e close — e comandos de segurança como retenção de avanço, pausa, parada de emergência e torque desligado — são permitidos a qualquer um com uma concessão não expirada sobre a unidade, a quem abriu a sessão e à pessoa da própria conta. Cancelar uma ordem em aberto também é segurança.

As regras que toda ação segue

Registrada antes de ser enviada. Antes que o driver seja chamado, uma nota — o principal e a ação — é anexada ao fluxo da execução e gravada em disco. Um projeto somente leitura recusa a ação em vez de agir sem registro.
Um reconhecimento não é um estado. Uma resposta ou ok nunca implica que o estado pedido foi atingido. Comandos ficam pendentes até a máquina informar um estado.
Desconhecido continua desconhecido. Um link perdido é registrado como state: unknown. Um fluxo que terminou sem um registro de fim lê-se interrompido: estado desconhecido.
Sem repetições silenciosas. Um comando físico nunca é repetido pelo sistema. Um agente pode decidir tentar de novo; essa decisão é um comando próprio, registrado.
Os limites são trabalho do driver. Limites, intervalos e verbos permitidos declarados são aplicados pelo driver, não por uma pessoa. Fluxos de entrada são espaçados: uma ação por vez, com pelo menos 30 ms entre elas.
Simulado e físico nunca se misturam. Uma execução pertence a um mundo, e a fonte dos registros precisa corresponder ao tipo do mundo.

Conversas e o agente delas

Iniciar uma conversa em um mundo físico concede ao agente da conversa (threads.agent, agent:mcp por padrão) todos os verbos sobre as unidades daquele mundo, por no máximo 24 horas, e revoga a concessão quando a conversa é encerrada. Desligue isso com a configuração "threads.agentControl": false.

Conecte um agente a tudo isso pelo MCP: SDK e MCP.

Agentes e concessões permanentes.