Ir al contenido principal
Español— Elegir un idioma
Menú

Anatomía del SDK: Agent, Runner, Tool, Guardrail

Lección 5 de 25 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Anatomía del SDK: Agent, Runner, Tool, Guardrail
  2. Agent: Configuración
  3. Runner: Ejecución
  4. Tool: Capacidades
  5. Guardrail: Seguridad
  6. Cómo interactúan estas piezas
  7. Puntos clave

Anatomía del SDK: Agent, Runner, Tool, Guardrail

El SDK de Agents se sustenta en cuatro conceptos clave: Agent, Runner, Tool y Guardrail. Cada uno tiene una única responsabilidad. Su interacción —quién decide, quién ejecuta, quién actúa y quién controla— es lo que hace que el SDK sea legible una vez que lo interiorizas.

1

Agent — El cerebro

Define las instrucciones, el modelo, las herramientas y los guardarrailes. Esta es la configuración de tu agente.

2

Runner — El motor de ejecución

Orquesta el bucle de razonamiento: envía solicitudes, ejecuta herramientas y gestiona los traspasos.

3

Tool — Capacidades

Funciones que el agente puede invocar: búsqueda web, ejecución de código, llamadas a API y más.

4

Guardrail — Seguridad

Valida las entradas y salidas del agente. Bloquea solicitudes peligrosas o fuera de tema.

Agent: Configuración

La clase Agent es puramente declarativa: no ejecuta nada, solo describe. Todo lo que define el comportamiento de tu agente reside en un único lugar.

from agents import Agent, function_tool, WebSearchTool

@function_tool
def get_price(product: str) -> str:
    """Recupera el precio de un producto."""
    prices = {"widget": "29,99 €", "gadget": "49,99 €"}
    return prices.get(product, "Producto desconocido")

agent = Agent(
    name="Agente de ventas",
    instructions="""Eres un agente de ventas para una tienda online.
    Ayuda a los clientes a encontrar productos y conocer sus precios.
    Responde siempre en francés con un tono profesional.""",
    model="gpt-5.6-terra",
    tools=[get_price, WebSearchTool()],
    handoff_description="Agente especializado en la venta de productos",
    output_type=None,  # o un tipo Pydantic para forzar un formato de salida
)

Parámetros clave de Agent:

  • name: Identificador legible por humanos para el agente
  • instructions: El prompt del sistema que define el comportamiento
  • model: El modelo a utilizar (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: La lista de herramientas disponibles
  • handoff_description: Descripción utilizada para los traspasos entre agentes
  • output_type: Tipo Pydantic para estructurar la salida

Runner: Ejecución

El Runner es el motor que ejecuta tu agente. Gestiona todo el bucle y ofrece tres modos según tu contexto de llamada.

from agents import Runner

# Modo síncrono (desarrollo)
result = Runner.run_sync(agent, "¿Cuál es el precio del widget?")

# Modo asíncrono (producción)
result = await Runner.run(agent, "¿Cuál es el precio del widget?")

# Modo streaming (tiempo real)
result = Runner.run_streamed(agent, "¿Cuál es el precio del widget?")

Independientemente del modo, obtienes un RunResult, que contiene mucho más que la respuesta visible. El historial completo te permite reanudar una conversación, y last_agent se vuelve esencial tan pronto como varios agentes se traspasan el control entre sí.

result = Runner.run_sync(agent, "¿Cuál es el precio del widget?")

# La respuesta final del agente
print(result.final_output)

# El historial completo de la conversación
print(result.to_input_list())

# El último agente activo (útil con traspasos)
print(result.last_agent.name)

Tool: Capacidades

El SDK admite tres formas de declarar herramientas, de la más común a la más arquitectónica.

1. Herramientas de función (las más comunes)

Una función de Python decorada se convierte en una herramienta; el SDK infiere el esquema a partir de la firma y el docstring.

from agents import function_tool

@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
    """Envía un correo electrónico a un destinatario."""
    # Tu lógica de envío aquí
    return f"Correo enviado a {recipient}"

2. Herramientas alojadas por OpenAI

Estas herramientas se ejecutan en el lado de OpenAI: no escribes la lógica de búsqueda ni el sandbox de Python.

from agents import WebSearchTool, FileSearchTool, CodeInterpreterTool

tools = [
    WebSearchTool(),                               # Búsqueda web
    FileSearchTool(vector_store_ids=["vs_123"]),   # Búsqueda de archivos
    CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),                          # Ejecución de código
]

3. Agentes como herramientas

Un agente puede utilizar a otro como herramienta. El coordinador siguiente delega la investigación sin ceder nunca el control de la conversación, lo que distingue esto de un traspaso.

search_agent = Agent(
    name="Investigador",
    instructions="Buscas información precisa.",
    tools=[WebSearchTool()],
)

primary_agent = Agent(
    name="Coordinador",
    instructions="Coordina la investigación.",
    tools=[search_agent.as_tool(
        tool_name="search",
        tool_description="Realiza una investigación en profundidad"
    )],
)

Guardrail: Seguridad

Un guardarraíl es un agente de control situado delante de tu agente de negocio. Aquí, un verificador comprueba si la solicitud pertenece al ámbito de ventas antes de que el agente de ventas responda.

from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner

guardrail_agent = Agent(
    name="Verificador",
    instructions="Determina si la solicitud trata sobre ventas. Responde true o false.",
    output_type=bool,
)

async def verify_topic(ctx, agent, input_data):
    result = await Runner.run(guardrail_agent, input_data, context=ctx)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=not result.final_output,
    )

protected_agent = Agent(
    name="Agente de ventas protegido",
    instructions="Eres un agente de ventas.",
    input_guardrails=[
        InputGuardrail(guardrail_function=verify_topic),
    ],
)

Si el guardarraíl se activa (tripwire_triggered=True), la ejecución se detiene y se lanza una excepción InputGuardrailTripwireTriggered. Planifica capturar esto en tu aplicación; de lo contrario, devolverás un error 500 a un usuario que simplemente ha hecho una pregunta fuera de tema.

Cómo interactúan estas piezas

El flujo completo se ejecuta de la siguiente manera:

  1. Llamas a Runner.run(agent, message)
  2. El Runner comprueba los guardarrailes de entrada
  3. El Runner envía el mensaje al modelo del Agent
  4. Si el modelo solicita una tool, el Runner la ejecuta
  5. El Runner devuelve el resultado al modelo (vuelta al paso 3)
  6. Cuando el modelo produce una respuesta final, el Runner comprueba los guardarrailes de salida
  7. Se devuelve el RunResult

Puntos clave

  • Agent define el comportamiento (instrucciones, modelo, herramientas)
  • Runner orquesta la ejecución del bucle del agente
  • Declara herramientas con @function_tool, clases integradas o .as_tool()
  • Los guardarrailes validan entradas y salidas por seguridad
  • RunResult contiene la respuesta final y el historial completo