Orquestração e transferências de controle

Fluxos de trabalho com vários agentes são úteis quando cada especialista deve cuidar de uma parte do trabalho. Ao projetar o fluxo, a primeira decisão é definir quem dará a resposta final ao usuário em cada ramificação.

Escolha o padrão de orquestração

Transfira o controle para delegar a resposta

A transferência de controle é o padrão mais indicado quando o especialista deve dar a próxima resposta, em vez de apenas ajudar nos bastidores.

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

const billingAgent = new Agent({ name: "Billing agent" });
const refundAgent = new Agent({ name: "Refund agent" });

const triageAgent = Agent.create({
  name: "Triage agent",
  handoffs: [billingAgent, handoff(refundAgent)],
});

1
2
3
4
5
6
7
8
9from agents import Agent, handoff

billing_agent = Agent(name="Billing agent")
refund_agent = Agent(name="Refund agent")

triage_agent = Agent(
    name="Triage agent",
    handoffs=[billing_agent, handoff(refund_agent)],
)

Para que o roteamento seja fácil de entender, siga estas orientações.

• Atribua a cada especialista uma função de escopo delimitado.
• Use uma descrição curta e específica em handoffDescription.
• Crie uma ramificação apenas quando ela realmente exigir instruções, ferramentas ou políticas diferentes.

Em casos mais avançados, as transferências de controle também podem incluir metadados estruturados ou um histórico filtrado. Consulte a documentação do SDK para ver as APIs específicas, pois a forma de usá-las varia conforme a linguagem.

Use agentes como ferramentas em fluxos com um agente gerente

Use agent.asTool() quando o agente principal precisar continuar responsável pela resposta final e chamar especialistas para auxiliá-lo.

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

const summarizer = new Agent({
  name: "Summarizer",
  instructions: "Generate a concise summary of the supplied text.",
});

const mainAgent = new Agent({
  name: "Research assistant",
  tools: [
    summarizer.asTool({
      toolName: "summarize_text",
      toolDescription: "Generate a concise summary of the supplied text.",
    }),
  ],
});

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

summarizer = Agent(
    name="Summarizer",
    instructions="Generate a concise summary of the supplied text.",
)

main_agent = Agent(
    name="Research assistant",
    tools=[
        summarizer.as_tool(
            tool_name="summarize_text",
            tool_description="Generate a concise summary of the supplied text.",
        )
    ],
)

Esse padrão costuma ser mais adequado quando:

• o gerente precisa reunir as contribuições dos especialistas em uma resposta final
• o especialista executa uma tarefa de escopo delimitado, como resumir ou classificar conteúdo
• você quer manter um único fluxo principal estável e chamar os especialistas dentro dele, sem transferir a responsabilidade pela resposta

Adicione especialistas apenas quando o contrato mudar

Sempre que possível, comece com um único agente. Adicione especialistas apenas quando isso ajudar de forma significativa a isolar capacidades ou políticas, tornar os prompts mais claros ou facilitar a leitura dos rastros de execução.

Dividir o trabalho cedo demais aumenta o número de prompts, de rastros de execução e de pontos que exigem aprovação, sem necessariamente melhorar o fluxo.

Próximos passos

Depois de definir quem responde ao usuário, consulte o guia que aborda sua próxima dúvida sobre execução ou estado.