AskUserQuestion). Entrambi attivano il tuo callback canUseTool, che mette in pausa l’esecuzione fino a quando non restituisci una risposta. Questo è diverso dai normali turni di conversazione in cui Claude finisce e attende il tuo prossimo messaggio.
Per le domande di chiarimento, Claude genera le domande e le opzioni. Il tuo ruolo è presentarle agli utenti e restituire le loro selezioni. Non puoi aggiungere le tue domande a questo flusso; se hai bisogno di chiedere qualcosa agli utenti tu stesso, fallo separatamente nella logica dell’applicazione.
Il callback può rimanere in sospeso indefinitamente. L’esecuzione rimane in pausa fino a quando il callback non restituisce, e l’SDK annulla l’attesa solo quando la query stessa viene annullata. Se un utente potrebbe impiegare più tempo per rispondere di quanto il tuo processo possa ragionevolmente rimanere in esecuzione, restituisci la decisione defer hook, che consente al processo di uscire e riprendere in seguito dalla sessione persistente.
Questa guida ti mostra come rilevare ogni tipo di richiesta e rispondere in modo appropriato.
Rilevare quando Claude ha bisogno di input
Passa un callbackcanUseTool nelle opzioni della query. Il callback si attiva ogni volta che Claude ha bisogno di input dell’utente, ricevendo il nome dello strumento e l’input come argomenti:
- Lo strumento ha bisogno di approvazione: Claude vuole utilizzare uno strumento che non è approvato automaticamente dalle regole di autorizzazione o dalle modalità. Controlla
tool_nameper lo strumento (ad es."Bash","Write"). - Claude pone una domanda: Claude chiama lo strumento
AskUserQuestion. Controlla setool_name == "AskUserQuestion"per gestirlo diversamente. Se specifichi un arraytools, includiAskUserQuestionaffinché funzioni. Vedi Gestire domande di chiarimento per i dettagli.
Per consentire o negare automaticamente gli strumenti senza chiedere agli utenti, utilizza invece gli hook. Gli hook vengono eseguiti prima di
canUseTool e possono consentire, negare o modificare le richieste in base alla tua logica. Puoi anche utilizzare l’hook PermissionRequest per inviare notifiche esterne (Slack, email, push) quando Claude è in attesa di approvazione.Gestire le richieste di approvazione dello strumento
Una volta passato un callbackcanUseTool nelle opzioni della query, si attiva quando Claude vuole utilizzare uno strumento che non è approvato automaticamente. Il tuo callback riceve tre argomenti:
| Argomento | Descrizione |
|---|---|
toolName | Il nome dello strumento che Claude vuole utilizzare (ad es. "Bash", "Write", "Edit") |
input | I parametri che Claude sta passando allo strumento. Il contenuto varia a seconda dello strumento. |
options (TS) / context (Python) | Contesto aggiuntivo incluso suggestions opzionale (voci PermissionUpdate proposte per evitare di ripetere le domande) e un segnale di annullamento. In TypeScript, signal è un AbortSignal; in Python, il campo signal è riservato per uso futuro. Vedi ToolPermissionContext per Python. |
input contiene parametri specifici dello strumento. Esempi comuni:
| Strumento | Campi di input |
|---|---|
Bash | command, description, timeout |
Write | file_path, content |
Edit | file_path, old_string, new_string |
Read | file_path, offset, limit |
In Python,
can_use_tool richiede la modalità streaming e un hook PreToolUse che restituisce {"continue_": True} per mantenere il flusso aperto. Senza questo hook, il flusso si chiude prima che il callback di autorizzazione possa essere invocato.y viene trattato come un rifiuto. In pratica, potresti creare un’interfaccia utente più ricca che consenta agli utenti di modificare la richiesta, fornire feedback o reindirizzare completamente Claude. Vedi Rispondere alle richieste dello strumento per tutti i modi in cui puoi rispondere.
Rispondere alle richieste dello strumento
Il tuo callback restituisce uno di due tipi di risposta:| Risposta | Python | TypeScript |
|---|---|---|
| Allow | PermissionResultAllow(updated_input=...) | { behavior: "allow", updatedInput } |
| Deny | PermissionResultDeny(message=...) | { behavior: "deny", message } |
- Approva: consenti l’esecuzione dello strumento come richiesto da Claude
- Approva con modifiche: modifica l’input prima dell’esecuzione (ad es. sanitizza i percorsi, aggiungi vincoli)
- Approva e ricorda: ripeti una regola di autorizzazione suggerita in modo che le chiamate corrispondenti saltino il prompt la prossima volta
- Rifiuta: blocca lo strumento e spiega a Claude il motivo
- Suggerisci alternativa: blocca ma guida Claude verso ciò che l’utente vuole invece
- Reindirizza completamente: utilizza input streaming per inviare a Claude un’istruzione completamente nuova
- Approva
- Approva con modifiche
- Approva e ricorda
- Rifiuta
- Suggerisci alternativa
- Reindirizza completamente
L’utente approva l’azione così com’è. Passa l’
input dal tuo callback invariato e lo strumento viene eseguito esattamente come richiesto da Claude.Gestire domande di chiarimento
Quando Claude ha bisogno di più direzione su un’attività con più approcci validi, chiama lo strumentoAskUserQuestion. Questo attiva il tuo callback canUseTool con toolName impostato su AskUserQuestion. L’input contiene le domande di Claude come opzioni a scelta multipla, che visualizzi all’utente e restituisci le sue selezioni.
I seguenti passaggi mostrano come gestire le domande di chiarimento:
Passa un callback canUseTool
Passa un callback
canUseTool nelle opzioni della query. Per impostazione predefinita, AskUserQuestion è disponibile. Se specifichi un array tools per limitare le capacità di Claude (ad esempio, un agente di sola lettura con solo Read, Glob e Grep), includi AskUserQuestion in quell’array. Altrimenti, Claude non sarà in grado di porre domande di chiarimento:Rileva AskUserQuestion
Nel tuo callback, controlla se
toolName è uguale a AskUserQuestion per gestirlo diversamente da altri strumenti:Analizza l'input della domanda
L’input contiene le domande di Claude in un array Vedi Formato della domanda per le descrizioni complete dei campi.
questions. Ogni domanda ha una question (il testo da visualizzare), options (le scelte) e multiSelect (se sono consentite più selezioni):Raccogli risposte dall'utente
Presenta le domande all’utente e raccogli le sue selezioni. Come lo fai dipende dalla tua applicazione: un prompt del terminale, un modulo web, una finestra di dialogo mobile, ecc.
Restituisci le risposte a Claude
Costruisci l’oggetto
Per le domande a selezione multipla, passa un array di etichette o uniscile con
answers come un record in cui ogni chiave è il testo question e ogni valore è l’label dell’opzione selezionata:| Dall’oggetto domanda | Usa come |
|---|---|
Campo question (ad es. "How should I format the output?") | Chiave |
Campo label dell’opzione selezionata (ad es. "Summary") | Valore |
", ". Se supporti input di testo libero, utilizza il testo personalizzato dell’utente come valore.Formato della domanda
L’input contiene le domande generate da Claude in un arrayquestions. Ogni domanda ha questi campi:
| Campo | Descrizione |
|---|---|
question | Il testo completo della domanda da visualizzare |
header | Etichetta breve per la domanda (max 12 caratteri) |
options | Array di 2-4 scelte, ognuna con label e description. TypeScript: opzionalmente preview (vedi sotto) |
multiSelect | Se true, gli utenti possono selezionare più opzioni |
Anteprime delle opzioni (TypeScript)
toolConfig.askUserQuestion.previewFormat aggiunge un campo preview a ogni opzione in modo che la tua app possa mostrare un mockup visivo insieme all’etichetta. Senza questa impostazione, Claude non genera anteprime e il campo è assente.
previewFormat | preview contiene |
|---|---|
| non impostato (predefinito) | Il campo è assente. Claude non genera anteprime. |
"markdown" | ASCII art e blocchi di codice recintati |
"html" | Un frammento <div> stilizzato (l’SDK rifiuta <script>, <style> e <!DOCTYPE> prima che il tuo callback venga eseguito) |
preview sulle opzioni in cui un confronto visivo aiuta (scelte di layout, schemi di colori) e lo omette dove non lo farebbe (conferme sì/no, scelte solo testo). Controlla undefined prima di eseguire il rendering.
Formato della risposta
Restituisci un oggettoanswers che mappa il campo question di ogni domanda all’label dell’opzione selezionata:
| Campo | Descrizione |
|---|---|
questions | Passa l’array di domande originale (obbligatorio per l’elaborazione dello strumento) |
answers | Oggetto in cui le chiavi sono il testo della domanda e i valori sono le etichette selezionate |
response | Risposta facoltativa in testo libero che l’utente ha digitato invece di rispondere alle domande strutturate |
", ". Per input di testo libero per domanda, come un’opzione “Other”, inserisci il testo dell’utente in answers[question] come mostrato in Supporta input di testo libero. Imposta response solo quando la tua interfaccia utente consente all’utente di chiudere la scheda della domanda e digitare una risposta generale che non sia una risposta a nessuna domanda specifica. Quando response è impostato, Claude riceve “L’utente ha risposto: …” invece dell’elenco di risposte per domanda.
Supporta input di testo libero
Le opzioni predefinite di Claude non copriranno sempre ciò che gli utenti vogliono. Per consentire agli utenti di digitare la propria risposta:- Visualizza una scelta “Other” aggiuntiva dopo le opzioni di Claude che accetta input di testo
- Utilizza il testo personalizzato dell’utente come valore della risposta (non la parola “Other”)
Esempio completo
Claude pone domande di chiarimento quando ha bisogno di input dell’utente per procedere. Ad esempio, quando gli viene chiesto di aiutare a decidere su uno stack tecnologico per un’app mobile, Claude potrebbe chiedere informazioni su cross-platform vs nativo, preferenze di backend o piattaforme di destinazione. Queste domande aiutano Claude a prendere decisioni che corrispondono alle preferenze dell’utente piuttosto che indovinare. Questo esempio gestisce quelle domande in un’applicazione terminale. Ecco cosa accade ad ogni passaggio:- Instrada la richiesta: Il callback
canUseToolcontrolla se il nome dello strumento è"AskUserQuestion"e instrada a un gestore dedicato - Visualizza le domande: Il gestore scorre l’array
questionse stampa ogni domanda con opzioni numerate - Raccogli input: L’utente può inserire un numero per selezionare un’opzione, o digitare testo libero direttamente (ad es. “jquery”, “i don’t know”)
- Mappa le risposte: Il codice controlla se l’input è numerico (utilizza l’etichetta dell’opzione) o testo libero (utilizza il testo direttamente)
- Restituisci a Claude: La risposta include sia l’array
questionsoriginale che la mappaturaanswers
Limitazioni
- Subagenti:
AskUserQuestionnon è attualmente disponibile nei subagenti generati tramite lo strumento Agent - Limiti delle domande: ogni chiamata
AskUserQuestionsupporta 1-4 domande con 2-4 opzioni ciascuna
Altri modi per ottenere input dall’utente
Il callbackcanUseTool e lo strumento AskUserQuestion coprono la maggior parte degli scenari di approvazione e chiarimento, ma l’SDK offre altri modi per ottenere input dagli utenti:
Input streaming
Utilizza input streaming quando hai bisogno di:- Interrompere l’agente a metà attività: invia un segnale di annullamento o cambia direzione mentre Claude sta lavorando
- Fornire contesto aggiuntivo: aggiungi informazioni di cui Claude ha bisogno senza aspettare che le chieda
- Costruire interfacce di chat: consenti agli utenti di inviare messaggi di follow-up durante operazioni di lunga durata
Strumenti personalizzati
Utilizza strumenti personalizzati quando hai bisogno di:- Raccogliere input strutturato: costruisci moduli, procedure guidate o flussi di lavoro multi-step che vanno oltre il formato a scelta multipla di
AskUserQuestion - Integrare sistemi di approvazione esterni: connettiti a piattaforme di ticketing, flusso di lavoro o approvazione esistenti
- Implementare interazioni specifiche del dominio: crea strumenti personalizzati per le esigenze della tua applicazione, come interfacce di revisione del codice o elenchi di controllo di distribuzione
canUseTool integrato.
Risorse correlate
- Configura autorizzazioni: configura modalità e regole di autorizzazione
- Controlla l’esecuzione con hook: esegui codice personalizzato nei punti chiave del ciclo di vita dell’agente
- Riferimento SDK TypeScript: documentazione API completa di canUseTool