Definición de agentes

Un agente es la unidad básica de un flujo de trabajo que usa el SDK. Reúne un modelo y sus instrucciones, y puede incorporar herramientas, mecanismos de protección, servidores MCP, transferencias de control y resultados estructurados para definir cómo se comporta durante la ejecución.

Qué configurar en un agente

Usa la configuración del agente para definir los aspectos propios de ese especialista.

Empieza con un agente especializado

Define el agente más sencillo que pueda encargarse de una tarea concreta. Agrega más agentes solo cuando necesites separar responsabilidades, darles instrucciones distintas o usar diferentes interfaces de herramientas o políticas de aprobación.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import { Agent, tool } from "@openai/agents";
import { z } from "zod";

const getWeather = tool({
  name: "get_weather",
  description: "Return the weather for a given city.",
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

const agent = new Agent({
  name: "Weather bot",
  instructions: "You are a helpful weather bot.",
  model: "gpt-6-astra",
  tools: [getWeather],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from agents import Agent, function_tool


@function_tool
def get_weather(city: str) -> str:
    """Return the weather for a given city."""
    return f"The weather in {city} is sunny."


agent = Agent(
    name="Weather bot",
    instructions="You are a helpful weather bot.",
    model="gpt-6-astra",
    tools=[get_weather],
)

Define las instrucciones, las transferencias de control y los resultados

Presta especial atención a estas tres decisiones de configuración.

• Empieza con instrucciones estáticas en instructions. Cuando las instrucciones dependan del usuario, del tenant o del contexto de la ejecución en curso, usa una función de callback que genere las instrucciones de forma dinámica en lugar de concatenar cadenas en el punto de llamada.
• Escribe una descripción breve y concreta en handoffDescription para que los agentes que distribuyen las tareas sepan cuándo elegir a este especialista.
• Usa outputType cuando el código que procesa el resultado necesite datos tipados en lugar de texto libre.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import { Agent, run } from "@openai/agents";
import { z } from "zod";

const calendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const agent = new Agent({
  name: "Calendar extractor",
  instructions: "Extract calendar events from text.",
  outputType: calendarEvent,
});

const result = await run(agent, "Dinner with Priya and Sam on Friday.");

console.log(result.finalOutput);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30import asyncio

from pydantic import BaseModel

from agents import Agent, Runner


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


agent = Agent(
    name="Calendar extractor",
    instructions="Extract calendar events from text.",
    output_type=CalendarEvent,
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Dinner with Priya and Sam on Friday.",
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

Usa prompt cuando quieras hacer referencia a una configuración de prompt guardada en la API de Responses en lugar de incluir todo el prompt del sistema en el código.

Separa el contexto local del contexto del modelo

El SDK te permite pasar el estado y las dependencias de la aplicación a una ejecución sin enviarlos al modelo. Usa el contexto local para pasar información del usuario autenticado, clientes de bases de datos, componentes de registro y funciones auxiliares.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const fetchUserAge = tool({
  name: "fetch_user_age",
  description: "Return the age of the current user.",
  parameters: z.object({}),
  // TypeScript users can type this as RunContext<{ name: string; uid: number }>.
  async execute(_args, runContext) {
    return `User ${runContext?.context.name} is 47 years old`;
  },
});

const agent = new Agent({
  name: "Assistant",
  tools: [fetchUserAge],
});

const result = await run(agent, "What is the age of the user?", {
  context: { name: "John", uid: 123 },
});

console.log(result.finalOutput);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35import asyncio
from dataclasses import dataclass

from agents import Agent, RunContextWrapper, Runner, function_tool


@dataclass
class UserInfo:
    name: str
    uid: int


@function_tool
async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str:
    """Fetch the age of the current user."""
    return f"The user {wrapper.context.name} is 47 years old."


agent = Agent[UserInfo](
    name="Assistant",
    tools=[fetch_user_age],
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "What is the age of the user?",
        context=UserInfo(name="John", uid=123),
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

Ten presente a qué información tiene acceso cada uno.

• El modelo ve el historial de la conversación.
• Tu código ve el contexto de la ejecución.

Si el modelo necesita un dato, inclúyelo en las instrucciones o en la entrada, o haz que esté disponible mediante la recuperación de información o una herramienta. Si solo lo necesita el entorno de ejecución, mantenlo en el contexto local.

Cuándo dividir un agente en varios

Divide un agente cuando un solo especialista no deba encargarse de toda la respuesta o cuando las funciones que cumple sean muy distintas entre sí. Estos son algunos motivos habituales.

• Un especialista necesita una interfaz de herramientas o de MCP diferente.
• Un especialista necesita una política de aprobación o un mecanismo de protección diferente.
• Una rama del flujo de trabajo necesita otro modelo u otro estilo de respuesta.
• Quieres que las trazas muestren explícitamente cómo se asignan las tareas en lugar de usar un solo prompt extenso.

Próximos pasos

Una vez que hayas definido bien al primer especialista, consulta la guía que responda a tu siguiente pregunta de diseño.