Cómo construir agentes durables en producción con Vercel AI SDK 7 y WorkflowAgent

El tutorial usa Next.js 15 con App Router, TypeScript estricto y pnpm como gestor de paquetes. Necesitas una cuenta en Vercel con Fluid Compute habilitado —disponible en planes Pro y Enterprise— para soportar ejecuciones de más de 60 segundos sin timeout. El agente usa Claude Opus 4.8, por lo que debes tener una API key de Anthropic con acceso a ese modelo. Para la telemetría, basta el tier gratuito de Langfuse o una cuenta de Datadog.

Requisitos del entorno

• Node.js 20 o superior
• pnpm 9+
• Cuenta Vercel (plan Pro o Enterprise para Fluid Compute)
• API key de Anthropic con acceso a Claude Opus 4.8
• Cuenta en Langfuse (tier gratuito) o Datadog para telemetría

Estructura del proyecto

mi-agente/
├── app/
│   ├── api/
│   │   ├── agent/
│   │   │   └── route.ts
│   │   └── agent-approve/
│   │       └── route.ts
│   └── page.tsx
├── lib/
│   ├── model.ts
│   └── telemetry.ts
├── .env.local
└── vercel.json

WorkflowAgent recibe un workflowId que actúa como clave del checkpoint: si el proceso reinicia y vuelve a llamar al agente con el mismo workflowId, la ejecución retoma desde el último paso persistido en lugar de iniciar desde cero. El workflowId debe ser determinista para cada tarea: el ID de un ticket de soporte, el UUID de una orden, o el hash del prompt inicial son buenas opciones.

La API route crea una instancia del agente por request, pero el estado no vive en memoria del servidor: cada paso completo escribe su resultado en el almacén durable configurado. El parámetro maxSteps previene loops infinitos. Las herramientas se dividen en dos categorías: las que solo leen (execute directo) y las que modifican estado irreversiblemente (con el campo approval).

// app/api/agent/route.ts
import { WorkflowAgent, tool } from 'ai'
import { z } from 'zod'
import { model } from '@/lib/model'

export const maxDuration = 300

export async function POST(req: Request) {
  const body = await req.json()
  const { prompt, workflowId } = body

  const agent = new WorkflowAgent({
    model,
    workflowId,
    maxSteps: 20,
    tools: {
      consultarCRM: tool({
        description: 'Consulta datos de un cliente en el CRM por su RUT',
        inputSchema: z.object({
          rut: z.string().describe('RUT del cliente sin puntos ni guion')
        }),
        execute: async ({ rut }) => {
          const response = await fetch('/api/crm?rut=' + rut)
          return response.json()
        }
      }),
      actualizarRegistro: tool({
        description: 'Actualiza un campo de un registro en el CRM. Requiere aprobacion.',
        inputSchema: z.object({
          id: z.string(),
          campo: z.string(),
          valor: z.string()
        }),
        approval: 'user-approval',
        execute: async ({ id, campo, valor }) => {
          const response = await fetch('/api/crm/' + id, {
            method: 'PATCH',
            body: JSON.stringify({ campo, valor })
          })
          return response.json()
        }
      })
    }
  })

  const stream = await agent.streamRun(prompt)
  return stream.toDataStreamResponse()
}

La herramienta consultarCRM se ejecuta directamente porque solo lee datos: no requiere intervención humana. actualizarRegistro lleva approval: 'user-approval', lo que hace que WorkflowAgent pause la ejecución, notifique al frontend con el toolCallId y los argumentos propuestos, y espere la decisión del operador antes de continuar.

AI SDK 7 introduce registerTelemetry() como punto de entrada único para toda la telemetría de la aplicación. Una sola llamada al inicio cubre todos los agentes, todas las API routes y todos los modelos: no hay que instrumentar cada WorkflowAgent por separado. La telemetría reporta duración por paso, tokens consumidos, tasa de éxito y razón de finalización (maxSteps, aprobación rechazada, error de herramienta) para cada ciclo del agente.

Conectar Langfuse

Crea lib/telemetry.ts e importa initTelemetry() en tu app/layout.tsx para garantizar que el registro ocurra antes del primer request:

// lib/telemetry.ts — configuracion para Langfuse
import { registerTelemetry } from 'ai'
import Langfuse from 'langfuse'

const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY || '',
  secretKey: process.env.LANGFUSE_SECRET_KEY || '',
  baseUrl: process.env.LANGFUSE_BASE_URL || 'https://cloud.langfuse.com'
})

export function initTelemetry() {
  registerTelemetry({
    provider: langfuse,
    metadata: {
      project: 'agente-crm-produccion',
      environment: process.env.NODE_ENV || 'production'
    }
  })
}

Conectar Datadog

Si prefieres Datadog, instala dd-trace (pnpm add dd-trace) y registra el tracer de la misma forma:

// lib/telemetry.ts — configuracion para Datadog
import { registerTelemetry } from 'ai'
import tracer from 'dd-trace'

tracer.init({
  service: 'agente-crm',
  env: process.env.DD_ENV || 'production',
  logInjection: true
})

export function initTelemetry() {
  registerTelemetry({
    provider: tracer,
    metadata: { service: 'agente-crm' }
  })
}

En ambos casos, las trazas incluyen el árbol completo de pasos del WorkflowAgent: cada decisión del modelo, cada herramienta llamada (aprobada o rechazada), la duración exacta y el volumen de tokens por paso. Desde Langfuse puedes filtrar por workflowId para ver la historia completa de una ejecución que atravesó varios reinicios de proceso.

Un agente durable no está verificado hasta que demuestras que sobrevive un reinicio real. El test más directo es enviar un prompt que requiera varios pasos, interrumpir el proceso a la mitad, y confirmar que al reiniciar con el mismo workflowId el agente continúa desde el checkpoint sin repetir trabajo.

1. Inicia el agente con un workflowId fijo y un prompt que requiera 5 o más pasos secuenciales
2. Interrumpe el proceso en el paso 3 (SIGTERM, reinicio del pod, o simulación de timeout)
3. Relanza el proceso y envía exactamente el mismo workflowId
4. Verifica en los logs de Langfuse o Datadog que los pasos 1 a 3 no se ejecutaron dos veces
5. Confirma que el agente completó desde el paso 4 hasta el final con el contexto correcto
6. Activa el gate de aprobaciones: envía un prompt que llame a la herramienta irreversible y verifica que el agente se pausa esperando confirmación
7. Rechaza la aprobación y confirma que el agente termina con estado limpio, sin escrituras parciales en el CRM

Si en el dashboard de Langfuse observas que los pasos 1 a 3 se ejecutaron dos veces, el checkpoint no está activo: verifica que workflowId sea exactamente el mismo string en ambas llamadas y que el proveedor de persistencia configurado en WorkflowAgent esté disponible durante el reinicio. Si el agente falla silenciosamente sin emitir trazas, confirma que initTelemetry() se llama antes del primer request en app/layout.tsx.