Uno degli aspetti più complessi nella creazione di un sistema agente è la costruzione del suo spazio d'azione.
Claude agisce tramite Tool Calling, ma esistono diversi modi per costruire strumenti nell'API di Claude utilizzando primitive come bash, skills e, recentemente, l'esecuzione di codice (leggi di più sul tool calling programmatico nell'API di Claude nel nuovo articolo di @RLanceMartin).
Date tutte queste opzioni, come si progettano gli strumenti del tuo agente? Ti serve un solo strumento come l'esecuzione di codice o bash? E se avessi 50 strumenti, uno per ogni caso d'uso che il tuo agente potrebbe incontrare?
Per mettermi nei panni del modello, mi piace immaginare di dover risolvere un difficile problema di matematica. Quali strumenti vorresti per risolverlo? Dipenderebbe dalle tue stesse capacità!
La carta sarebbe il minimo indispensabile, ma saresti limitato dai calcoli manuali. Una calcolatrice sarebbe meglio, ma dovresti saper usare le opzioni più avanzate. L'opzione più veloce e potente sarebbe un computer, ma dovresti saperlo usare per scrivere ed eseguire codice.
Questo è un quadro utile per progettare il tuo agente. Vuoi dargli strumenti modellati sulle sue capacità. Ma come fai a sapere quali sono queste capacità? Presti attenzione, leggi i suoi output, sperimenti. Impari a vedere come un agente.
Ecco alcune lezioni che abbiamo imparato prestando attenzione a Claude mentre costruivamo Claude Code.
Migliorare l'Elicitazione e lo strumento AskUserQuestion
Quando abbiamo costruito lo strumento AskUserQuestion, il nostro obiettivo era migliorare la capacità di Claude di fare domande (spesso chiamata elicitazione).
Sebbene Claude potesse semplicemente fare domande in testo semplice, abbiamo notato che rispondere a quelle domande richiedeva un tempo eccessivo. Come potevamo ridurre questo attrito e aumentare la larghezza di banda della comunicazione tra l'utente e Claude?
Tentativo #1 - Modificare l'ExitPlanTool
La prima cosa che abbiamo provato è stata aggiungere un parametro all'ExitPlanTool per avere una serie di domande insieme al piano. Questa era la cosa più semplice da implementare, ma confondeva Claude perché gli chiedevamo contemporaneamente un piano e una serie di domande sul piano. E se le risposte dell'utente fossero state in conflitto con ciò che diceva il piano? Claude avrebbe dovuto chiamare l'ExitPlanTool due volte? Avevamo bisogno di un altro approccio.
(puoi leggere di più sul perché abbiamo creato un ExitPlanTool nel nostro post sul prompt caching
Tentativo #2 - Cambiare il Formato di Output
Successivamente abbiamo provato a modificare le istruzioni di output di Claude per utilizzare un formato markdown leggermente modificato che potesse usare per fare domande. Ad esempio, potevamo chiedergli di produrre un elenco di domande puntate con alternative tra parentesi. Potevamo quindi analizzare e formattare quella domanda come interfaccia utente per l'utente.
Sebbene questa fosse la modifica più generale che potessimo apportare e Claude sembrasse anche abbastanza bravo a produrla, non era garantita. Claude aggiungeva frasi extra, ometteva opzioni o utilizzava un formato completamente diverso.
Tentativo #3 - Lo strumento AskUserQuestion
Alla fine, abbiamo optato per la creazione di uno strumento che Claude potesse chiamare in qualsiasi momento, ma che fosse particolarmente incentivato a usare durante la modalità di pianificazione. Quando lo strumento veniva attivato, mostravamo un modale per visualizzare le domande e bloccare il ciclo dell'agente fino a quando l'utente non rispondeva.
Questo strumento ci ha permesso di richiedere a Claude un output strutturato e ci ha aiutato a garantire che Claude offrisse all'utente più opzioni. Ha anche dato agli utenti il modo di comporre questa funzionalità, ad esempio chiamandola nell'Agent SDK o facendovi riferimento nelle skills.
La cosa più importante è che Claude sembrava apprezzare l'uso di questo strumento e abbiamo scoperto che i suoi output funzionavano bene. Anche lo strumento meglio progettato non funziona se Claude non capisce come chiamarlo.
È questa la forma finale dell'elicitazione in Claude Code? Non ne siamo sicuri. Come vedrai nel prossimo esempio, ciò che funziona per un modello potrebbe non essere il migliore per un altro.
Aggiornare con le Capacità - Tasks e Todos
Quando abbiamo lanciato per la prima volta Claude Code, abbiamo capito che il modello aveva bisogno di un elenco di Todo per rimanere in carreggiata. I Todo potevano essere scritti all'inizio e spuntati man mano che il modello lavorava. Per fare questo, abbiamo dato a Claude lo strumento TodoWrite, che scriveva o aggiornava i Todo e li mostrava all'utente.
Ma anche allora vedevamo spesso Claude dimenticare cosa doveva fare. Per adattarci, abbiamo inserito promemoria di sistema ogni 5 turni che ricordavano a Claude il suo obiettivo.
Ma con il miglioramento dei modelli, non solo non avevano più bisogno di essere ricordati dell'elenco Todo, ma potevano anche trovarlo limitante. Ricevere promemoria dell'elenco Todo faceva pensare a Claude che dovesse attenersi all'elenco invece di modificarlo. Abbiamo anche visto che Opus 4.5 è diventato molto più bravo a usare i subagenti, ma come potevano i subagenti coordinarsi su un elenco Todo condiviso?
Vedendo questo, abbiamo sostituito TodoWrite con lo strumento Task (leggi di più su Tasks qui). Mentre i Todo servivano a mantenere il modello in carreggiata, i Task erano più utili per aiutare gli agenti a comunicare tra loro. I Task potevano includere dipendenze, condividere aggiornamenti tra i subagenti e il modello poteva modificarli ed eliminarli.
Con l'aumento delle capacità del modello, gli strumenti di cui un tempo avevi bisogno potrebbero ora diventare un vincolo. È importante rivedere costantemente le ipotesi precedenti su quali strumenti siano necessari. Questo è anche il motivo per cui è utile attenersi a un piccolo insieme di modelli da supportare che abbiano un profilo di capacità abbastanza simile.
Progettare un'Interfaccia di Ricerca
Un insieme di strumenti particolarmente importante per Claude sono gli strumenti di ricerca che possono essere utilizzati per costruire il proprio contesto.
Quando Claude Code è uscito per la prima volta, abbiamo utilizzato un database vettoriale RAG per trovare il contesto per Claude. Sebbene RAG fosse potente e veloce, richiedeva indicizzazione e configurazione e poteva essere fragile in una serie di ambienti diversi. Ancora più importante, Claude riceveva questo contesto invece di trovarlo da solo.
Ma se Claude poteva cercare sul web, perché non cercare nel tuo codebase? Dando a Claude uno strumento Grep, potevamo lasciargli cercare i file e costruire il contesto da solo.
Questo è uno schema che abbiamo visto: man mano che Claude diventa più intelligente, diventa sempre più bravo a costruire il proprio contesto se gli vengono dati gli strumenti giusti.
Quando abbiamo introdotto le Agent Skills, abbiamo formalizzato l'idea della divulgazione progressiva, che consente agli agenti di scoprire incrementalmente il contesto rilevante attraverso l'esplorazione.
Claude poteva leggere i file delle skill e quei file potevano a loro volta fare riferimento ad altri file che il modello poteva leggere ricorsivamente. In effetti, un uso comune delle skill è aggiungere più capacità di ricerca a Claude, come dargli istruzioni su come usare un'API o interrogare un database.
Nel corso di un anno, Claude è passato dal non essere in grado di costruire il proprio contesto, a essere in grado di eseguire ricerche annidate su diversi livelli di file per trovare il contesto esatto di cui aveva bisogno.
La divulgazione progressiva è ora una tecnica comune che usiamo per aggiungere nuove funzionalità senza aggiungere uno strumento.
Divulgazione Progressiva - L'Agente Guida di Claude Code
Claude Code ha attualmente circa 20 strumenti, e ci chiediamo costantemente se ci servono tutti. La soglia per aggiungere un nuovo strumento è alta, perché questo dà al modello un'opzione in più da considerare.
Ad esempio, abbiamo notato che Claude non sapeva abbastanza su come usare Claude Code. Se gli chiedevi come aggiungere un MCP o cosa faceva un comando slash, non era in grado di rispondere.
Avremmo potuto mettere tutte queste informazioni nel prompt di sistema, ma dato che gli utenti raramente chiedevano queste cose, avrebbe aggiunto contesto inutile e interferito con il compito principale di Claude Code: scrivere codice.
Invece, abbiamo provato una forma di divulgazione progressiva. Abbiamo dato a Claude un link alla sua documentazione che poteva caricare per cercare ulteriori informazioni. Questo funzionava, ma abbiamo scoperto che Claude caricava molti risultati nel contesto per trovare la risposta giusta, quando in realtà tutto ciò di cui avevi bisogno era la risposta.
Così abbiamo costruito il subagente Guida di Claude Code, che Claude è incoraggiato a chiamare quando gli viene chiesto di sé stesso. Il subagente ha istruzioni dettagliate su come cercare bene nella documentazione e cosa restituire.
Sebbene non sia perfetto (Claude può ancora confondersi quando gli chiedi come configurarsi), è molto meglio di prima! Siamo riusciti ad aggiungere cose allo spazio d'azione di Claude senza aggiungere uno strumento.
Un'Arte, non una Scienza
Se speravi in un insieme di regole rigide su come costruire i tuoi strumenti, purtroppo questa non è quella guida. Progettare gli strumenti per i tuoi modelli è tanto un'arte quanto una scienza. Dipende fortemente dal modello che stai usando, dall'obiettivo dell'agente e dall'ambiente in cui opera.
Sperimenta spesso, leggi i tuoi output, prova cose nuove. Vedi come un agente.
