Como executar agentes

Definir um agente é apenas a etapa de configuração. Para entender como ele funciona em tempo de execução, é preciso saber o que acontece em cada execução, como a conversa continua no turno seguinte e como o fluxo se comporta quando precisa aguardar uma aprovação ou a conclusão de uma chamada de ferramenta.

O ciclo do agente

Cada execução do SDK corresponde a um turno do aplicativo. O executor repete o ciclo até encontrar uma condição de parada.

1. Chama o modelo do agente atual com os dados de entrada já preparados.
2. Examina a saída do modelo.
3. Se o modelo gerou chamadas de ferramentas, executa as chamadas e continua o ciclo.
4. Se o modelo transferiu o controle para outro especialista, troca de agente e continua o ciclo.
5. Se o modelo gerou uma resposta final e não há mais chamadas de ferramentas a executar, retorna um resultado.

Esse ciclo é o conceito central do SDK. É nele que se baseiam as ferramentas, as transferências entre agentes, as aprovações e a transmissão de eventos.

Escolha uma estratégia para a conversa

Há quatro formas comuns de levar o estado da conversa para o turno seguinte.

Na maioria dos aplicativos, escolha uma estratégia por conversa. Reenviar o histórico local e usar o estado gerenciado pelo servidor pode duplicar o contexto, a menos que você concilie explicitamente as duas camadas.

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())

As sessões são a melhor opção por padrão quando você precisa de memória persistente, de fluxos de aprovação que possam ser retomados ou de armazenamento controlado pelo seu aplicativo.

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())

Use conversationId quando vários sistemas precisarem compartilhar uma conversa identificada por nome. Use previousResponseId quando quiser a opção de menor custo para continuar de uma resposta para a seguinte.

Receba eventos à medida que a execução avança

A transmissão de eventos usa o mesmo ciclo do agente e as mesmas estratégias de estado. A única diferença é que você consome os eventos enquanto a execução ainda está em andamento.

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())

Siga estas três regras na prática.

• Aguarde o fim da transmissão antes de considerar a execução encerrada.
• Se a execução pausar para aprovação, resolva as interrupções em interruptions e retome a execução a partir de state, sem iniciar um novo turno do usuário.
• Se você cancelar a transmissão no meio de um turno e quiser continuá-lo depois, retome o turno inacabado a partir de state.

Diferencie pausas e falhas

Duas situações merecem atenção quando a execução sai do fluxo normal.

• Falhas de execução ou validação, por exemplo, quando a execução atinge o limite de turnos, uma regra de proteção gera uma exceção ou uma ferramenta retorna um erro.
• Pausas esperadas, como pedidos de aprovação humana, em que a execução é interrompida de propósito e deve ser retomada depois a partir do mesmo estado.

Ao processar uma aprovação, retome a execução pausada em vez de iniciar um novo turno. Assim, a contagem de turnos, o histórico e os IDs de continuação gerenciados pelo servidor permanecem consistentes.

Próximos passos

Depois de entender o ciclo de execução, escolha o guia que trata da próxima parte do fluxo que você precisa definir.