Tu primer agente con OpenAI Agents SDK paso a paso

La mayoría de los frameworks de “agentes” son capas de abstracción innecesarias. El OpenAI Agents SDK para TypeScript hace una cosa bien: estandariza el loop de tool-calling sin forzarte a una arquitectura compleja. Sin magia, solo gestión limpia de function calls y estado.

Requisitos previos

• Node.js 18+: versiones anteriores dan problemas con fetch nativo y ESM.
• TypeScript: el SDK está diseñado para TS. El tipado de tools es la ventaja real.
• API Key de OpenAI con créditos. Los agentes consumen más tokens que chat simple.

Instalación

npm install @openai/agents zod

El paquete core es ligero. Zod se usa para validar los esquemas de las tools.

Configuración básica

Un agente es un objeto con instrucciones y modelo. La función run orquesta el ciclo:

import { Agent, run } from '@openai/agents';

const weatherAgent = new Agent({
  name: 'WeatherBot',
  instructions: 'Asistente técnico. Das el clima de forma directa, sin adornos.',
  model: 'gpt-4o-mini', // barato para empezar
});

async function main() {
  const result = await run(weatherAgent, '¿Qué tiempo hace en Madrid?');
  console.log(result.finalOutput);
}

main().catch(console.error);

Esto es un chatbot. Para que sea un agente, necesita herramientas.

Añadiendo Tools

El SDK genera el esquema JSON automáticamente desde Zod. No escribas JSON schemas a mano:

import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';

const getWeather = tool({
  description: 'Obtiene la temperatura actual de una ciudad',
  parameters: z.object({
    city: z.string().describe('Nombre de la ciudad, ej. Madrid'),
  }),
  execute: async ({ city }) => {
    // Aquí iría la llamada real a OpenWeather o similar
    const temp = Math.floor(Math.random() * 30);
    return `Temperatura en ${city}: ${temp}°C.`;
  },
});

const agent = new Agent({
  name: 'WeatherAgent',
  instructions: 'Usa la herramienta de clima. Sé conciso.',
  tools: [getWeather],
});

const result = await run(agent, '¿Qué tiempo hace en Barcelona?');
console.log(result.finalOutput);

El Agent Loop

Lo que pasa dentro de run():

1. Envía el prompt al LLM
2. El LLM decide que necesita getWeather
3. El SDK ejecuta la función execute
4. El resultado vuelve al LLM
5. El LLM genera la respuesta final

El SDK maneja todo esto automáticamente. Tu código solo define el agente y llama a run().

Manejo de errores

En producción, el LLM enviará parámetros incorrectos. Zod valida, pero debes manejar errores de ejecución:

const safeTool = tool({
  description: 'Procesa un pago',
  parameters: z.object({
    amount: z.number().positive(),
  }),
  execute: async ({ amount }) => {
    try {
      // Lógica de pago real
      return 'Pago procesado';
    } catch (e: any) {
      // Devuelve el error al LLM para que corrija o informe
      return `Error procesando pago: ${e.message}`;
    }
  },
});

Si execute lanza una excepción no capturada, el loop se rompe. Siempre usa try-catch.

Múltiples tools

Puedes pasar varias herramientas. El LLM decide cuál usar:

const searchDocs = tool({
  description: 'Busca en la documentación del proyecto',
  parameters: z.object({
    query: z.string().describe('Término de búsqueda'),
  }),
  execute: async ({ query }) => {
    // Búsqueda real en tu documentación
    return `Resultados para "${query}": ...`;
  },
});

const runCode = tool({
  description: 'Ejecuta código TypeScript y devuelve el resultado',
  parameters: z.object({
    code: z.string().describe('Código a ejecutar'),
  }),
  execute: async ({ code }) => {
    try {
      // Ejecución en sandbox
      return 'Resultado de ejecución...';
    } catch (e: any) {
      return `Error: ${e.message}`;
    }
  },
});

const devAgent = new Agent({
  name: 'DevAssistant',
  instructions: 'Ayudas a desarrolladores. Busca docs y ejecuta código cuando sea necesario.',
  tools: [searchDocs, runCode],
  model: 'gpt-4o',
});

Control de costes

Los agentes pueden ser caros si no pones límites:

1. Modelo barato para routing: Usa gpt-4o-mini ($0.15/$0.60 por 1M tokens) para tareas simples.
2. Limita iteraciones: Un loop sin límite puede quemar tokens infinitamente.
3. Cachea resultados: Si el agente hace la misma sub-consulta dos veces, cachea.
4. Monitoring: Usa el Traces Dashboard de OpenAI para ver cada paso.

Deploy

Para producción, usa variables de entorno:

export OPENAI_API_KEY='sk-...'

Despliega en cualquier plataforma Node.js: Cloudflare Workers, Vercel, Railway, o un VPS.

Para agentes de larga duración, considera usar colas (BullMQ, Temporal) en lugar de HTTP requests directos.

Lo que este SDK NO hace

• No es multi-agente. Para eso necesitas LangGraph o tu propia orquestación.
• No tiene memoria persistente. Tienes que implementarla tú.
• No tiene evaluación. No te dice si el agente funciona bien.

Veredicto

El OpenAI Agents SDK es pragmático. Elimina boilerplate de JSON schemas y abstrae el loop de tool-calling sin quitarte control. Correcto si quieres agentes en TypeScript sin la complejidad de LangGraph.

Para algo más que un single-agent con tools, necesitarás añadir tu propia capa de orquestación encima.

Fuentes: OpenAI Agents SDK docs (platform.openai.com/docs), experiencia propia.