Começar · templates/eve-access-agent/README.md

Agente eve + Access#

Template de um agente eve já integrado ao Access: a pessoa entra no Access pela própria conversa, e cada ferramenta confere o papel dela antes de agir. Baixe pelo botão Baixar template do Access: na barra lateral, em Minhas sessões, na tela Integração ou na documentação.

Três coisas diferentes, cada uma no seu lugar:

O que respondeOnde fica
AutenticaçãoQuem é a pessoa?No Access. O agente nunca vê a senha.
PapéisQuais papéis ela tem nesta organização?No Access (tela Papéis e Membros).
AutorizaçãoEla pode fazer esta ação?Aqui, no código do agente: agent/lib/policy.ts e cada ferramenta.

Começar#

Requer Node.js 24+ e uma conta no Access que participe da organização.

  1. Junte os valores do .env:

    • Se você administra a organização: na tela Integração, crie a chave do agente. Ela aparece uma única vez, já dentro do .env pronto para copiar.
    • Se você não administra: em Minhas sessões está o ACCESS_ORGANIZATION_ID de cada organização. Peça ao administrador a chave da integração (ACCESS_CHANNEL_KEY) e o slug do papel que o agente vai exigir. ACCESS_BASE_URL é o endereço do Access, sem /api.
  2. Configure e instale:

    bash
    cp .env.example .env    # cole os valores; gere ACCESS_GRANTS_SECRET com: openssl rand -hex 32
    npm install
  3. Em agent/lib/policy.ts, troque "financeiro" pelo slug real de um papel da sua organização (tela Papéis, ou pergunte ao administrador).

  4. Rode e converse:

    bash
    npm run dev

    Peça “quero entrar” ou “aprove o reembolso do pedido 42 de R$ 30”. O eve mostra um link para entrar no Access; entre, confirme o agente e volte: o turno continua sozinho. Com o papel, a ferramenta aprova (é uma simulação). Sem o papel, ela nega e explica o motivo.

eve dev cuida das credenciais do modelo (abre /login no terminal se for preciso). Para trocar de modelo, use /model ou edite agent/agent.ts.

Como funciona#

text
pessoa ──mensagem──▶ canal eve ──▶ modelo ──▶ ferramenta aprovar_reembolso
                                                │ access.requireRole(ctx, "financeiro")
                                                ▼
                          sem sessão? eve pede "Entrar com Access" em privado
                          pessoa entra e confirma no Access ──▶ callback do eve
                          agente troca o código por uma sessão (guardada cifrada)
                                                │
                                                ▼
                          GET /api/v1/identity → { userId, roles }
                          papel na política? executa : nega (nada acontece)
ArquivoPapel
agent/lib/access-client.tsCliente HTTP do Access (identidade, login pelo navegador). Código do kit, verificado.
agent/lib/eve-access-login.tsLogin interativo do eve com o Access (defineInteractiveAuthorization). Código do kit.
agent/lib/access-sign-in.tsLê a configuração e cria access.identify / access.requireRole.
agent/lib/access-grants.tsOnde ficam as sessões Access das pessoas: cifradas, separadas por Access e organização, com expiração, fora do modelo.
agent/lib/policy.tsSua política: qual papel cada ferramenta exige.
agent/lib/protect.tsO formato de toda ferramenta protegida: protect (exige papel) e identified (só identifica).
agent/lib/denials.tsMensagem segura quando o Access nega.
agent/lib/local-developer.ts, direct-local.tsEm eve dev, trata você como uma pessoa que pode entrar, só em chamadas diretas da máquina.
agent/channels/eve.tsQuem pode chamar a API HTTP do agente.
agent/tools/minha_identidade.tsEntrar e ver os próprios papéis.
agent/tools/aprovar_reembolso.tsExemplo de ferramenta com efeito protegida por papel.
.agents/skills/eve-access-integration/Kit para o seu agente de código (Claude Code, Codex…) estender a integração.

Adicionar uma ferramenta protegida#

  1. Acrescente a ferramenta e o slug em agent/lib/policy.ts.
  2. Copie agent/tools/aprovar_reembolso.ts: o efeito vai dentro de protect(access, ctx, REQUIRED_ROLES.x, identity => …), que consulta o papel imediatamente antes, transforma negações do Access em denial(...) e deixa passar o resto (é assim que o eve pausa o turno para pedir a entrada).
  3. Papel não substitui propriedade: filtre os dados por identity.organizationId e, quando fizer sentido, por identity.userId.

Peça ao seu agente de código: “leia .agents/skills/eve-access-integration/SKILL.md e crie a ferramenta X exigindo o papel Y”.

Não exponha a API HTTP do eve dev por um túnel (ngrok, cloudflared) para entrar por ela: chamadas que passam por túnel ou proxy não contam como você e são recusadas. Do contrário, quem tivesse a URL usaria a sua sessão no Access.

Canais de chat#

O login funciona em qualquer canal do eve que identifique o remetente (Telegram, Slack, WhatsApp via Chat SDK, Twilio). Adicione um canal com npx eve add <canal> (veja node_modules/eve/docs/channels/). O pedido de entrada é enviado em privado; nunca no grupo nem ao modelo.

Publicar#

  • Configure as mesmas variáveis no provedor. Troque ACCESS_BASE_URL pelo domínio de produção do Access e crie uma integração própria para produção.
  • As sessões precisam de um armazenamento compartilhado: Redis REST (ACCESS_GRANTS_REDIS_REST_URL/_TOKEN, ou as variáveis KV_REST_API_* / UPSTASH_REDIS_REST_* que a Vercel cria ao conectar um Redis Upstash). Sem isso, fora do eve dev, a primeira entrada falha e nada é executado.
  • npx eve deploy publica na Vercel.

Testar#

bash
npm test          # sessões, protect, chamadas locais e clientes do kit, com respostas simuladas
npm run typecheck

Os testes não chamam o Access. Antes de usar com dados reais, faça o roteiro de .agents/skills/eve-access-integration/references/acceptance.md com uma conta de aula: sem papel nega, encerrar a sessão em Minhas sessões no Access faz a próxima ferramenta pedir nova entrada, remover a pessoa da organização nega.

Limites#

  • O Access devolve identidade e papéis, nunca decisões. A regra é sua.
  • Autenticar a rota não isola conversas: se você expuser a API HTTP a várias pessoas por um app web, associe cada sessão eve a (issuer, organizationId, userId) no seu servidor (veja references/integration.md do kit).
  • Turnos de agendamento não pedem entrada: ferramentas protegidas falham neles.