Inicio rápido

Esta guía te muestra la forma más rápida de poner en marcha un agente con el SDK. Los ejemplos siguen los mismos pasos en JavaScript y Python. Primero, define un agente y ejecútalo. Luego, agrega herramientas y agentes especializados a medida que crezca tu flujo de trabajo.

Instala el SDK

Crea un proyecto, instala el SDK y configura tu clave de API.

1234567# JavaScript
npm install @openai/agents zod

# Python
pip install openai-agents

export OPENAI_API_KEY=sk-...

Crea y ejecuta tu primer agente

Empieza con un solo agente dedicado a una tarea concreta y ejecútalo durante un turno. El SDK se encarga de la llamada al modelo y devuelve un objeto de resultado con la salida final y el historial de ejecución.

1
2
3
4
5
6
7
8
9
10import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "History tutor",
  instructions: "You answer history questions clearly and concisely.",
  model: "gpt-6-astra",
});

const result = await run(agent, "When did the Roman Empire fall?");
console.log(result.finalOutput);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import asyncio

from agents import Agent, Runner

agent = Agent(
    name="History tutor",
    instructions="You answer history questions clearly and concisely.",
    model="gpt-6-astra",
)


async def main() -> None:
    result = await Runner.run(agent, "When did the Roman Empire fall?")
    print(result.final_output)


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

Deberías ver una respuesta breve en la terminal. Una vez que funcione ese ciclo, conserva la estructura y agrega capacidades poco a poco en lugar de empezar con un diseño complejo que incluya muchos agentes.

Pasa el estado al siguiente turno

El resultado de la primera ejecución también te permite decidir qué estado usar en el segundo turno.

Después de una transferencia, vuelve a usar lastAgent en el siguiente turno si ese especialista debe seguir a cargo.

Dale una herramienta al agente

La primera capacidad que agregues suele ser una herramienta de función o una herramienta alojada por OpenAI, como la búsqueda web o la búsqueda de archivos.

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

const historyFunFact = tool({
  name: "history_fun_fact",
  description: "Return a short history fact.",
  parameters: z.object({}),
  async execute() {
    return "Sharks are older than trees.";
  },
});

const agent = new Agent({
  name: "History tutor",
  instructions:
    "Answer history questions clearly. Use history_fun_fact when it helps.",
  tools: [historyFunFact],
});

const result = await run(
  agent,
  "Tell me something surprising about ancient life on Earth."
);

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
28import asyncio

from agents import Agent, Runner, function_tool


@function_tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."


agent = Agent(
    name="History tutor",
    instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
    tools=[history_fun_fact],
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Tell me something surprising about ancient life on Earth.",
    )
    print(result.final_output)


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

Consulta la guía general Uso de herramientas cuando necesites herramientas alojadas, buscar herramientas o usar agentes como herramientas.

Agrega agentes especializados

Un siguiente paso habitual es repartir el trabajo entre agentes especializados y dejar que un enrutador les delegue tareas mediante transferencias.

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

const historyTutor = new Agent({
  name: "History tutor",
  instructions: "Answer history questions clearly and concisely.",
});

const mathTutor = new Agent({
  name: "Math tutor",
  instructions: "Explain math step by step and include worked examples.",
});

const triageAgent = Agent.create({
  name: "Homework triage",
  instructions: "Route each homework question to the right specialist.",
  handoffs: [historyTutor, mathTutor],
});

const result = await run(
  triageAgent,
  "Who was the first president of the United States?"
);

console.log(result.finalOutput);
console.log(result.lastAgent?.name);

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
34import asyncio

from agents import Agent, Runner

history_tutor = Agent(
    name="History tutor",
    handoff_description="Specialist for history questions.",
    instructions="Answer history questions clearly and concisely.",
)

math_tutor = Agent(
    name="Math tutor",
    handoff_description="Specialist for math questions.",
    instructions="Explain math step by step and include worked examples.",
)

triage_agent = Agent(
    name="Homework triage",
    instructions="Route each homework question to the right specialist.",
    handoffs=[history_tutor, math_tutor],
)


async def main() -> None:
    result = await Runner.run(
        triage_agent,
        "Who was the first president of the United States?",
    )
    print(result.final_output)
    print(result.last_agent.name)


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

Revisa las trazas desde el principio

Por lo general, el SDK registra trazas cuando se ejecuta en el servidor. En cuanto funcione la primera ejecución, abre el panel de trazas para revisar las llamadas al modelo, las llamadas a herramientas, las transferencias y las medidas de protección antes de empezar a ajustar los prompts.

Próximos pasos

Una vez que funcione la primera ejecución, continúa con la guía que corresponda a la capacidad que quieras agregar.