Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Transferências: Orquestração de Múltiplos Agentes

Aula 12 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Transferências: Orquestração de Múltiplos Agentes
  2. O Conceito de Transferência
  3. Personalização da Descrição da Transferência
  4. Transferências com Contexto
  5. Padrão: Triagem de Três Níveis
  6. Transferências Bidirecionais
  7. Rastreio de Transferências
  8. Pontos-chave

Transferências: Orquestração de Múltiplos Agentes

Um único agente não consegue fazer tudo. Quanto mais domínios acumular num único conjunto de instruções, mais as diretrizes se contradizem e mais mornas se tornam as respostas. As transferências permitem que um agente delegue a conversa a outro agente especializado. Este é o mecanismo fundamental para construir sistemas multiagente onde cada agente se destaca no seu próprio domínio.

O Conceito de Transferência

Uma transferência é a passagem de controlo de um agente para outro. Quando o Agente A transfere para o Agente B, o Agente B assume e gera a resposta. O Runner gere esta transição automaticamente: não precisa de escrever lógica de encaminhamento explícita nem de chamar manualmente o segundo agente. No exemplo abaixo, o agente de triagem recebe uma reclamação sobre o valor de uma fatura, reconhece o domínio e passa o testemunho. O cliente, entretanto, vê apenas uma conversa contínua.

from agents import Agent, Runner

billing_agent = Agent(
    name="Billing Agent",
    instructions="""You handle billing questions: invoices, payments,
    refunds, subscriptions. Respond precisely and professionally.""",
    model="gpt-5.6-terra",
)

technical_agent = Agent(
    name="Technical Agent",
    instructions="""You handle technical support: bugs, configuration,
    installation, troubleshooting. Provide step-by-step instructions.""",
    model="gpt-5.6-terra",
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="""You are the first point of contact.
    Analyze the customer's request and transfer it to the appropriate agent.
    - Billing questions → Billing Agent
    - Technical questions → Technical Agent""",
    handoffs=[billing_agent, technical_agent],
    model="gpt-5.6-terra",
)

result = Runner.run_sync(
    triage_agent,
    "My latest invoice seems incorrect; the amount is too high."
)
# The triage agent hands off to the billing agent
print(f"Answered by: {result.last_agent.name}")
print(result.final_output)

Personalização da Descrição da Transferência

Por predefinição, uma transferência utiliza o nome e as instruções do agente de destino. Isto funciona bem enquanto os nomes forem descritivos, mas torna-se arriscado quando dois agentes são semelhantes. Nesses casos, pode personalizar a descrição para orientar o encaminhamento, listando os cenários específicos que devem desencadear cada transferência.

from agents import Handoff

triage_agent = Agent(
    name="Triage Agent",
    instructions="Transfer the request to the specialized agent.",
    handoffs=[
        Handoff(
            agent=billing_agent,
            description="Transfer for payment questions, invoices, refunds, and subscriptions.",
        ),
        Handoff(
            agent=technical_agent,
            description="Transfer for technical issues, bugs, and configuration help requests.",
        ),
    ],
)

Transferências com Contexto

Uma transferência só é útil se o agente que assume souber o que se passa. Quando um agente efetua uma transferência, o histórico da conversa é passado ao agente de destino: o novo agente tem acesso a tudo o que foi dito até ao momento, pelo que o cliente não precisa de repetir o seu problema. Além disso, o contexto tipado transporta dados estruturados da sessão — ID do cliente, plano subscrito, tickets anteriores — e permanece acessível às ferramentas do agente incoming.

from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool

@dataclass
class CustomerContext:
    client_id: str
    plan: str
    ticket_history: list[str]

@function_tool
def view_invoice(ctx: RunContextWrapper[CustomerContext], month: str) -> str:
    """Views the invoice for a given month for the current customer."""
    client_id = ctx.context.client_id
    return f"Invoice for {month} for {client_id}: €149.99 (plan {ctx.context.plan})"

billing_agent = Agent(
    name="Billing Agent",
    instructions="You handle billing. Use the customer context.",
    tools=[view_invoice],
    model="gpt-5.6-terra",
)

triage_agent = Agent(
    name="Triage",
    instructions="Transfer to the right agent.",
    handoffs=[billing_agent],
    model="gpt-5.6-terra",
)

context = CustomerContext(
    client_id="cli_456",
    plan="Pro",
    ticket_history=["Ticket #001: Slow connection"]
)

result = Runner.run_sync(
    triage_agent,
    "Can you check my invoice for March?",
    context=context,
)

Padrão: Triagem de Três Níveis

As transferências não se limitam ao encaminhamento horizontal. Elas também replicam a estrutura de escalonamento de um serviço de apoio real. Eis um padrão de produção com três níveis: o N1 trata de consultas rotineiras, transfere problemas de configuração avançada para o N2, e o N2 escala tópicos de arquitetura para o N3. Note que o nível 3 recorre a um modelo mais capaz, uma vez que apenas vê casos já filtrados pelos dois níveis anteriores.

level3_agent = Agent(
    name="L3 Technical Expert",
    instructions="""You are a level 3 technical expert.
    You handle complex architecture and infrastructure problems.
    If you cannot resolve the issue, indicate that human escalation is necessary.""",
    model="gpt-5.6-sol",  # The most capable model for complex cases
)

level2_agent = Agent(
    name="L2 Technical Support",
    instructions="""You are a level 2 technician.
    You handle advanced configuration problems.
    If the problem is too complex, transfer to level 3.""",
    handoffs=[level3_agent],
    model="gpt-5.6-terra",
)

level1_agent = Agent(
    name="L1 Customer Support",
    instructions="""You are the first point of contact for customer support.
    Handle simple questions (password, account, navigation).
    Transfer technical problems to level 2.""",
    handoffs=[level2_agent],
    model="gpt-5.6-terra",
)

Transferências Bidirecionais

A cadeia também pode ser circular: dois agentes podem transferir o controlo entre si. Isto é típico quando um potencial cliente faz uma pergunta técnica durante uma conversa de vendas e, depois de tranquilizado, regressa aos preços.

sales_agent = Agent(
    name="Sales Agent",
    instructions="""You sell products. If the customer asks
    for technical support, transfer to the technical agent.""",
)

support_agent = Agent(
    name="Support Agent",
    instructions="""You provide technical support. If the customer
    wants to buy something, transfer to the sales agent.""",
)

# Bidirectional handoffs
sales_agent.handoffs = [support_agent]
support_agent.handoffs = [sales_agent]

Cuidado com loops infinitos: recomenda-se uma salvaguarda ou max_turns. Sem este limite, um pedido ambíguo pode fazer saltar a conversa de um agente para outro até esgotar a sua quota.

Rastreio de Transferências

Por fim, precisa de saber quem respondeu efetivamente — tanto para verificar o seu encaminhamento como para as suas estatísticas de apoio. O RunResult indica-lhe qual o agente que produziu finalmente a resposta.

result = Runner.run_sync(triage_agent, "I have a critical bug")

print(f"Initial agent: triage_agent")
print(f"Final agent: {result.last_agent.name}")
# Prints "Technical Agent" if triage worked correctly

Adote o hábito de registar este valor: se um agente de triagem mantiver o controlo de pedidos que deveria ter transferido, a distribuição de last_agent revelará o problema muito antes do feedback dos clientes.

Pontos-chave

  • As transferências permitem delegar a conversa a um agente especializado
  • O histórico da conversa é passado ao agente de destino
  • Utilize Handoff(agent=..., description=...) para orientar o encaminhamento
  • O contexto partilhado (RunContextWrapper) está acessível a todos os agentes
  • result.last_agent.name indica qual o agente que respondeu finalmente
  • Proteja as transferências bidirecionais com max_turns para evitar loops