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 responde | Onde fica | |
|---|---|---|
| Autenticação | Quem é a pessoa? | No Access. O agente nunca vê a senha. |
| Papéis | Quais papéis ela tem nesta organização? | No Access (tela Papéis e Membros). |
| Autorização | Ela 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.
-
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
.envpronto para copiar. - Se você não administra: em Minhas sessões está o
ACCESS_ORGANIZATION_IDde 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.
- Se você administra a organização: na tela Integração, crie a chave
do agente. Ela aparece uma única vez, já dentro do
-
Configure e instale:
bashcp .env.example .env # cole os valores; gere ACCESS_GRANTS_SECRET com: openssl rand -hex 32 npm install -
Em
agent/lib/policy.ts, troque"financeiro"pelo slug real de um papel da sua organização (tela Papéis, ou pergunte ao administrador). -
Rode e converse:
bashnpm run devPeç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#
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)| Arquivo | Papel |
|---|---|
agent/lib/access-client.ts | Cliente HTTP do Access (identidade, login pelo navegador). Código do kit, verificado. |
agent/lib/eve-access-login.ts | Login interativo do eve com o Access (defineInteractiveAuthorization). Código do kit. |
agent/lib/access-sign-in.ts | Lê a configuração e cria access.identify / access.requireRole. |
agent/lib/access-grants.ts | Onde ficam as sessões Access das pessoas: cifradas, separadas por Access e organização, com expiração, fora do modelo. |
agent/lib/policy.ts | Sua política: qual papel cada ferramenta exige. |
agent/lib/protect.ts | O formato de toda ferramenta protegida: protect (exige papel) e identified (só identifica). |
agent/lib/denials.ts | Mensagem segura quando o Access nega. |
agent/lib/local-developer.ts, direct-local.ts | Em eve dev, trata você como uma pessoa que pode entrar, só em chamadas diretas da máquina. |
agent/channels/eve.ts | Quem pode chamar a API HTTP do agente. |
agent/tools/minha_identidade.ts | Entrar e ver os próprios papéis. |
agent/tools/aprovar_reembolso.ts | Exemplo 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#
- Acrescente a ferramenta e o slug em
agent/lib/policy.ts. - Copie
agent/tools/aprovar_reembolso.ts: o efeito vai dentro deprotect(access, ctx, REQUIRED_ROLES.x, identity => …), que consulta o papel imediatamente antes, transforma negações do Access emdenial(...)e deixa passar o resto (é assim que o eve pausa o turno para pedir a entrada). - Papel não substitui propriedade: filtre os dados por
identity.organizationIde, quando fizer sentido, poridentity.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_URLpelo 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áveisKV_REST_API_*/UPSTASH_REDIS_REST_*que a Vercel cria ao conectar um Redis Upstash). Sem isso, fora doeve dev, a primeira entrada falha e nada é executado. npx eve deploypublica na Vercel.
Testar#
npm test # sessões, protect, chamadas locais e clientes do kit, com respostas simuladas
npm run typecheckOs 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 (vejareferences/integration.mddo kit). - Turnos de agendamento não pedem entrada: ferramentas protegidas falham neles.