Crea tu Primer Agente de IA Durable con Vercel Eve (Guía para Principiantes)

Vercel acaba de lanzar Eve, y la forma más fácil de describirlo es «Next.js, pero para agentes». En lugar de un único objeto de configuración gigante que tienes que mantener en la cabeza, cada parte de tu agente tiene su propio archivo. Las instrucciones viven en un archivo. Las herramientas viven en una carpeta. Los canales (Slack, Discord, una interfaz web) viven en otra. Eve lee esa estructura de carpetas y la convierte en un agente en ejecución que funciona en local, sirve HTTP y mantiene una conversación viva a lo largo de muchos turnos.

He construido agentes con varios frameworks distintos, y lo que me convenció aquí es lo poca ceremonia que hay. Puedes leer un proyecto de Eve completo con solo mirar el árbol de directorios. Eso es todo. Sin registro que mantener sincronizado, sin archivo de cableado que quede desactualizado.

En esta guía generaremos un agente desde cero, le daremos una herramienta, lo conectaremos tanto a Slack como a Discord, cambiaremos el modelo Claude por defecto por uno open source y después lo desplegaremos, ya sea en Vercel o en tu propio VPS con Dokploy. Al final tendrás un asistente funcional con el que tu equipo podrá hablar.

Qué es Eve realmente

Eve es un framework para construir agentes durables como archivos ordinarios en un proyecto TypeScript. «Durable» es la palabra que importa. Una sesión de Eve no es una petición y una respuesta. Puede emitir progreso en streaming mientras trabaja, llamar a herramientas y subagentes, pausarse para pedir aprobación a un humano, reanudarse cuando llega la respuesta y mantener el estado entre turnos. Internamente se apoya en el Workflow SDK open source para hacer las sesiones reanudables y resistentes a fallos, para que tu código pueda centrarse en el trabajo en lugar de la fontanería.

Así se ve un proyecto pequeño:

my-agent/
├── package.json
└── agent/
    ├── agent.ts          # picks the model, runtime config
    ├── instructions.md   # who the agent is, how it behaves
    ├── tools/            # typed functions the model can call
    │   └── get_weather.ts
    ├── skills/           # longer procedures, loaded on demand
    │   └── plan_a_trip.md
    └── channels/         # Slack, Discord, web, etc.
        └── slack.ts

La ubicación de un archivo dice qué hace, y su ruta suele darle su nombre. Coloca agent/tools/get_weather.ts en su sitio y Eve descubre una herramienta llamada get_weather. Renombra el archivo y el nombre de la herramienta lo acompaña. Ese es todo el modelo mental.

Empieza solo con instructions.md y agent.ts. Añade las demás carpetas cuando de verdad las necesites.

Requisitos previos

Antes de generar nada, asegúrate de tener:

El scaffold usa por defecto anthropic/claude-sonnet-4.6 enrutado a través del Vercel AI Gateway. Si omites la credencial, la terminal de desarrollo lo señala y te guía para pegar una clave con su comando /model, así que no te quedarás atascado.

Paso 1: Genera tu primer agente

npx puede ejecutar eve init sin instalar nada antes:

npx eve@latest init my-agent

Ese comando crea el proyecto, instala las dependencias, inicializa Git, arranca el servidor de desarrollo y abre una interfaz de terminal interactiva. Escribe un mensaje y verás el bucle del modelo ejecutándose en tiempo real.

Un par de cosas que conviene saber:

Si prefieres conectarlo a mano, instala las tres dependencias y declara un engine de Node 24:

npm install eve@latest ai zod

{
  "engines": {
    "node": "24.x"
  }
}

Después escribe los dos archivos que Eve necesita. agent/instructions.md:

You are a concise assistant. Use tools when they are available.

Y agent/agent.ts:

import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-4.6",
});

Incluso con este tamaño el agente ya puede hacer trabajo real, porque el arnés por defecto incluye herramientas de archivos, shell, web y delegación desde el primer momento.

Paso 2: Dale una herramienta al agente

Una herramienta es una acción tipada que el agente puede llamar: consultar una API, ejecutar una query, escribir un archivo. El nombre del archivo se convierte en el nombre de herramienta que ve el modelo, y tiene que ser snake_case. Crea agent/tools/get_weather.ts:

import { defineTool } from "eve/tools";
import { z } from "zod";

// The model sees this tool as `get_weather`, from the filename.
export default defineTool({
  description: "Get the current weather for a city.",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "Sunny", temperatureF: 72 };
  },
});

Las piezas de una herramienta:

Las herramientas se ejecutan en el runtime de tu app con acceso completo a process.env, no dentro del sandbox, así que pueden importar código compartido desde lib/ y leer tus secretos directamente. Una cosa a tener en cuenta: un paso que se interrumpe a mitad de ejecución se vuelve a ejecutar al reanudar, así que haz que los efectos secundarios como cargos o emails sean idempotentes, o protégelos detrás de una aprobación (más sobre esto abajo).

Paso 3: Ejecútalo y envía un mensaje

Una app generada con el scaffold tiene un script dev:

npm run dev

Si conectaste Eve a mano y no tienes script dev, ejecuta el binario con npx eve dev en su lugar. En ambos casos llegas a la interfaz de terminal. Escribe «¿Qué tiempo hace en Brooklyn?» y verás las llamadas ocurrir en orden: la llamada a get_weather, luego su resultado, luego la respuesta.

Toda app de Eve también expone la misma API HTTP estable. Inicia una sesión durable con curl:

curl -X POST http://127.0.0.1:3000/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"What is the weather in Brooklyn?"}'

La respuesta te devuelve dos cosas que reutilizarás: un continuationToken en el cuerpo para reanudar la conversación, y una cabecera x-eve-session-id que identifica la ejecución. Conéctate al stream con el id de sesión:

curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream

El stream es NDJSON. Para esta ejecución verás session.started, actions.requested (la llamada a la herramienta), action.result, message.completed (la respuesta) y session.completed. Para continuar la conversación, envía un mensaje de seguimiento con el token:

curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
  -H 'content-type: application/json' \
  -d '{"continuationToken":"<token>","message":"Now do Queens."}'

Ese es el hola mundo. Un bot del tiempo no le sirve a nadie, así que hagamos que sea accesible donde la gente realmente trabaja.

Paso 4: Conecta el agente a Slack

Un canal es el adaptador entre una plataforma y tu agente. Normaliza los mensajes entrantes, posee el token de reanudación para esa superficie y decide cómo se entregan las respuestas. El canal de Slack responde a @mentions y mensajes directos, contesta en hilos, muestra indicadores de escritura y convierte las peticiones de human-in-the-loop en botones de Slack.

La parte buena: las credenciales pasan por Vercel Connect, que gestiona tanto el token de bot saliente como la verificación del webhook entrante. No hay ningún SLACK_BOT_TOKEN ni SLACK_SIGNING_SECRET que tengas que vigilar.

Primero, configura un cliente de Connect y apunta su trigger a la ruta de Slack de Eve:

npm install -g vercel@latest && export FF_CONNECT_ENABLED=1
vercel connect create slack --triggers
vercel connect detach <uid> --yes
vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes

El paso create aprovisiona un destino en la ruta por defecto de Connect; después detach/attach lo reapunta a /eve/v1/slack, que es donde Eve realmente escucha. El flag --triggers activa las suscripciones a eventos de Slack; sin él, Slack nunca entrega los eventos app_mention ni message.im.

Ahora añade el canal. O lo generas con eve channels add slack, o escribes agent/channels/slack.ts a mano:

import { connectSlackCredentials } from "@vercel/connect/eve";
import { slackChannel } from "eve/channels/slack";

export default slackChannel({
  credentials: connectSlackCredentials("slack/my-agent"),
});

connectSlackCredentials devuelve el token de bot y el verificador de webhook, manteniendo la rotación de tokens y la verificación de peticiones dentro de Connect en lugar de en tu código. Despliega cuando el trigger y el archivo de canal estén listos:

VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1 vercel deploy --prod

Ese flag permite que la CLI de Vercel reconozca a Eve como framework durante el build.

Incorporar el contexto del hilo

Por defecto el canal te da la mención que lo activó, pero no las respuestas anteriores del hilo. Si quieres que el agente lea lo que se dijo antes de ser llamado, carga los mensajes previos y devuélvelos como context:

import { defaultSlackAuth, loadThreadContextMessages, slackChannel } from "eve/channels/slack";
import { connectSlackCredentials } from "@vercel/connect/eve";

export default slackChannel({
  credentials: connectSlackCredentials("slack/my-agent"),
  async onAppMention(ctx, message) {
    const auth = defaultSlackAuth(message, ctx);
    const prior = await loadThreadContextMessages(ctx.thread, message, {
      since: "last-agent-reply",
    });
    if (prior.length === 0) return { auth };
    const transcript = prior
      .map((m) => `${m.isMe ? "you" : (m.user ?? "user")}: ${m.markdown}`)
      .join("\n");
    return { auth, context: [`Recent thread messages since your last reply:\n\n${transcript}`] };
  },
});

Usar since: "last-agent-reply" significa que menciones repetidas en un mismo hilo solo inyectan lo nuevo, así que no vuelves a alimentar todo el historial en cada turno.

Paso 5: Conecta el agente a Discord

Discord funciona a través de HTTP Interactions: comandos de barra, componentes de mensaje y modales. Discord impone un plazo de tres segundos para confirmar un comando, así que el canal verifica la firma, confirma de inmediato y ejecuta el trabajo real en segundo plano. No tienes que pensar en nada de eso; está resuelto.

El agent/channels/discord.ts mínimo:

import { discordChannel } from "eve/channels/discord";

export default discordChannel();

Discord necesita tres variables de entorno:

DISCORD_PUBLIC_KEY=...      # verifies the signature headers
DISCORD_APPLICATION_ID=...  # edits the deferred response, sends followups
DISCORD_BOT_TOKEN=...       # proactive messages, fallback, typing indicators

La ruta es POST /eve/v1/discord por defecto. Pega esa URL pública en el campo Interactions Endpoint URL de tu aplicación de Discord en el Developer Portal.

Registrar los comandos es cosa tuya, no del canal. Una opción de tipo string llamada message coincide con la extracción de prompt por defecto de Eve:

curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/commands" \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" -H "Content-Type: application/json" \
  -d '[{"name":"ask","description":"Ask the eve agent","type":1,
    "options":[{"name":"message","description":"What should the agent do?","type":3,"required":true}]}]'

Usa comandos de guild durante el desarrollo; se propagan mucho más rápido que los globales. Aquí tienes un canal algo más completo que decide la autenticación por comando y publica la respuesta:

import { discordChannel } from "eve/channels/discord";

export default discordChannel({
  onCommand: (ctx, interaction) => ({
    auth: {
      principalId: interaction.user.id,
      principalType: "user",
      authenticator: "discord",
      attributes: { channel_id: interaction.channelId, guild_id: interaction.guildId ?? "" },
    },
  }),
  events: {
    "message.completed"(eventData, channel, ctx) {
      if (eventData.finishReason === "tool-calls") return;
      if (eventData.message) channel.discord.post(eventData.message);
    },
  },
});

Una limitación a tener en cuenta: los archivos adjuntos entrantes no están soportados hoy en el canal de Discord, mientras que Slack sí los gestiona. Si tu agente necesita leer archivos subidos, piensa en usar Slack o un canal web.

Lo que me gusta es que la misma lógica de agente sirve a ambas plataformas. Tu herramienta get_weather no sabe ni le importa si la pregunta vino de Slack, Discord, la terminal o un navegador. Escribe el comportamiento una vez, expónlo en todas partes.

Paso 6: Usa modelos open source en lugar de Claude

El modelo por defecto es Claude Sonnet, pero no estás casado con él. En los últimos años aprendimos por las malas que un modelo del que dependes puede quedar obsoleto o desaparecer de un día para otro, así que poder cambiar importa. Eve convierte el modelo en una sola línea de configuración.

Tienes dos opciones de enrutado.

import { defineAgent } from "eve";

export default defineAgent({
  // any model the gateway exposes
  model: "moonshotai/kimi-k2.6",
});

npm install @ai-sdk/openai

import { createOpenAI } from "@ai-sdk/openai";
import { defineAgent } from "eve";

const provider = createOpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

export default defineAgent({
  model: provider("z-ai/glm-5.1"),
});

¿Qué modelo abierto deberías elegir? Modelos como GLM-5.2, Kimi K2.6 y Qwen 3.6 se mantienen bien en trabajo agéntico de llamadas a herramientas por una fracción del coste de los modelos frontera. Profundicé en las ventajas e inconvenientes en mi guía de los mejores LLMs open source para reemplazar a Claude, así que consúltala si vas a elegir uno para una carga de trabajo real. La versión corta: enruta modelos baratos y rápidos a los turnos simples y guarda los caros para los problemas difíciles. Eve te permite hacer exactamente eso, incluso por subagente.

Paso 7: Añade herramientas de servicios externos con conexiones

Más allá de las herramientas que escribes, Eve puede incorporar herramientas de servidores MCP externos y documentos OpenAPI. Estas viven en agent/connections/, y el modelo nunca ve la URL ni las credenciales: descubre las herramientas y las llama por su nombre.

Una conexión al servidor MCP de Linear se ve así:

import { defineMcpClientConnection } from "eve/connections";

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

Para cualquier cosa que toque dinero, borre datos o envíe mensajes, protégela detrás de una aprobación. Los helpers de eve/tools/approval te dan never(), once() (pregunta la primera vez en una sesión) y always() (pregunta cada vez). El mismo flujo de pausa y reanudación que impulsa las herramientas human-in-the-loop se encarga de ello.

Paso 8: Despliégalo

Ya tienes un agente funcionando. Ahora necesita vivir en algún sitio. Eve se ejecuta igual en local, en Vercel y en un host de Node normal, así que pasar a producción es casi todo mecánico.

Opción A: Desplegar en Vercel

eve build compila el agente y escribe la salida del host. En Vercel eso es el bundle de Build Output en .vercel/output, más los artefactos compilados en .eve/. Después despliega con la CLI o haciendo push a un proyecto conectado a Git:

vercel deploy

Antes de esa primera petición de producción, recorre esta checklist corta:

Una vez desplegado, la plataforma detecta Eve automáticamente y muestra una pestaña Agent Runs en la vista de Observability de tu proyecto, donde puedes explorar sesiones y leer la traza de cada conversación.

Opción B: Autoalojar en tu propio VPS

Si prefieres no atarte a la plataforma de Vercel, Eve se ejecuta como un servicio de Node normal detrás de tu propio gestor de procesos o proxy inverso:

eve build
PORT=3000 eve start --host 0.0.0.0

Fuera de Vercel, Eve escribe la salida estándar de Nitro en .output/, el Workflow SDK usa su mundo local (guardando el estado en .workflow-data) y defaultBackend() elige un backend de sandbox local. Algunas cosas que conviene explicitar al autoalojar:

La forma más limpia que he encontrado de ejecutar un servicio de Node como este en un VPS es Dokploy, una alternativa open source y autoalojable a Vercel y Heroku. Te da despliegues basados en Git, HTTPS automático vía Traefik, gestión de variables de entorno y logs, todo desde un panel que controlas tú. Mi guía de instalación de Dokploy cubre cómo ponerlo en marcha en un servidor nuevo.

El flujo de despliegue de un agente Eve se corresponde casi exactamente con el de una app de Node normal, así que si ya has desplegado algo con Dokploy, esto te resultará familiar. Mi tutorial sobre desplegar TanStack Start en un VPS con Dokploy muestra el patrón completo (comando de build, comando de arranque, variables de entorno, dominio), y los mismos pasos aplican aquí: define el comando de build como eve build, el de arranque como eve start --host 0.0.0.0, expón el puerto y añade tus secretos de modelo y autenticación en el panel de entorno.

Verifica el despliegue

Tomaras el camino que tomaras, haz una prueba de humo de las rutas en vivo. Primero el health, luego un turno real:

curl https://<your-app>/eve/v1/health

curl -X POST https://<your-app>/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"Hello from production"}'

También puedes manejar el despliegue en vivo con la terminal de desarrollo, lo cual viene bien para una comprobación rápida en producción:

eve dev https://<your-app>

Qué construir después

El bot del tiempo era solo una forma de ver el bucle en marcha. Lo interesante es lo que pones en tools/ y skills/. Un agente de reutilización de contenido que redacta posts sociales y llama a herramientas de generación de imágenes. Un agente de investigación de leads que extrae datos de tu CRM. Un bot de triaje de soporte viviendo en tu Slack. El andamiaje es siempre el mismo, que es justo la idea: dejas de reinventar el arnés y dedicas tu tiempo a la capacidad real.

Preguntas frecuentes

Conclusión

Eve toma la parte de la construcción de agentes que suele ser un lío (canales, estado durable, enrutado de modelos, despliegues) y la convierte en una carpeta que puedes leer de arriba abajo. Generas el scaffold con un comando, añades una herramienta como un único archivo, apuntas un canal a Slack o Discord y eliges el modelo que encaje con el trabajo y tu presupuesto. Despliégalo en Vercel para el camino de cero configuración, o autoalójalo en un VPS con Dokploy cuando quieras ser dueño de todo el stack.

Si vienes de otro framework, el cambio casi no te cuesta nada, ya que tus herramientas y skills son TypeScript y Markdown planos que puedes llevarte a otra parte. Empieza con el hola mundo del tiempo y luego reemplázalo por algo que tu equipo usaría de verdad.