Eve: Guia Definitivo — O Framework Filesystem-First da Vercel

TL;DR: Eve é o framework TypeScript open-source (Apache 2.0) da Vercel que trata cada agente como um diretório de arquivos — instructions.md, tools/.ts, skills/.md, channels/.ts, subagents/, schedules/*.ts. Anunciado em 17 de junho de 2026 no Ship London, roda sobre Vercel Workflow (durabilidade), Vercel Sandbox (isolamento microVM) e AI Gateway (model routing via OIDC). Sessions sobrevivem a crashes e redeploys, approvals pausam sem consumir compute, e deploy é vercel deploy. A Vercel já roda 100+ agentes internos no Eve — incluindo o d0 (30K+ perguntas/mês) e o Vertex (92% dos tickets resolvidos solo). Se você vive no ecossistema Vercel e quer construir agentes de produção sem montar a infraestrutura do zero, Eve é a aposta mais coerente do mercado. O trade-off? Lock-in. Você está trocando liberdade de runtime por DX excepcional.

A filosofia: filesystem-first como abstração de agente

Tem uma frase do post oficial da Vercel que resume tudo:

“Next.js ended this for the web, and eve is doing the same for agents.”

Ousada? Sim. Mas quando você entende o padrão mental, faz sentido. Assim como o Next.js transformou um diretório pages/ em rotas HTTP sem que você configurasse um router, Eve transforma um diretório agent/ em um agente completo de produção sem que você monte filas, configure runtimes ou escreva boilerplate de registro de ferramentas.

O core insight é que agentes têm forma. Depois de construir centenas de agentes internamente, a Vercel percebeu que todos compartilhavam a mesma anatomia:

• Um modelo
• Instruções (prompt de sistema)
• Ferramentas (ações tipadas)
• Skills (conhecimento sob demanda)
• Canais de entrada (Slack, HTTP, GitHub…)
• Agendamentos (cron)
• Sub-agentes (delegação)

Eve é essa anatomia codificada como convenção de filesystem. Você descreve o que o agente faz. O framework cuida do como.

A relação com o AI SDK 7

Eve não existe no vácuo. Ele é construído sobre o AI SDK — a mesma biblioteca TypeScript que hoje puxa mais de 16 milhões de downloads semanais e que, com a versão 7 (lançada em 25 de junho de 2026), evoluiu de primitivas de chat para uma plataforma completa de agentes.

A relação é clara: o AI SDK é a camada de abstração de modelos e tool calling. Eve é a camada de framework opinado construída em cima, assim como o Next.js é um framework opinado sobre React. Se você precisa de controle total e quer montar seu próprio harness, use o AI SDK diretamente. Se quer convenções de produção resolvidas, use Eve.

Para quem acompanha o ecossistema de agent frameworks, essa separação de camadas é familiar — e essencial para entender onde Eve se posiciona.

Tutorial: do init ao deploy em 10 minutos

Pré-requisitos

• Node.js 20+
• pnpm (ou npm)
• TypeScript fluente
• Conta Vercel (gratuita, para deploy)
• Nenhuma API key de provedor necessária (AI Gateway + OIDC cuida disso)

1. Scaffold do projeto

npx eve@latest init meu-agente
cd meu-agente

O CLI cria a estrutura, instala dependências, inicializa Git e inicia o dev server. Pare o servidor para editar com calma. A árvore resultante:

meu-agente/
├─ agent/
│  ├─ agent.ts              # config do runtime (modelo, opções)
│  ├─ instructions.md       # prompt de sistema always-on
│  ├─ tools/                # uma tool por arquivo
│  ├─ skills/               # skills markdown sob demanda
│  ├─ subagents/            # agentes-filhos para delegação
│  ├─ channels/             # entry points (HTTP, Slack...)
│  ├─ schedules/            # cron jobs
│  └─ sandbox/              # ambiente isolado de execução
├─ evals/                   # test suites para o agente
├─ package.json
└─ README.md

2. Definir o agente

Dois arquivos. Primeiro, o system prompt em agent/instructions.md:

Você é um assistente de pesquisa focado.
- Use as ferramentas disponíveis quando ajudarem a responder.
- Quando pedirem um relatório completo, carregue a skill de research report.
- Sempre cite fontes. Se não tem certeza, diga.

Depois, o runtime em agent/agent.ts:

import { defineAgent } from 'eve';

export default defineAgent({
  model: 'anthropic/claude-opus-4.8',
});

Uma linha. O model string resolve via AI Gateway — trocar provedor depois é mudar a string para openai/gpt-5.4-mini. Fallbacks entre provedores são automáticos.

3. Criar uma tool

Cada arquivo em agent/tools/ é uma ferramenta. O nome do arquivo vira o nome que o modelo vê. Sem registro central, sem arrays de configuração.

// agent/tools/web_search.ts
import { defineTool } from 'eve/tools';
import { z } from 'zod';

export default defineTool({
  description: 'Busca informações recentes na web.',
  inputSchema: z.object({
    query: z.string().min(1).describe('A consulta de busca'),
    limit: z.number().int().min(1).max(10).default(5),
  }),
  async execute({ query, limit }) {
    // Integre aqui sua API de busca real
    const results = Array.from({ length: limit }, (_, i) => ({
      title: `Resultado ${i + 1} para "${query}"`,
      url: `https://example.com/${encodeURIComponent(query)}/${i + 1}`,
    }));
    return { query, results };
  },
});

Repare: o inputSchema é Zod. Eve usa para validar argumentos e para gerar o JSON Schema que o modelo recebe. Descrições nos campos guiam o modelo para chamadas corretas.

Vamos adicionar uma segunda tool que persiste dados no sandbox:

// agent/tools/save_note.ts
import { defineTool } from 'eve/tools';
import { z } from 'zod';

export default defineTool({
  description: 'Salva uma nota de pesquisa para referência futura.',
  inputSchema: z.object({
    title: z.string(),
    body: z.string(),
  }),
  async execute({ title, body }, ctx) {
    await ctx.sandbox.writeFile(
      `notes/${title.replace(/\s+/g, '-').toLowerCase()}.md`,
      `# ${title}\n\n${body}\n`,
    );
    return { saved: true, title };
  },
});

O segundo parâmetro ctx dá acesso ao sandbox do agente — um filesystem isolado. Tools customizadas e tools built-in (bash, read_file, write_file) compartilham o mesmo ambiente.

4. Adicionar uma skill

Skills são procedimentos ou referências que o modelo carrega sob demanda. A diferença crucial vs tools:

• Tools = ações tipadas que o modelo executa
• Skills = instruções que o modelo lê

---
name: research-report
description: Produz um relatório estruturado e citado sobre um tópico.
---

# Procedimento de Relatório de Pesquisa

Siga estes passos quando pedirem um relatório completo:

1. Chame `web_search` 2-3 vezes com ângulos diferentes sobre o tema.
2. Agrupe os achados em 3 a 5 eixos temáticos.
3. Para cada eixo, escreva um parágrafo curto e cite as URLs fonte.
4. Chame `save_note` com o relatório final.
5. Termine com um resumo executivo no topo.

Skill separada = prompt padrão enxuto = agente rápido em perguntas simples, capaz em tarefas profundas. Se você implementa ferramentas (tools) e MCP servers, esse split vai soar familiar.

5. Conectar a um canal

HTTP vem ligado por padrão. Para adicionar Slack:

npx eve@latest channels add slack

Isso gera agent/channels/slack.ts — um adapter fino que mapeia eventos do Slack para turns no agente. Canais disponíveis: Slack, Discord, Teams, Telegram, Twilio, GitHub, Linear. Para custom channels, use defineChannel.

A ideia-chave: o mesmo agente serve todas as superfícies. Você não reconstrói lógica por plataforma.

6. Deploy

vercel deploy

Sem Dockerfile, sem orquestrador, sem provisionar nada. Eve compila o agente como Vercel Functions, AI Gateway resolve modelos via OIDC, e a sessão durável roda sobre Vercel Workflow. O dashboard de Agent Runs mostra sessions, turns, tool calls, timing e tokens sem configuração extra.

Deep Dive: os 7 pilares do Eve

Durable Sessions

Cada conversa é um workflow durável. Cada step é checkpointed. Na prática:

• Sobrevive a cold starts — o próximo message faz replay do event log e continua.
• Sobrevive a redeploys — você pode shipar código novo com agentes mid-task. O session em andamento termina na versão que iniciou.
• Sobrevive a longas pausas — o agente pode esperar horas por uma approval humana sem manter processo aberto, sem consumir compute.

Isso é construído sobre o Workflow SDK open-source, que já processou mais de 100 milhões de runs na Vercel. Você escreve funções async normais. A durabilidade é da infraestrutura.

A HTTP API é minimalista:

# Iniciar session
POST /eve/v1/session
{"message": "O que foi a receita da semana passada?"}

# Attach ao stream (NDJSON)
GET /eve/v1/session/:id/stream

# Continuar conversa
POST /eve/v1/session
{"message": "Detalhe por região", "continuationToken": "..."}

Sandboxes (microVMs)

O código que seu agente escreve é untrusted. Eve mantém código gerado pelo modelo fora do runtime da aplicação. Cada agente tem seu próprio sandbox — um ambiente isolado para shell, scripts, leitura e escrita de arquivos.

O backend é um adapter:

• Deployed: Vercel Sandbox (microVM dedicada)
• Local: Docker, microsandbox, ou just-bash
• Custom: implemente seu próprio adapter

Isso resolve o problema fundamental de harness e loop na arquitetura de agentes: execução isolada com segurança sem sacrificar poder.

Approvals (Human-in-the-Loop)

Qualquer tool pode exigir aprovação humana com um campo:

export default defineTool({
  description: 'Executa query SQL no warehouse.',
  inputSchema: z.object({ sql: z.string() }),
  needsApproval: ({ toolInput }) => estimateScanGb(toolInput.sql) > 50,
  async execute({ sql }) {
    // executa normalmente após aprovação
  },
});

O agente pausa no ponto da aprovação — indefinidamente se necessário — sem consumir compute. Quando aprovado, retoma exatamente de onde parou. Em canais como Slack, approvals renderizam como botões nativos.

Isso é elegante. Zero compute durante a espera significa que o custo de um agente com human-in-the-loop não explode.

Connections (MCP + OpenAPI)

Connections são integrações com serviços externos. Um arquivo aponta para um MCP server ou qualquer API com documento OpenAPI compatível:

// agent/connections/linear.ts
import { defineMcpClientConnection } from 'eve/connections';

export default defineMcpClientConnection({
  url: 'https://mcp.linear.app/sse',
  description: 'Linear workspace: issues, projects, cycles.',
  auth: {
    getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
  },
});

Eve descobre as tools remotas, entrega ao modelo, e faz broker da auth. O modelo nunca vê URLs ou credenciais da connection. Com Vercel Connect, OAuth interativo com consent e token refresh vem built-in.

No launch: Slack, GitHub, Snowflake, Salesforce, Notion, Linear + qualquer coisa via OAuth, API key ou MCP server.

Evals

Evals testam seu agente como você testa o resto do software:

// evals/revenue.eval.ts
import { defineEval } from 'eve/evals';
import { includes } from 'eve/evals/expect';

export default defineEval({
  description: 'O analista responde perguntas de receita seguindo regras do time.',
  async test(t) {
    await t.send('Qual foi a receita da semana passada?');
    t.completed();
    t.calledTool('run_sql');
    t.check(t.reply, includes('líquido de reembolsos'));
  },
});

Execute com eve eval localmente ou aponte para uma app deployed. Wire no CI e uma mudança de prompt que quebra algo morre no pipeline antes de chegar aos usuários.

Channels

Canais são entry points para o mesmo runtime. Slack, Discord, Teams, Telegram, Twilio, GitHub, Linear — cada um é um arquivo adapter. Um canal pode hand-off para outro: um webhook de incidente pode abrir uma thread de investigação no Slack.

O insight aqui é multimodal de superfícies sem duplicação de lógica. O agente é um. Os canais são interfaces.

AI Gateway

Model strings como anthropic/claude-opus-4.8 ou openai/gpt-5.4-mini resolvem via AI Gateway com OIDC. Na prática:

• Zero API keys no código — autenticação por token OIDC do projeto
• Fallbacks automáticos entre provedores quando um tem um bad day
• Model routing — swap de provedor é uma mudança de string
• Rate limiting e observability centralizados

Isso elimina aquele padrão onde cada agente tem seu próprio .env com chaves espalhadas.

Tracing e Observabilidade

Cada run produz um trace com spans OpenTelemetry padrão:

ai.eve.turn                      # um span por turn
├── ai.streamText                # a chamada ao modelo
│   └── ai.streamText.doStream
└── ai.toolCall                  # run_sql, com inputs e outputs

Exporta para qualquer backend OTel que você já rode — Braintrust, Datadog, Honeycomb, Jaeger. Na Vercel, aparece na aba Agent Runs sob Observability.

Casos internos da Vercel: Eve em produção real

A Vercel não lançou Eve como exercício acadêmico. São 100+ agentes internos rodando no framework. Alguns destaques:

d0 — O analista de dados

A ferramenta interna mais usada na Vercel. Mais de 30.000 perguntas por mês via Slack. Qualquer pessoa pergunta qualquer coisa sobre dados e recebe resposta do warehouse. Queries são scoped às permissões do perguntador — d0 nunca mostra uma tabela que você não poderia ver diretamente.

Lead Agent — O SDR autônomo

Roda o playbook do melhor rep da Vercel 24/7. Trabalha cada lead novo no instante que entra e faz follow-up sozinho para que nenhum esfrie durante a noite. Custo: ~$5.000/ano. Retorno: ~32× ROI. Um engenheiro mantém part-time.

Athena — RevOps

Construído pelo time de RevOps em 6 semanas sem engenheiros. Responde perguntas de pipeline e forecast a partir de Snowflake + Salesforce em linguagem natural. Pipeline coverage quase dobrou depois que entrou em produção.

Vertex — Suporte

Atende tickets no help center, docs e Slack 24/7. Lê o ticket, encontra a resposta certa e responde. 92% dos tickets resolvidos solo, escalando o resto para humanos focarem nos problemas que realmente precisam de atenção.

V — O router

Com 100+ agentes, manter track de qual cuida do quê é ineficiente. Tudo vai pro V primeiro no Slack. V descobre qual agente responde e roteia. A frota inteira funciona como um agente só em vez de cem opções diferentes.

Esses cinco agentes juntos pintam o retrato de uma empresa que opera — literalmente — sobre o framework que está lançando. 29% dos deploys na Vercel já são triggered por agentes. E a expectativa é que metade de todos os deploys venham de agentes em breve.

Spider Chart — 8 Eixos

                    DX / Ergonomia
                         10
                          |
         Ecosystem ──── 9 ┼ ──── 9 Durabilidade
                        / | \
                       /  |  \
      Observability  8    |    8  Segurança (Sandbox)
                      \   |   /
                       \  |  /
         Extensão ──── 7 ┼ ──── 5 Portabilidade
                          |
                     Multi-canal
                          8

Prós e Contras

Prós

• DX insana — agent = diretório, tool = arquivo, deploy = um comando. A curva de aprendizado é quase zero se você já usa Next.js.
• Durabilidade de graça — sessions que sobrevivem a tudo sem você escrever retry logic.
• Approvals sem custo — human-in-the-loop com zero compute durante espera. Isso é economicamente elegante.
• Multi-canal trivial — eve channels add slack e pronto. Mesmo agente em todas as superfícies.
• Evals como cidadãos de primeira classe — eve eval no CI resolve o problema de regressão de prompt.
• Observability built-in — tracing OTel sem configuração extra.
• AI Gateway — sem API keys espalhadas, fallbacks automáticos, swap de modelo em uma string.
• Battle-tested — 100+ agentes internos da Vercel rodando em produção antes do launch público.

Contras

• Lock-in Vercel — o elefante na sala. Durable execution depende de Vercel Workflow. Sandbox deployed depende de Vercel Sandbox. AI Gateway depende da infra Vercel. Se você sair, reconstrua tudo isso.
• Beta — o framework está em public preview. Convenções de pastas são estáveis, mas assinaturas de helpers podem mudar.
• Sem deploy self-hosted — não existe eve start para rodar em Kubernetes ou bare metal em produção. Localmente funciona, mas produção = Vercel.
• Vendor coupling — Vercel Connect para OAuth, OIDC do projeto para auth, Fluid Compute para funções long-running. São abstrações elegantes que acoplam firme.
• Custo em escala — serverless + microVMs + model calls = bill que escala com uso. Previsibilidade de custo é menor que self-hosted.

O trade-off real: Lock-in vs DX

Aqui vai minha opinião — e ela não é neutra.

Eve é provavelmente o framework de agentes com melhor developer experience que existe hoje. O filesystem-first é intuitivo, o deploy é trivial, a durabilidade é gratuita, e os canais são ridiculamente fáceis de adicionar. Se a Vercel resolveu o “cold start problem” para web, Eve resolve o “plumbing problem” para agentes.

Mas. Você está comprando a decisão de que seus agentes vivem na Vercel. Ponto. Se daqui a 2 anos os preços mudarem, se surgir uma alternativa melhor, se você precisar de GPU compute ou de compliance que exige infra controlada — você migra com custo significativo.

O Flue, do time Astro, oferece praticamente as mesmas convenções (agente como diretório, skills como markdown, durable execution) sem lock-in de runtime. Roda em Node, Cloudflare Workers, GitHub Actions, Docker, Railway, Fly. A DX é 80% da do Eve, e a portabilidade é 100%.

A analogia justa: Eve é para agentes o que Vercel é para o Next.js. Se você já tomou a decisão de estar all-in Vercel para web, estender isso para agentes é a decisão óbvia. Se portabilidade é um hard requirement, olhe para Flue.

Quando usar Eve

✅ Você já está all-in no ecossistema Vercel ✅ Precisa de agentes duráveis que sobrevivam a long-running tasks ✅ Quer multi-canal (Slack, Teams, GitHub) sem reconstruir lógica ✅ Precisa de human-in-the-loop com approvals elegantes ✅ Quer deploy em minutos, não em dias ✅ TypeScript é sua linguagem de produção ✅ Precisa de observability e evals sem montar stack de monitoring ✅ Equipe pequena que não pode investir semanas em infraestrutura

Quando NÃO usar Eve

❌ Portabilidade de runtime é hard requirement — use Flue ❌ Você precisa de self-hosted / on-premise / air-gapped ❌ Orçamento não comporta serverless em escala agressiva ❌ Você precisa de GPU compute acoplado ao agente (ML training, inference local) ❌ Compliance exige infra que você controla (HIPAA on-premise, SOC2 com escopo restrito) ❌ Python é sua linguagem — Eve é TypeScript-only ❌ Você quer um coding agent (CLI interativo) — Eve é para backend agents, não para TUI de código

Eve vs o ecossistema: onde se encaixa

O ponto: Eve e Flue concordam na forma (agente = diretório). A decisão não é sobre features — é sobre onde você quer rodar. Se é Vercel, Eve. Se é qualquer outro lugar, Flue.

Próximos passos

1. Scaffold seu primeiro agente: npx eve@latest init meu-agente — leva menos de 1 minuto até o dev server rodar.

2. Leia a doc oficial: eve.dev/docs — getting started, concepts, API reference.

3. Explore os starters: vercel.com/kb/eve — Slack agent, content agent, Sanity feedback agent.

4. Compare com Flue: se portabilidade importa, leia nosso comparativo Eve vs Flue vs Mastra antes de decidir.

5. Entenda o harness pattern: para contexto arquitetural mais profundo, veja Harness e Loop: Arquitetura de Agentes.

6. Contribua: github.com/vercel/eve — issues, discussions, PRs são bem-vindos. Apache 2.0.

Referências

• Introducing eve — Vercel Blog
• AI SDK 7 is now available — Vercel Blog
• eve.dev — Documentação oficial
• github.com/vercel/eve
• Eve vs Flue — The Road to Enterprise
• Vercel Eve Launch — Digital Applied
• Workflow SDK

Quer receber análises como essa direto no seu feed? Acompanhe o agentify.ia.br e o ft.ia.br para não perder os próximos guias sobre o ecossistema de agentes IA.