Vai al contenuto principale
Durante il lavoro su un’attività, Claude a volte ha bisogno di verificare con gli utenti. Potrebbe aver bisogno di autorizzazione prima di eliminare file, oppure potrebbe aver bisogno di chiedere quale database utilizzare per un nuovo progetto. La tua applicazione deve presentare queste richieste agli utenti in modo che Claude possa continuare con il loro input. Claude richiede input dell’utente in due situazioni: quando ha bisogno di autorizzazione per utilizzare uno strumento (come eliminare file o eseguire comandi), e quando ha domande di chiarimento (tramite lo strumento 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 callback canUseTool 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:
async def handle_tool_request(tool_name, input_data, context):
    # Chiedi all'utente e restituisci allow o deny
    ...


options = ClaudeAgentOptions(can_use_tool=handle_tool_request)
Il callback si attiva in due casi:
  1. Lo strumento ha bisogno di approvazione: Claude vuole utilizzare uno strumento che non è approvato automaticamente dalle regole di autorizzazione o dalle modalità. Controlla tool_name per lo strumento (ad es. "Bash", "Write").
  2. Claude pone una domanda: Claude chiama lo strumento AskUserQuestion. Controlla se tool_name == "AskUserQuestion" per gestirlo diversamente. Se specifichi un array tools, includi AskUserQuestion affinché 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 callback canUseTool nelle opzioni della query, si attiva quando Claude vuole utilizzare uno strumento che non è approvato automaticamente. Il tuo callback riceve tre argomenti:
ArgomentoDescrizione
toolNameIl nome dello strumento che Claude vuole utilizzare (ad es. "Bash", "Write", "Edit")
inputI 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.
L’oggetto input contiene parametri specifici dello strumento. Esempi comuni:
StrumentoCampi di input
Bashcommand, description, timeout
Writefile_path, content
Editfile_path, old_string, new_string
Readfile_path, offset, limit
Vedi il riferimento SDK per gli schemi di input completi: Python | TypeScript. Puoi visualizzare queste informazioni all’utente in modo che possa decidere se consentire o rifiutare l’azione, quindi restituire la risposta appropriata. L’esempio seguente chiede a Claude di creare ed eliminare un file di test. Quando Claude tenta ogni operazione, il callback stampa la richiesta dello strumento nel terminale e chiede l’approvazione s/n.
import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from claude_agent_sdk.types import (
    HookMatcher,
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


async def can_use_tool(
    tool_name: str, input_data: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    # Visualizza la richiesta dello strumento
    print(f"\nTool: {tool_name}")
    if tool_name == "Bash":
        print(f"Command: {input_data.get('command')}")
        if input_data.get("description"):
            print(f"Description: {input_data.get('description')}")
    else:
        print(f"Input: {input_data}")

    # Ottieni l'approvazione dell'utente
    response = input("Allow this action? (y/n): ")

    # Restituisci allow o deny in base alla risposta dell'utente
    if response.lower() == "y":
        # Allow: lo strumento viene eseguito con l'input originale (o modificato)
        return PermissionResultAllow(updated_input=input_data)
    else:
        # Deny: lo strumento non viene eseguito, Claude vede il messaggio
        return PermissionResultDeny(message="User denied this action")


# Workaround richiesto: dummy hook mantiene il flusso aperto per can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
    return {"continue_": True}


async def prompt_stream():
    yield {
        "type": "user",
        "message": {
            "role": "user",
            "content": "Create a test file in /tmp and then delete it",
        },
    }


async def main():
    async for message in query(
        prompt=prompt_stream(),
        options=ClaudeAgentOptions(
            can_use_tool=can_use_tool,
            hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
        ),
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())
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.
Questo esempio utilizza un flusso s/n in cui qualsiasi input diverso da 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:
RispostaPythonTypeScript
AllowPermissionResultAllow(updated_input=...){ behavior: "allow", updatedInput }
DenyPermissionResultDeny(message=...){ behavior: "deny", message }
Quando consenti, passa l’input dello strumento (originale o modificato). Quando neghi, fornisci un messaggio che spiega il motivo. Claude vede questo messaggio e potrebbe adattare il suo approccio.
from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

# Consenti l'esecuzione dello strumento
return PermissionResultAllow(updated_input=input_data)

# Blocca lo strumento
return PermissionResultDeny(message="User rejected this action")
Oltre a consentire o negare, puoi modificare l’input dello strumento o fornire contesto che aiuta Claude ad adattare il suo approccio:
  • 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
L’utente approva l’azione così com’è. Passa l’input dal tuo callback invariato e lo strumento viene eseguito esattamente come richiesto da Claude.
async def can_use_tool(tool_name, input_data, context):
    print(f"Claude wants to use {tool_name}")
    approved = await ask_user("Allow this action?")

    if approved:
        return PermissionResultAllow(updated_input=input_data)
    return PermissionResultDeny(message="User declined")

Gestire domande di chiarimento

Quando Claude ha bisogno di più direzione su un’attività con più approcci validi, chiama lo strumento AskUserQuestion. 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.
Le domande di chiarimento sono particolarmente comuni nella modalità plan, dove Claude esplora la base di codice e pone domande prima di proporre un piano. Questo rende la modalità plan ideale per flussi di lavoro interattivi in cui vuoi che Claude raccolga i requisiti prima di apportare modifiche.
I seguenti passaggi mostrano come gestire le domande di chiarimento:
1

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:
async for message in query(
    prompt="Analyze this codebase",
    options=ClaudeAgentOptions(
        # Includi AskUserQuestion nella tua lista di strumenti
        tools=["Read", "Glob", "Grep", "AskUserQuestion"],
        can_use_tool=can_use_tool,
    ),
):
    print(message)
2

Rileva AskUserQuestion

Nel tuo callback, controlla se toolName è uguale a AskUserQuestion per gestirlo diversamente da altri strumenti:
async def can_use_tool(tool_name: str, input_data: dict, context):
    if tool_name == "AskUserQuestion":
        # La tua implementazione per raccogliere risposte dall'utente
        return await handle_clarifying_questions(input_data)
    # Gestisci altri strumenti normalmente
    return await prompt_for_approval(tool_name, input_data)
3

Analizza l'input della domanda

L’input contiene le domande di Claude in un array questions. Ogni domanda ha una question (il testo da visualizzare), options (le scelte) e multiSelect (se sono consentite più selezioni):
{
  "questions": [
    {
      "question": "How should I format the output?",
      "header": "Format",
      "options": [
        { "label": "Summary", "description": "Brief overview" },
        { "label": "Detailed", "description": "Full explanation" }
      ],
      "multiSelect": false
    },
    {
      "question": "Which sections should I include?",
      "header": "Sections",
      "options": [
        { "label": "Introduction", "description": "Opening context" },
        { "label": "Conclusion", "description": "Final summary" }
      ],
      "multiSelect": true
    }
  ]
}
Vedi Formato della domanda per le descrizioni complete dei campi.
4

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

Restituisci le risposte a Claude

Costruisci l’oggetto answers come un record in cui ogni chiave è il testo question e ogni valore è l’label dell’opzione selezionata:
Dall’oggetto domandaUsa come
Campo question (ad es. "How should I format the output?")Chiave
Campo label dell’opzione selezionata (ad es. "Summary")Valore
Per le domande a selezione multipla, passa un array di etichette o uniscile con ", ". Se supporti input di testo libero, utilizza il testo personalizzato dell’utente come valore.
return PermissionResultAllow(
    updated_input={
        "questions": input_data.get("questions", []),
        "answers": {
            "How should I format the output?": "Summary",
            "Which sections should I include?": ["Introduction", "Conclusion"],
        },
    }
)

Formato della domanda

L’input contiene le domande generate da Claude in un array questions. Ogni domanda ha questi campi:
CampoDescrizione
questionIl testo completo della domanda da visualizzare
headerEtichetta breve per la domanda (max 12 caratteri)
optionsArray di 2-4 scelte, ognuna con label e description. TypeScript: opzionalmente preview (vedi sotto)
multiSelectSe true, gli utenti possono selezionare più opzioni
La struttura che il tuo callback riceve:
{
  "questions": [
    {
      "question": "How should I format the output?",
      "header": "Format",
      "options": [
        { "label": "Summary", "description": "Brief overview of key points" },
        { "label": "Detailed", "description": "Full explanation with examples" }
      ],
      "multiSelect": false
    }
  ]
}

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.
previewFormatpreview 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)
Il formato si applica a tutte le domande nella sessione. Claude include 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.
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Help me choose a card layout",
  options: {
    toolConfig: {
      askUserQuestion: { previewFormat: "html" }
    },
    canUseTool: async (toolName, input) => {
      // input.questions[].options[].preview è una stringa HTML o undefined
      return { behavior: "allow", updatedInput: input };
    }
  }
})) {
  // ...
}
Un’opzione con un’anteprima HTML:
{
  "label": "Compact",
  "description": "Title and metric value only",
  "preview": "<div style=\"padding:12px;border:1px solid #ddd;border-radius:8px\"><div style=\"font-size:12px;color:#666\">Active users</div><div style=\"font-size:28px;font-weight:600\">1,284</div></div>"
}

Formato della risposta

Restituisci un oggetto answers che mappa il campo question di ogni domanda all’label dell’opzione selezionata:
CampoDescrizione
questionsPassa l’array di domande originale (obbligatorio per l’elaborazione dello strumento)
answersOggetto in cui le chiavi sono il testo della domanda e i valori sono le etichette selezionate
responseRisposta facoltativa in testo libero che l’utente ha digitato invece di rispondere alle domande strutturate
Per le domande a selezione multipla, passa un array di etichette o uniscile con ", ". 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.
{
  "questions": [
    // ...
  ],
  "answers": {
    "How should I format the output?": "Summary",
    "Which sections should I include?": ["Introduction", "Conclusion"]
  }
}

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”)
Vedi l’esempio completo di seguito per un’implementazione completa.

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:
  1. Instrada la richiesta: Il callback canUseTool controlla se il nome dello strumento è "AskUserQuestion" e instrada a un gestore dedicato
  2. Visualizza le domande: Il gestore scorre l’array questions e stampa ogni domanda con opzioni numerate
  3. Raccogli input: L’utente può inserire un numero per selezionare un’opzione, o digitare testo libero direttamente (ad es. “jquery”, “i don’t know”)
  4. Mappa le risposte: Il codice controlla se l’input è numerico (utilizza l’etichetta dell’opzione) o testo libero (utilizza il testo direttamente)
  5. Restituisci a Claude: La risposta include sia l’array questions originale che la mappatura answers
import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from claude_agent_sdk.types import HookMatcher, PermissionResultAllow


def parse_response(response: str, options: list) -> str:
    """Analizza l'input dell'utente come numero(i) di opzione o testo libero."""
    try:
        indices = [int(s.strip()) - 1 for s in response.split(",")]
        labels = [options[i]["label"] for i in indices if 0 <= i < len(options)]
        return ", ".join(labels) if labels else response
    except ValueError:
        return response


async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow:
    """Visualizza le domande di Claude e raccogli le risposte dell'utente."""
    answers = {}

    for q in input_data.get("questions", []):
        print(f"\n{q['header']}: {q['question']}")

        options = q["options"]
        for i, opt in enumerate(options):
            print(f"  {i + 1}. {opt['label']} - {opt['description']}")
        if q.get("multiSelect"):
            print("  (Enter numbers separated by commas, or type your own answer)")
        else:
            print("  (Enter a number, or type your own answer)")

        response = input("Your choice: ").strip()
        answers[q["question"]] = parse_response(response, options)

    return PermissionResultAllow(
        updated_input={
            "questions": input_data.get("questions", []),
            "answers": answers,
        }
    )


async def can_use_tool(
    tool_name: str, input_data: dict, context
) -> PermissionResultAllow:
    # Instrada AskUserQuestion al nostro gestore di domande
    if tool_name == "AskUserQuestion":
        return await handle_ask_user_question(input_data)
    # Auto-approva altri strumenti per questo esempio
    return PermissionResultAllow(updated_input=input_data)


async def prompt_stream():
    yield {
        "type": "user",
        "message": {
            "role": "user",
            "content": "Help me decide on the tech stack for a new mobile app",
        },
    }


# Workaround richiesto: dummy hook mantiene il flusso aperto per can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
    return {"continue_": True}


async def main():
    async for message in query(
        prompt=prompt_stream(),
        options=ClaudeAgentOptions(
            can_use_tool=can_use_tool,
            hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
        ),
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

Limitazioni

  • Subagenti: AskUserQuestion non è attualmente disponibile nei subagenti generati tramite lo strumento Agent
  • Limiti delle domande: ogni chiamata AskUserQuestion supporta 1-4 domande con 2-4 opzioni ciascuna

Altri modi per ottenere input dall’utente

Il callback canUseTool 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
L’input streaming è ideale per interfacce conversazionali in cui gli utenti interagiscono con l’agente durante l’esecuzione, non solo nei checkpoint di approvazione.

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
Gli strumenti personalizzati ti danno il controllo completo sull’interazione, ma richiedono più lavoro di implementazione rispetto all’utilizzo del callback canUseTool integrato.

Risorse correlate