Transferências: Orquestração de Múltiplos Agentes
Nesta página
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.nameindica qual o agente que respondeu finalmente- Proteja as transferências bidirecionais com
max_turnspara evitar loops