Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Passaggi di consegne: orchestrare più agenti

Lezione 12 di 25 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Passaggi di consegne: orchestrare più agenti
  2. Il concetto di passaggio di consegne
  3. Personalizzare la descrizione del passaggio
  4. Passaggi di consegne con contesto
  5. Pattern: Triage a tre livelli
  6. Passaggi di consegne bidirezionali
  7. Tracciare i passaggi di consegne
  8. Punti chiave

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.name indica quale agente ha risposto infine
  • Proteggi i passaggi di consegne bidirezionali con max_turns per prevenire i loop