AI & MCP
Orchestrare agenti multi-step: piano, checkpoint e budget per passo
Un agente multi-step regge se il piano è un file, ogni passo ha un gate e il costo è limitato prima di partire. Ecco il ciclo e i punti in cui si rompe.
In sintesi
- Il piano vive su disco con stato per passo, così un'interruzione non riparte da zero.
- Ogni passo ha un gate eseguibile e un tetto di chiamate, altrimenti il ciclo non termina.
- MCP non offre transazioni: gli strumenti che scrivono hanno bisogno di una chiave di idempotenza nel tool.
Un agente multi-step si orchestra con un piano scritto, un checkpoint su disco e un budget per passo, non con un prompt più lungo. Il modello sceglie l'azione dentro un passo; la struttura del ciclo resta al tuo codice.
Il ciclo minimo
Quattro stati bastano: plan legge il piano, step esegue una sola azione, gate controlla il risultato con un comando, checkpoint scrive lo stato su disco. Se il processo muore al passo 7, il riavvio legge il checkpoint e riparte dal passo 7, non dal primo.
Il piano è un file, non un messaggio
{
"goal": "aggiungere il filtro regione al catalogo",
"budget_calls": 40,
"steps": [
{ "id": 1, "action": "search_components", "gate": "results > 0" },
{ "id": 2, "action": "edit", "files": ["client/src/pages/Components.tsx"], "gate": "npm run build" },
{ "id": 3, "action": "verify", "gate": "npx tsc --noEmit -p client/tsconfig.json" }
]
}Il piano dichiara il numero massimo di chiamate prima di iniziare. Un tetto scritto è l'unica difesa contro il ciclo che continua a cercare di aggiustare lo stesso errore: quando le chiamate finiscono, l'agente si ferma e ti lascia il diff.
Un passo, una chiamata
curl -s https://ui.eneawork.it/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_components","arguments":{"query":"table filter","limit":5}}}'La risposta è testo: il server non sa quale passo stai eseguendo e non vede il resto della conversazione. Sta al tuo codice registrare nome del tool, argomenti e durata, perché il modello non lo farà e senza quel registro non puoi spiegare un fallimento.
Dove si rompe
| Guasto | Come si vede | Difesa |
|---|---|---|
| Passo eseguito due volte | due file scritti con lo stesso contenuto | chiave di idempotenza nell'argomento del tool |
| Piano che deriva | il passo 7 parla di un altro file | piano congelato e diff tra piano e azione |
| Contesto che cresce | costo per passo in salita | riassunto ogni cinque passi, output vecchi scartati |
| Limite di frequenza | errore 429 a metà ciclo | backoff con tetto e contatore nel checkpoint |
| Tool lento | un passo dura minuti | timeout per chiamata e passo marcato come fallito |
Il verificatore non è un secondo parere
Un secondo agente che dice «mi sembra a posto» non verifica nulla. Il verificatore utile esegue un comando e confronta un'uscita: build, tipi, test, diff atteso. Se il controllo è un'opinione, stai pagando due modelli per lo stesso errore.
La limitazione
MCP non ha transazioni. Una chiamata che scrive non si annulla, e un retry dopo un timeout può duplicare l'effetto: l'idempotenza deve stare nel tool, non nel client. Il server EneUI è in sola lettura, quindi il pattern qui descritto è sicuro per la scoperta e la lettura, non per la scrittura su un servizio esterno.
Dove continuare
La scrittura del prompt di sistema è in prompt per agenti, la struttura di una skill in anatomia di una agent skill, e la misura del costo per attività in valutare un modello per il codice. Per il lato server leggi costruire un server MCP. Il catalogo da cui pesca l'esempio è in 111.985 componenti e 1.556 blocchi; un record MIT adatto a una UI di agente è agent dock di dqnamo.
Domande frequenti
Quanti passi deve avere al massimo un agente?
Non c'è un numero giusto, c'è un tetto esplicito. Il piano deve dichiarare un massimo di chiamate e fermarsi lì: senza tetto il ciclo continua a ritentare lo stesso errore e il costo cresce senza un risultato.
Serve un database per i checkpoint?
No, un file JSON riscritto in modo atomico basta per un agente singolo. Un database serve quando due processi lavorano sullo stesso piano, perché allora il checkpoint diventa un lock.
Come gestisco il limite di frequenza del server MCP?
Con un backoff e un contatore nel checkpoint. Il piano anonimo di EneUI regge 60 richieste al minuto, quello free 120, pro 600 e team 1.200, valori letti in backend/entitlements.js il 1 novembre 2026.
Il verificatore deve essere un altro modello?
Non necessariamente. Deve eseguire un comando che può fallire: build, tipi, test o confronto con un diff atteso. Un secondo modello che legge e approva aggiunge costo e nessuna prova.
Posso far scrivere l'agente tramite MCP?
Solo se il tool che scrive è idempotente, perché MCP non offre transazioni e un retry può duplicare l'effetto. Il server EneUI è in sola lettura, quindi lì il rischio non esiste, ma un tool di scrittura va progettato per resistere al doppio invio.