Guías

OpenAI Agents SDK: cómo montar agentes con MCP, guardrails y trazas sin perder el control

OpenAI Agents SDK no es otro wrapper para llamar a un modelo. Es una forma de asumir la orquestación de herramientas, MCP, guardrails, handoffs, sesiones y trazas sin escribir todo el loop agentic desde cero.

DevAI Editorial

— 9 min de lectura
Compartir
OpenAI Agents SDK: cómo montar agentes con MCP, guardrails y trazas sin perder el control

OpenAI Agents SDK no es otro wrapper para llamar a un modelo. Es una forma de asumir la orquestación de herramientas, MCP, guardrails, handoffs, sesiones y trazas sin escribir todo el loop agentic desde cero.

OpenAI Agents SDK es el framework oficial de OpenAI para construir aplicaciones agentic donde tu código controla agentes, herramientas, handoffs, sesiones, guardrails, aprobaciones y trazas. La diferencia importante frente a una llamada suelta a Responses API no es el modelo: es quién gobierna el loop.

Checklist

Qué es OpenAI Agents SDK y qué no es

Una definición citable: OpenAI Agents SDK es una capa de orquestación para construir agentes que planifican, llaman herramientas, delegan en otros agentes, validan límites y dejan trazas operativas sobre el flujo completo.

No es un sustituto mágico de arquitectura de producto. El SDK te da primitivas: `Agent`, `Runner`, tools, handoffs, sessions, guardrails, MCP y tracing. Tu aplicación sigue siendo responsable de permisos, datos, colas, persistencia, costes, errores, revisión humana y rollback.

La documentación de OpenAI lo separa claramente de Responses API: si una llamada con tools y lógica propia basta, usa Responses. Si tu aplicación quiere poseer orquestación, ejecución de tools, aprobaciones y estado, el SDK empieza a tener sentido.

Recibe una lectura semanal de herramientas IA para devs

Si quieres seguir OpenAI Agents SDK, MCP, Codex, Claude Code y patrones reales para devs sin leer cada changelog, DevAI Semanal te lo resume cada semana en un email de 5 minutos.

Suscribirme gratis

Modelo mental: Agent, Runner, tools y handoffs

`Agent` define identidad operativa: instrucciones, modelo, herramientas, MCP servers, guardrails y agentes a los que puede delegar. `Runner` ejecuta el flujo y devuelve el resultado final junto con información útil del recorrido.

Las tools convierten acciones de tu aplicación en capacidades llamables por el agente. Pueden ser funciones locales, hosted tools, MCP o incluso otros agentes expuestos como herramientas. El error común es registrar demasiadas tools desde el principio; eso empeora coste, latencia y elección de acciones.

Los handoffs sirven cuando otro agente debe tomar el control, no solo cuando quieres “organizar código”. Un agente de triage puede derivar a un especialista de billing o soporte, pero cada handoff debe tener frontera clara, datos mínimos y salida esperada.

Ejemplo mínimo en Python

El arranque conceptual en Python es instalar `openai-agents`, definir un `Agent` y ejecutar `Runner.run`. Para una primera prueba, elige una tarea sin efectos laterales y registra el resultado completo, no solo `final_output`.

Puntos a revisar

Lo que conviene comprobar

Ejemplo reducido: `from agents import Agent, Runner, function_tool`; define una tool con `@function_tool`, crea `Agent(name="Soporte interno", instructions="Responde con criterios operativos", tools=[buscar_runbook])` y ejecuta `await Runner.run(agent, "Resume el runbook de despliegue")`.

No metas secretos ni permisos de escritura en el primer ejemplo. Si el agente puede llamar APIs internas, empieza con tools de lectura, timeouts cortos, errores visibles y datos sintéticos.

Checklist

Tools: namespaces, timeouts y errores visibles

La documentación de tools empuja una idea sana: agrupa capacidades cuando el catálogo crece. Un namespace pequeño como `github`, `billing` o `docs` es más interpretable que 40 funciones sueltas compitiendo por atención.

Cada tool debería tener contrato estrecho: nombre claro, descripción honesta, argumentos tipados y salida que el agente pueda usar. Si una tool falla, devuelve un error útil o propaga una excepción controlada; no escondas fallos como texto ambiguo.

Para tools async, usa timeouts por llamada. Un agente que espera 60 segundos a una integración rota no está razonando: está bloqueado. Timeouts, retries y circuit breakers son parte del diseño agentic, no optimizaciones posteriores.

Checklist

MCP dentro de OpenAI Agents SDK

El SDK soporta varias formas de MCP: hosted MCP tools a través de Responses API, servidores Streamable HTTP, SSE y stdio. La elección depende de dónde quieres que ocurra la llamada de herramienta: en infraestructura de OpenAI, en tu proceso, en tu red interna o como proceso local.

Para servidores remotos públicos, revisa `require_approval`, autenticación, scopes y origen del servidor. La propia documentación de OpenAI recomienda preferir servidores oficiales del proveedor cuando existan; un proxy de terceros con tu token es una decisión de riesgo, no una comodidad inocente.

Para servidores que controlas, usa filtrado de tools, nombres con prefijo de servidor, caching de `list_tools()` y metadatos por llamada si necesitas tenant, trace ID o política de autorización. MCP no elimina tu modelo de permisos; solo estandariza el cable.

Mi regla: todo agente con tools mutantes necesita al menos un guardrail de entrada, un guardrail de tool y una política de aprobación. Si solo hay guardrails al final, ya llegas tarde para evitar efectos laterales.

Patrón recomendado: agente de runbooks internos

Un primer caso sensato no es un agente que despliega producción, sino uno que lee runbooks internos, consulta estado y prepara un plan verificable. La salida esperada es una explicación, un checklist y quizá comandos sugeridos, no ejecución automática.

Arquitectura mínima: API interna valida la solicitud, cola lanza el workflow, Agents SDK ejecuta con tools de lectura y MCP controlado, tracing guarda el recorrido, un output guardrail valida formato y un humano aprueba cualquier paso mutante.

Cuando ese flujo sea estable, añade una segunda fase con herramientas mutantes muy estrechas: crear issue, comentar PR, abrir ticket, generar patch en rama temporal. Cada permiso nuevo debe tener métrica y rollback.

Checklist de producción

  • Define si el flujo necesita Responses API directa o Agents SDK.
  • Empieza con un agente, una tarea y tools de lectura.
  • Usa nombres de tools y namespaces que expliquen el dominio.
  • Conecta MCP solo si evita wrappers propios o integra herramientas ya existentes.
  • Filtra tools MCP y exige aprobación para acciones mutantes.
  • Pon timeouts, manejo de errores y retries explícitos.
  • Añade guardrails de entrada, salida y tool cuando haya riesgo real.
  • Activa tracing desde el primer piloto.
  • Redacta o desactiva captura de datos sensibles en traces.
  • Mide aceptación humana, coste, latencia, tools usadas y fallos por workflow.

Checklist

Errores que evitaría

El primero es usar Agents SDK porque suena más avanzado. Un agente añade no determinismo, estado y coste. Si una función normal resuelve el problema, una función normal es mejor ingeniería.

El segundo es conectar MCP servers por catálogo. Cada servidor añade herramientas, permisos y texto al entorno del agente. Elige por caso de uso, no por novedad.

El tercero es confundir trazas con seguridad. Tracing te ayuda a explicar lo ocurrido; no impide por sí solo una acción mala. Para eso necesitas scopes, aprobaciones, guardrails, entornos aislados y revisión.

Checklist

Conclusión

OpenAI Agents SDK encaja cuando quieres construir producto agentic de verdad: herramientas, MCP, especialistas, sesiones, guardrails y observabilidad. Pero cuanto más capaz es el agente, más debes tratarlo como infraestructura operativa.

Mi recomendación: arranca con un caso interno de lectura, activa trazas, limita tools, mide coste y aceptación, y solo después añade acciones mutantes. El objetivo no es demostrar que el agente puede hacerlo todo; es demostrar que puede hacer una cosa útil, observable y revisable.

Preguntas frecuentes

¿Qué es OpenAI Agents SDK?

OpenAI Agents SDK es el framework oficial de OpenAI para construir workflows agentic con agentes, tools, handoffs, sesiones, guardrails, MCP y trazas.

¿OpenAI Agents SDK reemplaza a Responses API?

No. Responses API es mejor para llamadas directas con tools y lógica propia; Agents SDK conviene cuando tu aplicación necesita orquestación, estado, delegación y observabilidad.

¿OpenAI Agents SDK funciona con MCP?

Sí. Puede usar hosted MCP tools, servidores Streamable HTTP, SSE y stdio, además de configuraciones de aprobación, filtrado y metadatos por llamada.

¿Necesito guardrails para un agente interno?

Sí si el agente acepta input de usuarios, llama herramientas, accede a datos sensibles o produce salidas que otros sistemas consumirán. Los guardrails convierten límites editoriales en checks ejecutables.

¿Tracing guarda datos sensibles?

Puede hacerlo. Algunos spans capturan inputs y outputs de generaciones o funciones, así que debes configurar redacción o desactivar captura sensible si manejas secretos o datos de clientes.

¿Cuál es un buen primer caso de uso?

Un agente de lectura que consulta documentación o runbooks internos y devuelve un plan verificable. Es útil, medible y no empieza tocando producción.

Fuentes y referencias

También te puede interesar

Claude Agent SDK en Python y TypeScriptMCP outputSchema y structuredContentMCP en producción: seguridad y permisosPlaywright MCP para agentes de IACopilot coding agent: MCP y hooks

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Leer más