Agentes e aprovações

O Console foi feito para ser operado também por agentes: a CLI iugu em uma sessão de um agente de código, ou um assistente de IA conectado ao Iugu for AI, o servidor MCP do Console. Um agente faz o que a pessoa que o autorizou pode fazer — nada além — e o que é sensível não é executado por ele: vira um pedido que a pessoa aprova no navegador, com um segundo fator. Esta página descreve esse modelo.

A Lifecycle API

Agentes e CLI falam com a Lifecycle API, em https://api.console.iugu.com/v1, cujo contrato OpenAPI 3.1 está em api-v1.yaml. Cada operação declara três coisas:

A autorização de cada chamada é a interseção dos três: escopos do token ∩ áreas de trabalho consentidas ∩ permissões da pessoa. Nada que a pessoa não possa fazer no Console se torna possível por um agente.

Consentimento e agentes conectados

Um agente entra com o login da pessoa e um consentimento que cobre escopos × áreas de trabalho. Os escopos do Console:

Todo escopo de escrita implica console:read. Os consentimentos aparecem em Gerenciar Usuário → Agentes conectados: cada ferramenta ou assistente autorizado, com seus escopos e áreas de trabalho, e o botão para revogar o que a pessoa não reconhecer. Um consentimento é por portador de credencial — cada instalação da CLI ou de um assistente tem o seu; revogar um não afeta os outros.

Conjuntos de mudanças e aprovações

Uma operação de Tier 1 — credenciais, certificados, URL e callbacks OAuth, filtro por IPs, publicação, instalação de apps de terceiros, descarte de app, tokens de deploy e todas as escritas de GIA — responde 202 pending_approval com um conjunto de mudanças e a URL de aprovação. O agente entrega a URL à pessoa e espera; a pessoa abre https://console.iugu.com/workspace/approvals/<id>, vê exatamente o que será feito (o diff), quem pediu e por qual ferramenta, e escolhe Aprovar e aplicar ou Rejeitar.

• Aprovar exige o nível Gerenciamento de Configurações (um segundo fator recente) e todas as permissões das operações contidas — o Console só mostra o botão a quem pode.
• Um conjunto pode reunir várias operações e é aplicado de uma vez: um único pedido para “URL e callbacks + publicar + credencial de produção”.
• Segredos (o client_secret de uma credencial nova) são entregues uma única vez: ao cliente que pediu a mudança ou à CLI iugu do próprio solicitante — mesmo quando o pedido saiu de um assistente conectado ao Iugu for AI, iugu changeset secrets <id> --write-env .env.local na máquina do desenvolvedor grava o segredo sem exibi-lo — ou pela página de segredos da aprovação. Ficam disponíveis por uma hora após a aprovação; depois, é preciso pedir uma nova credencial. O assistente nunca recebe o segredo.
• Algumas operações exigem uma segunda pessoa (four_eyes): um membro mudando os próprios papéis não pode aprovar a si mesmo. O conjunto informa quem pode aprovar (approver_actions) e o Console notifica quem tem essa permissão.

Estados: Aguardando aprovação, Aprovado, Aplicado, Rejeitado, Expirado, Falhou.

Três pedidos que não exigem um novo login

Quando falta algo ao agente, a resposta traz uma URL e a pessoa resolve no navegador; o token do agente não muda, o consentimento sim:

Auditoria

Em Gerenciar Área de Trabalho → Auditoria fica a linha do tempo da área de trabalho: cada mudança por agente ou API, cada aprovação, cada chamada do Iugu for AI a um app (inclusive leituras) com os argumentos enviados, com filtros Iugu for AI, Aprovações, Agentes e API e Tudo, e no topo o que está Aguardando alguém — conjuntos de mudanças e confirmações pendentes. Quem tem console:workspace.audit.list vê tudo; os demais membros veem os próprios eventos. Os eventos são mantidos por 30 dias (configurável por área de trabalho) e também estão na API: GET /v1/workspaces/<id>/events.

Iugu for AI

O Iugu for AI é o servidor MCP do Console em https://mcp.console.iugu.com/mcp. Suas ferramentas são geradas do mesmo contrato da Lifecycle API e executadas com a mesma autorização — e, por meio do app Iugu for AI instalado em toda área de trabalho, ele também oferece as ações dos apps provedores (veja Expor ações) como ferramentas <tag>__<ação>, chamadas em nome da pessoa e sujeitas às permissões dela.

Para conectar um assistente:

# Claude Code (identifica-se pelo documento de metadados da Anthropic)
claude mcp add --transport http iugu https://mcp.console.iugu.com/mcp
# depois, dentro do Claude Code: /mcp → Authenticate

# Codex: em ~/.codex/config.toml
# [mcp_servers.iugu]
# url = "https://mcp.console.iugu.com/mcp"
# e então: codex mcp login iugu

# ou, para todos os assistentes instalados na máquina, com o roteiro embutido:
iugu agent setup --all

iugu agent setup escreve a entrada do servidor MCP e a skill da iugu para Claude Code, Codex, OpenCode, Cursor e VS Code (--print mostra os trechos sem gravar). O Claude Desktop é outro produto: seu claude_desktop_config.json só aceita servidores locais (stdio); o Iugu for AI entra pelo próprio aplicativo, em Settings → Connectors → Add custom connector com a URL acima — o consentimento OAuth acontece ali.

O que o assistente recebe do Iugu for AI ao conectar são as instruções do servidor (níveis, aprovações, nunca pedir segredos, as ações dos apps disponíveis) e a descrição de cada ferramenta; a skill da CLI só faz sentido para assistentes que executam comandos. Para ler essas instruções — e entregá-las de propósito a uma conversa — use o prompt iugu_guide que o servidor oferece (no Claude Desktop: + → Add from Iugu for AI). Uma ação elevada de um app provedor (config/transfers) leva a pessoa a uma página do Console que mostra o app, a ação, os argumentos exatos e a área de trabalho — ela confirma com o segundo fator, e a confirmação vale para uma única repetição da mesma chamada. Uma área de trabalho que não quer a ponte desinstala o app Iugu for AI.

Apps agindo por si e tokens de deploy