Passaggi di consegne: orchestrare più agenti
In questa pagina
Passaggi di consegne: orchestrare più agenti
Un singolo agente non può fare tutto. Più domini accumuli in un unico set di istruzioni, più le linee guida si contraddicono e più le risposte diventano tiepide. I passaggi di consegne (handoffs) permettono a un agente di delegare la conversazione a un altro agente specializzato. Questo è il meccanismo chiave per costruire sistemi multi-agente in cui ogni agente eccelle nel proprio dominio.
Il concetto di passaggio di consegne
Un passaggio di consegne è un trasferimento di controllo da un agente a un altro. Quando l’Agente A passa il testimone all’Agente B, quest’ultimo prende il sopravvento e genera la risposta. Il Runner gestisce questa transizione automaticamente: non devi scrivere logica di routing esplicita né chiamare manualmente il secondo agente. Nell’esempio seguente, l’agente di triage riceve un reclamo sull’importo di una fattura, riconosce il dominio e passa il testimone. Il cliente, nel frattempo, vede solo una conversazione continua.
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)
Personalizzare la descrizione del passaggio
Di default, un passaggio di consegne utilizza il nome e le istruzioni dell’agente di destinazione. Questo funziona bene finché i nomi sono descrittivi, ma diventa rischioso quando due agenti si assomigliano. In questi casi, puoi personalizzare la descrizione per guidare il routing elencando gli scenari specifici che dovrebbero attivare ogni trasferimento.
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.",
),
],
)
Passaggi di consegne con contesto
Un trasferimento è utile solo se l’agente che subentra sa cosa sta succedendo. Quando un agente esegue un passaggio di consegne, la cronologia della conversazione viene passata all’agente di destinazione: il nuovo agente ha accesso a tutto ciò che è stato detto finora, quindi il cliente non deve ripetere il proprio problema. Oltre a questo, il contesto tipizzato trasporta dati di sessione strutturati (ID cliente, piano abbonato, ticket passati) e rimane accessibile agli strumenti dell’agente entrante.
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,
)
Pattern: Triage a tre livelli
I passaggi di consegne non si limitano al routing orizzontale. Replicano anche la struttura di escalation di un vero servizio di assistenza. Ecco un pattern produttivo a tre livelli: L1 gestisce le richieste di routine, trasferisce i problemi di configurazione avanzata a L2, e L2 scala gli argomenti di architettura a L3. Nota che il livello 3 si affida a un modello più capace, poiché vede solo i casi già filtrati dai due livelli precedenti.
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",
)
Passaggi di consegne bidirezionali
La catena può anche essere circolare: due agenti possono trasferirsi il controllo avanti e indietro. Questo è tipico quando un prospect pone una domanda tecnica durante una conversazione di vendita, per poi tornare ai prezzi una volta rassicurato.
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]
Attenzione ai loop infiniti: è consigliabile utilizzare una guardia o max_turns. Senza questo limite, una richiesta ambigua può far rimbalzare la conversazione da un agente all’altro fino all’esaurimento della tua quota.
Tracciare i passaggi di consegne
Infine, devi sapere chi ha effettivamente risposto, sia per verificare il tuo routing sia per le tue statistiche di supporto. Il RunResult ti indica quale agente ha prodotto ultimamente la risposta.
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
Prendi l’abitudine di registrare questo valore: se un agente di triage mantiene il controllo su richieste che avrebbe dovuto trasferire, la distribuzione di last_agent rivelerà il problema ben prima del feedback dei clienti.
Punti chiave
- I passaggi di consegne ti permettono di delegare la conversazione a un agente specializzato
- La cronologia della conversazione viene passata all’agente di destinazione
- Usa
Handoff(agent=..., description=...)per guidare il routing - Il contesto condiviso (
RunContextWrapper) è accessibile a tutti gli agenti result.last_agent.nameindica quale agente ha risposto infine- Proteggi i passaggi di consegne bidirezionali con
max_turnsper prevenire i loop