# 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.

> Pagina: https://ui.eneawork.it/blog/agenti-multi-step-orchestrazione
> Markdown: https://ui.eneawork.it/blog/agenti-multi-step-orchestrazione.md

*2026-11-01*

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 server EneUI espone 9 strumenti MCP in sola lettura, contati in backend/mcp.js il 1 novembre 2026, e tools/list ha risposto con 3.655 byte in 138 ms misurati da ui.eneawork.it/mcp lo stesso giorno. I limiti di frequenza per piano sono in backend/entitlements.js, letti il 1 novembre 2026: 60 richieste al minuto anonime, 120 sul piano free, 600 su pro e 1.200 su team, business e premium. Il listino DeepSeek letto il 1 novembre 2026 dichiara un limite di concorrenza di 2.500 richieste per deepseek-flash e 500 per deepseek-v4-pro. Il catalogo dietro conta 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, letti da /api/stats.

## 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

## 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.

## FAQ

### 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.