Regola il contesto degli strumenti di un agente

Questa guida copre il lavoro pratico attorno alla superficie degli strumenti a due livelli: vedere che cosa invia un’esecuzione, cambiarlo e diagnosticare un agente che ha puntato allo strumento sbagliato. Per capire perché funziona così, leggi Contesto degli strumenti e cache dei prompt.

Guarda che cosa invia davvero un’esecuzione

Apri una conversazione e tocca l’indicatore di utilizzo del contesto nell’intestazione della conversazione. Ricostruisce esattamente la superficie che manderebbe l’invio successivo, senza eseguire nulla. Vedi altro (o il comando /context) apre l’esploratore completo del contesto, dove puoi ispezionare ogni strumento.

Qui contano due segmenti:

• Definizioni degli strumenti e MCP e strumenti dinamici — l’insieme residente, con il costo reale in token di ogni strumento.
• Strumenti caricati su richiesta — l’indice differito. Ogni voce paga solo il proprio nome, perché un nome è tutto ciò che la richiesta porta con sé; aprirne una mostra comunque la descrizione e lo schema completi, così puoi vedere quanto costerebbe se l’esecuzione la caricasse.

Se il segmento dei differiti è vuoto, il differimento è disattivato su questo server. Controlla --tool-deferral nella CLI di cc_server.

Cambia quali strumenti vengono caricati in anticipo

L’insieme residente è una politica, non una configurazione: vive in ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) e vale per ogni esecuzione:

• residentBuiltins — il vocabolario di file e shell.
• residentDiscovery — search_tools e list_my_tools. Non rimuoverli: sono il modo in cui un agente raggiunge tutto il resto.
• residentMcpTools — la manciata di strumenti di Control Center il cui schema vale il costo a ogni richiesta.
• Un blocco per modalità, per gli strumenti che una determinata modalità usa quasi a ogni turno.

Due regole quando lo modifichi:

Aggiungi uno strumento solo se lo usa la maggior parte delle esecuzioni. Ogni nome costa il proprio schema a ogni richiesta di ogni esecuzione, per sempre. Uno strumento importante quando serve ma raro nel complesso appartiene alla metà differita: l’agente lo troverà comunque.

Usa il nome reale dello strumento. Un nome residente che non corrisponde ad alcuno strumento è inerte: nessun errore, nessun avviso, lo strumento viene semplicemente differito. test/tooling/resident_tool_names_test.dart se ne accorge e tiene anche ogni modalità sotto i 40 strumenti residenti, che è poi il punto dell’esercizio: oltre quella soglia, la selezione degli strumenti peggiora in modo misurabile.

I verbi richiesti e fissati di una modalità vengono aggiunti automaticamente, quindi non devi mai elencare il verbo di output della modalità stessa.

Diagnostica una scelta di strumento sbagliata

Quando un agente ha usato lo strumento sbagliato o ha sostenuto di non poter fare qualcosa, stabilisci quale di queste tre cose è successa.

1. Ha guardato?

Ogni esecuzione registra gli strumenti differiti che ha caricato e che cosa li ha innescati: una chiamata diretta per nome o una query di search_tools. Apri il flusso di eventi dell’esecuzione (Impostazioni → Spazio di lavoro → Agenti → l’agente → Log → Visualizza) e cerca [harness] loaded N deferred tool(s).

• Nessuna voce registrata e l’agente ha detto che la capacità mancava — non ha mai guardato. È un problema di prompt, non di recupero: l’indice differito è nel suo prompt di sistema con l’istruzione di non dichiarare mancante una capacità finché una ricerca non è tornata vuota.
• Una ricerca registrata, ma nulla di caricato — un vero recupero mancato. Passa al punto 2.
• Strumenti caricati, ma usato quello sbagliato — gli strumenti che ha trovato si somigliano troppo. Passa al punto 3.

2. Correggi un recupero mancato

search_tools cerca per nomi, descrizioni e nomi degli argomenti. Un mancato recupero significa quasi sempre che la descrizione non contiene le parole usate dall’agente.

Aggiungile. Le descrizioni sono l’indice di recupero, quindi allungale invece di accorciarle — scrivi il vocabolario che un operatore digiterebbe davvero («assign», «hand off», «give to»), non solo il sostantivo interno. Accorciare una descrizione per risparmiare token ti costa sia il successo della ricerca sia la precisione nella selezione, e rispetto allo schema non fa risparmiare quasi nulla.

Se lo strumento giusto esiste ma è classificato in basso, è a questo che serve l’argomento limit; la descrizione dello strumento stesso dice all’agente di ampliare una ricerca che sembra vicina ma non trova nulla.

3. Correggi gli strumenti che si somigliano

Se due strumenti hanno descrizioni che suonerebbero identiche a chi non conosce già la differenza, il modello sta tirando a indovinare. Uniscili in un unico strumento con un argomento discriminante.

ticket_relation e ticket_pr_link seguono questo schema: ciascuno gestisce collegamento e scollegamento tramite un argomento discriminante. Una scelta fatta dentro una chiamata, con il contesto completo della richiesta, è più affidabile di una scelta fatta tra due descrizioni che si somigliano.

Tieni separati gli strumenti quando richiedono approvazioni diverse, audit diversi o rendering diversi: sono motivi per cui un’unione ti costerebbe qualcosa di reale.

Verifica che la cache dei prompt funzioni

Il tasso di successo della cache compare in Osservabilità → Panoramica come Tasso di cache. Una conversazione lunga e in salute se ne sta su valori alti; se resta stabilmente basso, qualcosa riscrive il prefisso a ogni turno.

Cause comuni, in ordine di probabilità:

• Qualunque elemento non deterministico all’inizio del prompt. Bastano un timestamp, un id di richiesta o un insieme iterato in ordine variabile.
• Un cambio di modello o di sforzo di ragionamento a conversazione avviata. Entrambi cambiano il prefisso. Con i subagent è particolarmente facile sbagliare: eseguire i figli a uno sforzo di ragionamento più basso per risparmiare può costare, in condivisione di cache persa, più di quanto faccia risparmiare.
• Compattazione frequente. La compattazione riscrive la cronologia per sua stessa natura, quindi il suo costo è reale; la soluzione è compattare di rado e in profondità, non spesso e in superficie.

Disattivare il differimento con --tool-deferral=off è un A/B valido per isolare se un cambiamento di comportamento deriva dalla superficie a due livelli. Riproduce esattamente la richiesta precedente al differimento, quindi se il comportamento persiste con il differimento disattivato, la superficie non è la causa.