Gestire approvazioni e input dell'utente

Mentre lavora 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 della tua applicazione.

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

Gestire richieste di approvazione dello strumento

Una volta passato un callback canUseTool nelle opzioni della tua query, si attiva quando Claude vuole utilizzare uno strumento che non è approvato automaticamente. Il tuo callback riceve due argomenti:

L'oggetto input contiene parametri specifici dello strumento. Esempi comuni:

Vedi il riferimento dell'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, 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: hook dummy 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 hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

Questo esempio utilizza un flusso s/n in cui qualsiasi input diverso da s è 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:

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 un contesto che aiuti 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)
• Rifiuta: blocca lo strumento e spiega a Claude il motivo
• Suggerisci un'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

Gestire domande di chiarimento

Quando Claude ha bisogno di più indicazioni 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 loro selezioni.

I seguenti passaggi mostrano come gestire le domande di chiarimento:

Formato della domanda

L'input contiene le domande generate da Claude in un array questions. Ogni domanda ha questi campi:

Ecco un esempio della struttura che riceverai:

{
  "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
    }
  ]
}

Formato della risposta

Restituisci un oggetto answers che mappa il campo question di ogni domanda all'label dell'opzione selezionata:

Per le domande a selezione multipla, unisci più label con ", ". Per l'input di testo libero, utilizza il testo personalizzato dell'utente direttamente.

{
  "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 uno stack tecnologico per un'app mobile, Claude potrebbe chiedere informazioni su cross-platform vs nativo, preferenze di backend o piattaforme target. 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, 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: hook dummy 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 hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

Limitazioni

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

Altri modi per ottenere input dell'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 le interfacce conversazionali in cui gli utenti interagiscono con l'agente durante l'esecuzione, non solo nei punti 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, flussi 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 liste 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

• Configura autorizzazioni: imposta 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 completa dell'API canUseTool