Un’architettura Claude non è «il modello più un prompt». È un percorso completo: che cosa entra, come viene trasformato, che cosa esce e — la parte che quasi sempre manca nei disegni di prima iterazione — come il sistema scopre di aver sbagliato e reagisce.

L’unità di base è l’LLM aumentato

Il punto di partenza canonico è uno solo: «The basic building block of agentic systems is an LLM enhanced with augmentations such as retrieval, tools, and memory.» Tre superfici, tre decisioni di ingresso da mettere sul disegno: che cosa viene recuperato e da dove, quali azioni sono disponibili, che cosa sopravvive fra un turno e l’altro. Sul lato ingresso vale il principio del context engineering, definito come «the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference», con l’obiettivo dichiarato di trovare «the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome».

L’uscita merita la stessa attenzione dell’ingresso: se il consumatore a valle è un sistema e non una persona, l’architettura deve produrre un formato che quel sistema sa leggere, e il punto in cui si esegue il parsing è un punto di rottura da progettare, non da scoprire in produzione.

Workflow o agente: dove passa la riga

La distinzione autoritativa è netta: «Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.» I workflow comprano prevedibilità e coerenza su compiti ben definiti; «agents are the better option when flexibility and model-driven decision-making are needed at scale», e in particolare servono «for open-ended problems where it’s difficult or impossible to predict the required number of steps, and where you can’t hardcode a fixed path».

La regola di ingresso resta però la più economica da difendere: «Try the task as a single agent call first. If that meets your quality bar, you’re done.»

Cinque schemi, e il momento in cui non usarli

I cinque schemi di workflow documentati sono il prompt chaining (passi sequenziali in cui ogni chiamata lavora sull’uscita della precedente), il routing (classificazione dell’input e instradamento verso compiti specializzati), la parallelizzazione — «LLMs can sometimes work simultaneously on a task and have their outputs aggregated programmatically» —, l’orchestrator-workers (un LLM centrale scompone, delega e sintetizza) e l’evaluator-optimizer (un modello genera, un altro valuta e rimanda indietro il giudizio).

La parte che un architetto deve saper recitare a memoria è il rovescio, perché è lì che si perdono soldi:

sequenziale     -> evitalo se una sola chiamata copre già l'intero compito
parallelo       -> evitalo se gli agenti devono costruire l'uno sul lavoro dell'altro
evaluator-opt.  -> evitalo se la qualità al primo tentativo basta già
                   e nelle applicazioni che richiedono risposta immediata

Il ciclo di feedback è parte del disegno, non un’aggiunta

Un agente non parte da solo: «Agents begin their work with either a command from, or interactive discussion with, the human user.» Poi il ciclo si regge su una condizione precisa: «During execution, it’s crucial for the agents to gain ‘ground truth’ from the environment at each step (such as tool call results or code execution) to assess its progress.» Se l’ambiente non restituisce un segnale verificabile — un test che passa, una query che torna, un file che esiste — l’agente non ha modo di correggersi e il ciclo diventa una ripetizione costosa.

Da qui i due controlli che appartengono all’architettura, non all’implementazione. Il primo è umano: «Agents can then pause for human feedback at checkpoints or when encountering blockers.» Il secondo è meccanico: «The task often terminates upon completion, but it’s also common to include stopping conditions (such as a maximum number of iterations) to maintain control.» L’Agent SDK espone entrambi i limiti come parametri, e distingue nel risultato il completamento dall’interruzione:

max_turns / maxTurns             -> esito error_max_turns
max_budget_usd / maxBudgetUsd    -> esito error_max_budget_usd

La documentazione è esplicita sul default da adottare: «Setting a budget is a good default for production agents.» Sul lato Managed Agents il ciclo di revisione è a sua volta limitato: il campo max_iterations di un outcome ha default 3 e massimo 20, e la valutazione può chiudersi come soddisfatta, come bisognosa di revisione o come esaurita per iterazioni.

Che cosa si difende in riunione

Le tre raccomandazioni finali di «Building effective agents» sono la sintesi difendibile di questo dominio: mantenere semplice il disegno dell’agente, privilegiare la trasparenza mostrando esplicitamente i passi di pianificazione, e curare l’interfaccia fra agente e strumenti con documentazione e test accurati. Tradotte per chi finanzia: ogni gradino di autonomia in più va pagato in latenza, costo e superficie di errore, e va quindi chiesto solo quando una misura dice che il gradino precedente non basta.