Cómo elegir un framework
Ya has escrito a mano un Agent y sabes qué hace cada paso del bucle. En esta sección veremos qué hace por ti cada framework principal, en qué escenarios encaja cada uno, y reescribiremos el ejemplo del capítulo 2 usando uno de ellos.
Vale la pena recordar primero la recomendación de Anthropic en «Building effective agents»: empieza usando directamente la interfaz del modelo grande; muchos patrones se implementan en pocas líneas de código; si usas un framework, entiende qué hace por debajo.
Una tabla
| ¿Qué es? | Lenguaje | ¿Permite modelos nacionales / locales? | Adecuado para | |
|---|---|---|---|---|
| Escrito a mano (esta lección) | Un bucle while | Cualquiera | Sí, cualquier interfaz compatible con OpenAI | Aprender los principios; necesidades simples, control total |
| OpenAI Agents SDK | Framework de Agent ligero: Agent, herramientas, Handoff, guardrails, sesiones, tracing | Python (0.25.0) | Sí, la documentación oficial da la forma de conectar otros proveedores; lo probamos con Ollama local y funcionó | Quieres colaboración multi-Agent y guardrails listos para usar, sin quedar atado a un único modelo |
| Claude Agent SDK | Usa Claude Code como biblioteca: mismas herramientas, bucle, gestión de contexto | Python, TypeScript | La documentación oficial solo menciona usar Claude a través de Bedrock, Google Cloud, Microsoft Foundry y otras plataformas; no indica que se puedan conectar modelos de otros fabricantes | Necesitas un Agent de programación potente, capaz de leer y escribir archivos y ejecutar comandos |
| LangGraph | Framework de orquestación de bajo nivel: define el flujo con un grafo de «estado + nodos + aristas» | Python | Sí | Flujos complejos de larga duración, con persistencia, intervención humana y control explícito de cada paso |
| Dify | Plataforma open source para construir aplicaciones de IA, orquestación visual | Sin escribir código | Sí | No programadores que crean herramientas internas; necesidad de despliegue privado |
| Coze (扣子) | Plataforma de ByteDance; la versión open source se llama Coze Studio | Sin escribir código | — | Construcción visual |
Varios detalles que conviene aclarar:
- ¿Puede Claude Agent SDK usar modelos nacionales? Es una pregunta frecuente en las búsquedas. La documentación oficial que encontramos solo menciona la autenticación con la API Key de Anthropic, o el uso de Claude a través de plataformas en la nube como Amazon Bedrock, Google Cloud o Microsoft Foundry; no menciona la conexión de modelos de otros fabricantes.
- La licencia de Dify no es Apache 2.0 estándar, sino una «versión modificada de Apache 2.0»: sin autorización no se puede usar su código fuente para operar un servicio multiinquilino, ni eliminar el logotipo y la información de copyright del frontend. Última versión 1.20.0 (2026-11-18).
- Coze: coze.cn ahora se centra en el «asistente de oficina con IA»; el Coze Studio open source usa Apache 2.0, pero su última publicación es la v0.5.1 del 5 de 2 de 2026.
Reescribir el capítulo 2 con OpenAI Agents SDK
pip install openai-agents, y luego (descarga step_sdk.py):
import os
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled
from agents.decorators import tool
set_tracing_disabled(disabled=True) # 没有 OpenAI 平台的 key 时要关掉 tracing
client = AsyncOpenAI(base_url=os.environ.get("AGENT_BASE_URL", "http://localhost:11434/v1"),
api_key=os.environ.get("AGENT_API_KEY", "ollama"))
model = OpenAIChatCompletionsModel(model=os.environ.get("AGENT_MODEL", "qwen3:8b"), openai_client=client)
@tool
def add(a: float, b: float) -> float:
"""计算两个数的和"""
return a + b
@tool
def multiply(a: float, b: float) -> float:
"""计算两个数的积"""
return a * b
agent = Agent(name="计算助手", instructions="用工具做计算,最后用中文回答。", tools=[add, multiply], model=model)
result = Runner.run_sync(agent, "一箱苹果 24 个,我买了 17 箱,又多拿了 9 个。一共多少个?请用工具计算。")
print(result.final_output)Deberías ver (qwen3:8b local):
Se compraron 417 manzanas en total. El cálculo es el siguiente:
1. 17 cajas de manzanas: 17 × 24 = 408 unidades
2. Sumando las 9 extra: 408 + 9 = 417 unidadesComparado con el capítulo 2: el JSON Schema de tools ya no se escribe a mano (se genera a partir de las anotaciones de tipo y de los docstrings), y el bucle, el emparejamiento de tool_call_id y la concatenación de mensajes los hace Runner.
Tres puntos clave al conectar modelos que no son de OpenAI (según la documentación oficial):
- Usa
OpenAIChatCompletionsModel: el SDK usa por defecto la nueva interfaz Responses de OpenAI, que muchos otros proveedores no soportan y devolverá 404. - Si no tienes una key de la plataforma de OpenAI,
set_tracing_disabled(True); de lo contrario, la subida del tracing dará un error 401. @tooles la abreviatura de@function_toolen la nueva versión; lo que escriben los tutoriales antiguos de internet,@function_tool, todavía funciona.
Cómo elegir
BuscarMi situación es…
Toca uno para ver.
Pon a prueba tus conocimientosAl conectar Ollama local con OpenAI Agents SDK, ¿por qué usar OpenAIChatCompletionsModel?
Compruébalo
- Puedo decir en qué escenario encaja cada una de las cinco opciones
- Logré ejecutar con OpenAI Agents SDK el ejemplo de conexión a un modelo local
- Sé qué aspectos requieren atención en Claude Agent SDK y en Dify
Siguiente sección: Seguridad: permisos, sandbox e inyección de prompts.