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

> Guia completo do Eve: framework TypeScript filesystem-first da Vercel para agentes duráveis com sessions, sandbox, approvals e deploy em um comando.

Source: https://agentify.ia.br/blog/eve/

> **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](https://vercel.com/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](/blog/agent-frameworks-vs-coding-agents), 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().describe('A consulta de busca'),
 limit: z.number().int().min().max().default(),
 }),
 async execute({ query, limit }) {
 // Integre aqui sua API de busca real
 const results = Array.from({ length: limit }, (_, i) => ({
 title: `Resultado ${i +} para "${query}"`,
 url: `https://example.com/${encodeURIComponent(query)}/${i +}`,
 }));
 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](/blog/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](https://workflow-sdk.dev/) 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](https://justbash.dev/)

- **Custom:** implemente seu próprio adapter

Isso resolve o problema fundamental de [harness e loop na arquitetura de agentes](/blog/harness-e-loop-arquitetura-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) >,
 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](https://vercel.com/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

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

 Eixo
 Score
 Justificativa

 DX / Ergonomia
 10/10
 Filesystem-first com zero boilerplate. Se você construiu com Next.js, já sabe Eve.

 Durabilidade
 9/10
 Sessions checkpointed sobre Workflow SDK (100M+ runs). Sobrevive a crash, redeploy, e longas pausas.

 Ecosystem
 9/10
 AI SDK 7 (16M downloads/semana), Vercel Connect, MCP nativo, 7+ canais out-of-box.

 Multi-canal
 8/10
 Slack, Discord, Teams, Telegram, Twilio, GitHub, Linear + custom. Um agente, N superfícies.

 Observability
 8/10
 OpenTelemetry nativo, Agent Runs dashboard, evals com scoring. Falta vendor-neutral UI built-in.

 Segurança (Sandbox)
 8/10
 MicroVMs para execução isolada. Modelo nunca vê credentials. OIDC para auth.

 Extensão
 7/10
 Subagentes, MCP connections, skills markdown, tools Zod-typed. Falta marketplace de skills oficial maduro.

 Portabilidade
 5/10
 Lock-in Vercel real. Sandbox adapter é plugável, mas durable execution e AI Gateway são Vercel-only deployed.

---

## 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](/blog/flue-vs-eve-vs-mastra), 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](/blog/flue-vs-eve-vs-mastra)
❌ 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

 Framework
 Linguagem
 Runtime
 Lock-in
 Durabilidade
 Filosofia

 Eve
 TypeScript
 Vercel
 Alto
 Vercel Workflow
 Filesystem-first, opinado

 Flue
 TypeScript
 Any (Node, CF Workers, Docker)
 Nenhum
 Durable Streams
 Filesystem-first, portável

 Mastra
 TypeScript
 Any
 Baixo
 Inngest/custom
 Code-first, flexível

 AI SDK 7
 TypeScript
 Any
 Nenhum
 Manual
 Primitivas, DIY

 LangGraph
 Python
 Any
 Nenhum
 Checkpointer
 Graph-first

 CrewAI
 Python
 Any
 Nenhum
 Limitada
 Role-playing agents

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

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

- **Leia a doc oficial:** [eve.dev/docs](https://eve.dev/docs) — getting started, concepts, API reference.

- **Explore os starters:** [vercel.com/kb/eve](https://examples.vercel.com/kb/eve) — Slack agent, content agent, Sanity feedback agent.

- **Compare com Flue:** se portabilidade importa, leia nosso [comparativo Eve vs Flue vs Mastra](/blog/flue-vs-eve-vs-mastra) antes de decidir.

- **Entenda o harness pattern:** para contexto arquitetural mais profundo, veja [Harness e Loop: Arquitetura de Agentes](/blog/harness-e-loop-arquitetura-agentes).

- **Contribua:** [github.com/vercel/eve](https://github.com/vercel/eve) — issues, discussions, PRs são bem-vindos. Apache 2.0.

---

## Referências

- [Introducing eve — Vercel Blog](https://vercel.com/blog/introducing-eve)

- [AI SDK 7 is now available — Vercel Blog](https://vercel.com/blog/ai-sdk-7)

- [eve.dev — Documentação oficial](https://eve.dev/docs)

- [github.com/vercel/eve](https://github.com/vercel/eve)

- [Eve vs Flue — The Road to Enterprise](https://theroadtoenterprise.com/blog/eve-vs-flue-typescript-agent-framework)

- [Vercel Eve Launch — Digital Applied](https://www.digitalapplied.com/blog/vercel-eve-open-source-typescript-agent-framework-launch)

- [Workflow SDK](https://workflow-sdk.dev/)

---

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

-->