Come progettare un handoff affidabile tra agent AI

Un agente legge una richiesta, capisce che serve uno specialista e gli passa il lavoro. La demo finisce qui. Il sistema reale comincia dalla domanda successiva: che cosa è stato trasferito, con quali prove e fino a quale limite?

Se il secondo agente riceve solo un riassunto libero, dovrà ricostruire obiettivo, stato e vincoli. Se riceve tutta la conversazione, può ereditare rumore, dati non necessari e istruzioni in conflitto. Se riceve anche credenziali o permessi del primo, un semplice errore di routing diventa un effetto operativo.

Un handoff affidabile è una transizione di stato con un contratto verificabile. Trasferisce un incarico. Non trasferisce automaticamente autorità, responsabilità o fiducia.

Decidi se serve davvero un handoff

Non ogni collaborazione fra agenti richiede un passaggio di controllo.

OpenAI Agents SDK distingue due pattern utili:

Questa differenza cambia il contratto. Se un agente traduttore è chiamato come tool, può restituire testo e note al manager. Se un agente amministrativo prende in carico una pratica, deve ricevere stato, scadenza, documenti ammessi e criteri di chiusura.

Usa un handoff quando sono vere almeno queste condizioni:

• cambia l'owner operativo del prossimo tratto

• cambiano istruzioni o competenze necessarie

• il ricevente deve poter proseguire per più passi

• esiste un punto chiaro di accettazione o rifiuto

• il passaggio deve restare osservabile come evento autonomo

Se vuoi solo una seconda opinione, una classificazione o un estratto, l'agente come tool mantiene il flusso più semplice. La complessità multi-agent ha un costo: più stati, più failure mode, più superfici da testare.

Scrivi il contratto minimo dell'handoff

Un buon payload non prova a raccontare tutto. Contiene ciò che serve al ricevente per decidere se accettare e come iniziare.

handoff_id: ho_20260903_00421
from_agent: intake.v3
to_agent: contract_review.v2
task_type: verify_missing_fields
reason_code: contract_data_incomplete
requested_action: identify_missing_required_fields
case_ref: case_8f12
state_version: 7
evidence_refs:
  - doc:contract_draft@sha256:91ab...
  - rule:required_fields@4
constraints:
  allowed_actions:
    - read_case
    - create_review_note
  forbidden_actions:
    - send_message
    - update_contract
due_at: 2026-09-03T14:00:00+02:00
acceptance_criteria:
  - every_missing_field_has_evidence
  - no_inferred_personal_data
idempotency_key: case_8f12:state_7:verify_missing_fields

I campi fanno lavori diversi:

• reason_code spiega perché il routing è avvenuto

• requested_action definisce il prossimo outcome, non una vaga competenza

• state_version impedisce di lavorare su uno snapshot superato senza accorgersene

• evidence_refs collega le fonti senza copiare tutto nel prompt

• constraints rende visibile il perimetro, ma non sostituisce l'enforcement tecnico

• acceptance_criteria dice quando il lavoro è completo

• idempotency_key permette di riconoscere un trasferimento ripetuto

Il payload può includere una sintesi leggibile. La sintesi non sostituisce i campi che determinano routing, autorità e chiusura.

Il contratto degli input di un workflow AI aiuta a definire presenza, provenienza e rifiuto dei dati. Nell'handoff aggiungi la semantica della transizione: chi consegna, chi riceve e quale stato viene ceduto.

Scegli la destinazione da regole ed evidenze

Passa al miglior agente non è una regola di routing. È un invito a improvvisare.

Descrivi ogni destinazione con:

• task ammessi e task esclusi

• dati che può leggere

• azioni che può proporre o eseguire

• livello di conseguenza accettato

• orari, disponibilità o dipendenze

• condizioni che rendono il target non disponibile

• fallback o percorso umano

Il modello può classificare un caso ambiguo. Il codice dovrebbe applicare i vincoli deterministici: target abilitato, tenant corretto, scope ammesso, versione compatibile e assenza di blocchi.

Un routing robusto separa tre decisioni:

1. eleggibilità: quali destinazioni sono ammesse per quel caso?

2. preferenza: quale agente è più adatto fra quelli ammessi?

3. autorizzazione: quali azioni potrà compiere dopo l'accettazione?

La preferenza non può allargare l'eleggibilità. Un agente molto capace ma non autorizzato resta fuori dal set.

Filtra il contesto prima del passaggio

La documentazione degli handoff di OpenAI mostra che il ricevente può vedere la storia precedente e che un filtro può modificarla. Questo è un dettaglio architetturale, non una scelta editoriale minore.

Passare tutta la storia può introdurre:

• PII non necessaria al task successivo

• istruzioni obsolete o rivolte al primo agente

• risultati di tool che il ricevente non deve conoscere

• ipotesi scambiate per fatti

• contenuto avverso recuperato da fonti esterne

• un costo crescente a ogni trasferimento

Costruisci il contesto del ricevente da componenti espliciti:

Non lasciare che il primo agente decida da solo quali dati sensibili inoltrare. Applica una policy locale sul tipo di task, sul destinatario e sul tenant.

Fai accettare o rifiutare il lavoro

Un trasferimento non è completo quando il mittente emette l'handoff. È completo quando il ricevente accetta una versione precisa dello stato.

Il ricevente controlla almeno:

• schema e campi obbligatori

• target e versione corretti

• riferimenti accessibili

• task nel proprio perimetro

• dati sufficienti per iniziare

• stato non scaduto o già sostituito

• idempotency key non già chiusa

• azioni richieste compatibili con la propria autorità

Gli esiti minimi sono:

accepted    il lavoro entra nella coda del ricevente
rejected    il contratto è invalido o fuori scope
needs_input manca una prova identificabile
stale       esiste una versione più recente dello stato
duplicate   lo stesso handoff è già stato accettato o chiuso

Rejected non deve diventare una nuova conversazione fra agenti senza fine. Il rifiuto contiene un codice, i campi mancanti e il prossimo owner. Se il problema non è riparabile automaticamente, il flusso segue l'escalation umana di un workflow AI.

L'accettazione produce una ricevuta:

handoff_id: ho_20260903_00421
accepted_by: contract_review.v2
accepted_state_version: 7
accepted_at: 2026-09-03T10:41:09+02:00
authority_profile: review_note_only@3
queue_ref: qr_771

Questa ricevuta separa il modello ha chiamato il tool di handoff da il sistema ha preso in carico il lavoro.

Non trasferire autorità per implicazione

AutoGen ricorda che gli agenti possono produrre effetti esterni. Perciò il passaggio deve legare il nuovo owner a un profilo di autorità applicato dal sistema.

Il mittente può dichiarare allowed_actions, ma non dovrebbe poterle concedere. L'enforcement verifica identità del ricevente, risorsa, operazione, stato e policy corrente.

Esempio: l'agente di intake può indirizzare una pratica a contract_review. Questo non autorizza il secondo agente a inviare una mail. Può creare una nota di revisione perché quel permesso esiste nel suo profilo, non perché il primo agente lo ha scritto nel payload.

Se un campo generato dal modello determina l'autorizzazione, validalo prima di qualsiasi side effect. La documentazione OpenAI segnala che i controlli sull'input dell'handoff e quelli sui tool non sono la stessa superficie. Progetta il gate nel punto in cui l'applicazione conosce argomenti, identità e risorsa concreta.

NIST AI RMF chiede ruoli, responsabilità e linee di comunicazione chiare. In pratica, ogni nodo del grafo dovrebbe avere:

• owner organizzativo

• owner tecnico

• task ammessi

• azioni con effetto

• escalation

• criteri di sospensione

• evidenza richiesta per la chiusura

Rendi retry e concorrenza innocui

Un timeout può arrivare dopo l'accettazione ma prima che il mittente riceva la conferma. Se il sistema ripete l'handoff senza una chiave stabile, il ricevente apre due lavori.

La chiave idempotente dovrebbe derivare da identità del caso, versione dello stato e azione richiesta. Non usare un timestamp casuale se vuoi riconoscere lo stesso tentativo logico.

Il ricevente salva in modo atomico:

1. handoff accettato

2. versione dello stato

3. coda o work item creato

4. ricevuta restituita

Se trova la stessa chiave, restituisce la ricevuta esistente. Se trova lo stesso caso con una versione più recente, marca il vecchio passaggio stale.

Definisci anche il controllo di concorrenza. Due agenti potrebbero provare a prendere lo stesso caso. Il sistema deve avere un solo owner attivo oppure un modello esplicito di collaborazione. Chi risponde per primo non è una policy.

Osserva il passaggio come un evento

Un trace utile mostra:

routing_requested
destination_eligible
handoff_emitted
payload_validated
handoff_accepted
work_started
work_completed
result_returned

Per ogni fase conserva timestamp, agente, versione, esito e reason code. Non registrare il payload completo quando contiene dati protetti: usa riferimenti e hash dove bastano.

Misura:

• percentuale accettata al primo passaggio

• rifiuti per schema, scope, dati mancanti e stato stale

• tempo fra emissione e accettazione

• duplicati intercettati

• handoff che tornano al mittente

• trasferimenti per singolo caso

• side effect prima dell'accettazione

• casi chiusi senza prova finale

L'audit trail di un workflow AI aiuta a collegare identità, azioni ed evidenze. L'handoff aggiunge due momenti che non vanno fusi: consegna e presa in carico.

Testa il grafo, non solo i singoli agenti

Un agente può superare i propri eval e fallire nel passaggio. Crea test su:

• destinazione corretta e destinazioni escluse

• payload minimo valido

• campo obbligatorio mancante

• contesto con PII da rimuovere

• stato aggiornato mentre il passaggio è in corso

• target temporaneamente disabilitato

• retry dopo timeout

• doppia accettazione concorrente

• autorizzazione richiesta ma non posseduta

• ciclo A → B → A

• catena oltre il numero massimo di passaggi

• ricevente che completa senza evidenza

Gli oracoli devono controllare il trace e lo stato, non soltanto la risposta finale. Un testo corretto dopo due side effect non autorizzati è un fallimento.

Imposta limiti di profondità e condizioni di stop. Se tre agenti si rimbalzano lo stesso caso, il quarto passaggio non porterà magicamente chiarezza: serve un owner umano o una regola deterministica.

Esempio fittizio: verifica di un contratto incompleto

Un agente di intake estrae i campi da una bozza contrattuale sintetica. Mancano effective_date e owner. Non deve inventarli.

Il routing considera due target:

• contract_review: può leggere la bozza e creare note

• vendor_contact: può preparare una richiesta ma non inviarla

La policy sceglie contract_review perché la prima azione è verificare quali campi siano davvero obbligatori. Il payload include hash della bozza, versione delle regole e due campi candidati.

Il ricevente nota che la regola required_fields@4 è stata sostituita dalla versione 5. Rifiuta con stale_rule_ref. Il mittente ricostruisce il payload sulla versione 5 e ripete con la stessa azione ma una nuova state version.

Il secondo passaggio viene accettato. L'agente produce una nota con tre campi mancanti e riferimenti alla regola. Non aggiorna il contratto e non contatta nessuno. La ricevuta chiude l'handoff; un owner umano decide l'azione successiva.

Il valore non è aver aggiunto un secondo modello. È aver reso visibili versione, rifiuto, autorità e prova.

Think, Build, Enable applicato agli handoff

Think: definisci quando cambia owner, quali destinazioni sono eleggibili, che cosa non deve attraversare il confine e chi decide in caso di rifiuto.

Build: usa payload strutturati, riferimenti versionati, filtri del contesto, accettazione atomica, chiavi idempotenti e enforcement locale dei permessi.

Enable: assegna owner al grafo, osserva rifiuti e cicli, prova retry e concorrenza e conserva l'escalation umana.

Porta grafo, agenti e failure mode a MAIKER HUB per progettare automazioni e agent AI con n8n. Un buon handoff non si misura dalla naturalezza del passaggio. Si misura da quanto è difficile perdere stato, autorità e responsabilità mentre il lavoro cambia mano.