Ejecución de agentes

Definir un agente es solo el primer paso. Al ejecutarlo, necesitas saber qué ocurre en cada ejecución, cómo continúa la conversación en el siguiente turno y qué sucede cuando el flujo de trabajo se pausa en espera de una aprobación o del resultado de una herramienta.

El ciclo del agente

Cada ejecución del SDK corresponde a un turno de la aplicación. El ejecutor repite este ciclo hasta que se cumple una condición de parada:

1. Llama al modelo del agente actual con la entrada preparada.
2. Examina la salida del modelo.
3. Si el modelo generó llamadas a herramientas, las ejecuta y continúa.
4. Si el modelo transfirió el control a otro especialista, cambia de agente y continúa.
5. Si el modelo generó una respuesta final y no quedan llamadas a herramientas por ejecutar, devuelve un resultado.

Este ciclo es la base del SDK. Las herramientas, las transferencias entre agentes, las aprobaciones y la transmisión en tiempo real se apoyan en él sin sustituirlo.

Elige una estrategia para la conversación

Hay cuatro formas habituales de conservar el estado de un turno al siguiente:

En la mayoría de las aplicaciones, elige una sola estrategia por conversación. Si vuelves a enviar el historial local y a la vez usas el estado que administra el servidor, puedes duplicar el contexto, a menos que concilies explícitamente ambas capas.

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

const agent = new Agent({
  name: "Tour guide",
  instructions: "Answer with compact travel facts.",
});

const session = new MemorySession();

const firstTurn = await run(agent, "What city is the Golden Gate Bridge in?", {
  session,
});
console.log(firstTurn.finalOutput);

const secondTurn = await run(agent, "What state is it in?", { session });
console.log(secondTurn.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 agents import Agent, Runner, SQLiteSession

agent = Agent(
    name="Tour guide",
    instructions="Answer with compact travel facts.",
)

session = SQLiteSession("conversation_123")


async def main() -> None:
    first_turn = await Runner.run(
        agent,
        "What city is the Golden Gate Bridge in?",
        session=session,
    )
    print(first_turn.final_output)

    second_turn = await Runner.run(
        agent,
        "What state is it in?",
        session=session,
    )
    print(second_turn.final_output)


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

Las sesiones son la mejor opción predeterminada si necesitas memoria persistente, flujos de aprobación que puedas reanudar o almacenamiento que controle tu aplicación.

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

const agent = new Agent({
  name: "Assistant",
  instructions: "Reply very concisely.",
});

const client = new OpenAI();
const { id: conversationId } = await client.conversations.create({});

const first = await run(agent, "What city is the Golden Gate Bridge in?", {
  conversationId,
});
console.log(first.finalOutput);

const second = await run(agent, "What state is it in?", {
  conversationId,
});
console.log(second.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
27import asyncio

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="Reply very concisely.",
)


async def main() -> None:
    first = await Runner.run(
        agent,
        "What city is the Golden Gate Bridge in?",
    )
    print(first.final_output)

    second = await Runner.run(
        agent,
        "What state is it in?",
        previous_response_id=first.last_response_id,
    )
    print(second.final_output)


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

Usa conversationId cuando varios sistemas deban compartir una misma conversación con nombre. Usa previousResponseId si quieres la opción de menor costo para continuar de una respuesta a la siguiente.

Recibe eventos a medida que avanza la ejecución

La transmisión en tiempo real usa el mismo ciclo del agente y las mismas estrategias para conservar el estado. La única diferencia es que consumes los eventos mientras la ejecución sigue en curso.

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

const agent = new Agent({
  name: "Planet guide",
  instructions: "Answer with short facts.",
});

const stream = await run(agent, "Give me three short facts about Saturn.", {
  stream: true,
});

for await (const event of stream) {
  if (
    event.type === "raw_model_stream_event" &&
    event.data.type === "output_text_delta"
  ) {
    process.stdout.write(event.data.delta);
  }
}

await stream.completed;
console.log("\nFinal:", stream.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
29import asyncio

from openai.types.responses import ResponseTextDeltaEvent

from agents import Agent, Runner

agent = Agent(
    name="Planet guide",
    instructions="Answer with short facts.",
)


async def main() -> None:
    stream = Runner.run_streamed(
        agent,
        "Give me three short facts about Saturn.",
    )

    async for event in stream.stream_events():
        if event.type == "raw_response_event" and isinstance(
            event.data, ResponseTextDeltaEvent
        ):
            print(event.data.delta, end="", flush=True)

    print(f"\nFinal: {stream.final_output}")


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

Ten en cuenta estas tres reglas:

• Espera a que termine la transmisión antes de dar por concluida la ejecución.
• Si la ejecución se pausa para solicitar aprobación, resuelve interruptions y reanuda la ejecución desde state en lugar de iniciar un nuevo turno de usuario.
• Si cancelas la transmisión a mitad de un turno y quieres continuarlo más adelante, reanuda el turno pendiente desde state.

Gestiona las pausas y los errores

Cuando la ejecución se aparta de su curso habitual, distingue entre dos tipos de situaciones:

• Errores de ejecución o de validación, por ejemplo, cuando se alcanza el límite de turnos, un mecanismo de protección genera una excepción o falla una herramienta.
• Pausas previstas, como las solicitudes de aprobación humana, en las que la ejecución se interrumpe de forma intencional y debe reanudarse más adelante desde el mismo estado.

Trata las solicitudes de aprobación como pausas en la ejecución, sin iniciar turnos nuevos. Así mantienes la coherencia entre el recuento de turnos, el historial y los ID de continuación que administra el servidor.

Próximos pasos

Una vez que entiendas el ciclo de ejecución, consulta la guía que corresponda al siguiente aspecto del flujo de trabajo que necesites diseñar.