Construyendo Agentes Rápidos con TypeScript y Vercel AI SDK

TypeScript + Vercel AI SDK: la combinación que uso para construir agentes rápido

Tiempo estimado de lectura: 4 min

TypeScript + Vercel AI SDK: la combinación que uso para construir agentes rápido. Si vas a poner agentes en producción, necesitas que la capa que conecta al LLM con tus herramientas sea predecible, tipada y validada desde el primer día. Esa combinación reduce errores silenciosos, acelera refactors y convierte promesas estocásticas en contratos verificables.

Resumen rápido (lectores con prisa)

TypeScript para tipado estático, Zod para validación en runtime y Vercel AI SDK como API unificada. Juntos: herramientas tipadas, extracción estructurada (generateObject), y streaming (streamText) para agentes más seguros y previsibles.

TypeScript + Vercel AI SDK: por qué funciona para agentes rápidos

Tres problemas recurrentes al construir agentes:

1. El LLM alucina parámetros para las herramientas (tool calls)

Los modelos pueden generar parámetros inválidos o inventados para llamadas a herramientas, lo que puede llevar a ejecuciones peligrosas si no se validan antes.

2. Las respuestas JSON vienen envueltas en markdown o truncadas

Solemos ver JSON con backticks, texto adicional o respuestas incompletas que complican el parsing confiable.

3. Cambios en la API del proveedor rompen integraciones silenciosamente

Actualizar modelos o proveedores puede introducir cambios incompatibles si no hay contratos y pruebas robustas.

La solución práctica es simple: tipos en la superficie (TypeScript), contratos ejecutables (Zod) y una API que integra ambas cosas (Vercel AI SDK). Beneficios concretos:

Tool calls tipados: la barrera que evita ejecuciones peligrosas

Definir herramientas con esquemas evita que el agente ejecute acciones con parámetros inventados. Ejemplo:

import { tool } from 'ai';
import { z } from 'zod';

const searchOrders = tool({
  description: 'Busca pedidos por ID de cliente',
  parameters: z.object({
    customerId: z.string().uuid(),
    status: z.enum(['pending','shipped','delivered']).optional(),
  }),
  execute: async ({ customerId, status }) => {
    return queryOrdersDatabase({ customerId, status });
  },
});

Si el LLM devuelve un customerId inválido, Zod lo rechazará antes de llamar a execute. Resultado: menos excepciones en la base de datos y trazabilidad clara del fallo (prompt → validación → rechazo).

generateObject: extracción fiable de datos estructurados

generateObject obliga al modelo a respetar un esquema y te devuelve un objeto tipado sin hacer JSON.parse() manual. Ejemplo práctico:

import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const schema = z.object({
  sentiment: z.enum(['positive','neutral','negative']),
  confidence: z.number().min(0).max(1),
  topics: z.array(z.string()).max(5)
});

const { object } = await generateObject({
  model: openai('gpt-4o'),
  schema,
  prompt: 'Analiza la reseña y devuelve sentiment, confidence y topics.'
});

// object ya está tipado según schema

Esto reduce la ingeniería de prompts (“Devuelve SOLO JSON”) y aumenta la tasa de respuestas utilizables desde el primer intento.

streamText: UX que comunica progreso y permite pasos intermedios

Los agentes suelen ejecutar varias herramientas en cadena. streamText permite emitir texto progresivo y reflejar estados intermedios (p. ej. “consultando base de datos…”) en la UI sin arquitectura adicional:

Esto mejora la percepción de latencia y permite interacciones más naturales con agentes multi‑paso.

Integración práctica y operaciones en producción

Patrón recomendado

Medidas operativas

Limitaciones y decisions trade‑offs

Conclusión

TypeScript + Vercel AI SDK: la combinación que uso para construir agentes rápido no es un truco de marketing. Es una estrategia concreta: tipos para detectar cambios, Zod para validar en runtime, y un SDK que une proveedores, streaming y herramientas tipadas. Si tu objetivo es desplegar agentes que actúen sobre sistemas reales—bases de datos, pedidos, o infraestructuras—esta pila reduce fallos silenciosos y convierte iteración rápida en ingeniería sostenible.

Para equipos que exploran automatización y agentes como flujo de trabajo productivo, una guía práctica y recursos adicionales están disponibles en Dominicode Labs. Es una continuación lógica para quienes quieren aterrizar estas prácticas en sistemas reales.

FAQ

¿Por qué combinar TypeScript con Zod y un SDK como Vercel AI SDK?

TypeScript aporta seguridad estática y autocompletado; Zod proporciona validación en runtime; y Vercel AI SDK unifica la interacción con proveedores, streaming y herramientas tipadas. La combinación reduce errores silenciosos y facilita refactors.

¿Cómo evitan las herramientas tipadas ejecuciones peligrosas?

Al definir parámetros con esquemas Zod, cualquier dato que no valide se rechaza antes de ejecutar la función execute, evitando operaciones con parámetros inventados o inválidos.

¿Qué ventaja ofrece generateObject frente a parsear JSON manualmente?

generateObject obliga al modelo a respetar un esquema y devuelve un objeto ya tipado, evitando la ingeniería de prompt para forzar JSON y reduciendo errores por markdown, texto adicional o truncado.

¿Cuándo debo usar streamText?

Cuando quieras mejorar la UX en interacciones multi‑paso: emitir tokens progresivamente, mostrar estados intermedios y reportar eventos de invocation/execute sin añadir complejidad arquitectónica.

¿Qué métricas operativas son críticas?

Métricas como tasa de validación fallida, latencia media por herramienta y reintentos por prompt son esenciales para monitorear la salud y eficacia del agente.

¿Cuáles son las limitaciones principales de esta pila?

No elimina la estocasticidad del LLM; solo la controla. También requiere validación semántica adicional (p. ej. asegurar números positivos). Tipar desde el día 0 impone disciplina, aunque acelera onboarding y refactors.