AskUserQuestion-Tool). Beide lösen Ihren canUseTool-Callback aus, der die Ausführung pausiert, bis Sie eine Antwort zurückgeben. Dies unterscheidet sich von normalen Gesprächsrunden, bei denen Claude fertig ist und auf Ihre nächste Nachricht wartet.
Bei Klärungsfragen generiert Claude die Fragen und Optionen. Ihre Aufgabe besteht darin, sie den Benutzern zu präsentieren und ihre Auswahl zurückzugeben. Sie können diesem Ablauf keine eigenen Fragen hinzufügen; wenn Sie Benutzer selbst etwas fragen müssen, tun Sie dies separat in Ihrer Anwendungslogik.
Der Callback kann unbegrenzt ausstehend bleiben. Die Ausführung bleibt pausiert, bis Ihr Callback zurückkommt, und das SDK bricht das Warten nur ab, wenn die Abfrage selbst abgebrochen wird. Wenn ein Benutzer länger braucht, um zu antworten, als Ihr Prozess vernünftigerweise laufen kann, geben Sie die defer-Hook-Entscheidung zurück, mit der der Prozess beendet und später aus der persistierten Sitzung fortgesetzt werden kann.
Diese Anleitung zeigt Ihnen, wie Sie jeden Anforderungstyp erkennen und angemessen reagieren.
Erkennen Sie, wenn Claude Eingaben benötigt
Übergeben Sie einencanUseTool-Callback in Ihren Abfrageoptionen. Der Callback wird ausgelöst, wenn Claude Benutzereingaben benötigt, und erhält den Tool-Namen und die Eingabe als Argumente:
- Tool benötigt Genehmigung: Claude möchte ein Tool verwenden, das nicht durch eine Berechtigungsregel oder einen Berechtigungsmodus automatisch genehmigt wird. Überprüfen Sie
tool_nameauf das Tool (z. B."Bash","Write"). - Claude stellt eine Frage: Claude ruft das
AskUserQuestion-Tool auf. Überprüfen Sie, obtool_name == "AskUserQuestion", um es anders zu behandeln. Wenn Sie eintools-Array angeben, fügen SieAskUserQuestionein, damit dies funktioniert. Siehe Klärungsfragen verarbeiten für Details.
PermissionRequest-Hook verwenden, um externe Benachrichtigungen (Slack, E-Mail, Push) zu senden, wenn Claude auf Genehmigung wartet.
Tool-Genehmigungsanfragen verarbeiten
Nachdem Sie einencanUseTool-Callback in Ihren Abfrageoptionen übergeben haben, wird er ausgelöst, wenn Claude ein Tool verwenden möchte, das nicht automatisch genehmigt ist. Ihr Callback erhält drei Argumente:
Das
input-Objekt enthält Tool-spezifische Parameter. Häufige Beispiele:
Siehe die SDK-Referenz für vollständige Eingabeschemas: Python | TypeScript.
Sie können diese Informationen dem Benutzer anzeigen, damit er entscheiden kann, ob er die Aktion zulässt oder ablehnt, und dann die entsprechende Antwort zurückgeben.
Das folgende Beispiel fordert Claude auf, eine Testdatei zu erstellen und zu löschen. Wenn Claude jeden Vorgang versucht, druckt der Callback die Tool-Anfrage auf dem Terminal aus und fordert zur y/n-Genehmigung auf.
In Python erfordert
can_use_tool den Streaming-Modus. Wenn Sie einen endlichen Nachrichtenstrom durch query(prompt=generator) oder ClaudeSDKClient.connect(prompt=async_iterable) übergeben, schließt das SDK den Eingabestrom nach der letzten Nachricht, bevor der Berechtigungscallback aufgerufen werden kann, es sei denn, ein registrierter Hook oder ein In-Process-MCP-Server hält ihn offen. Das obige Beispiel hält ihn mit einem PreToolUse-Hook offen, der {"continue_": True} zurückgibt. Das Verbinden ohne Eingabeaufforderung und das Senden von Nachrichten über ClaudeSDKClient.query() hält den Stream von selbst offen und benötigt keinen Hook.y/n-Ablauf, bei dem jede Eingabe außer y als Ablehnung behandelt wird. In der Praxis könnten Sie eine umfangreichere Benutzeroberfläche erstellen, die es Benutzern ermöglicht, die Anfrage zu ändern, Feedback zu geben oder Claude vollständig umzuleiten. Siehe Auf Tool-Anfragen reagieren für alle Möglichkeiten, wie Sie reagieren können.
Auf Tool-Anfragen reagieren
Ihr Callback gibt einen von zwei Antworttypen zurück:
Beim Zulassen wird das Tool mit der von Claude angeforderten Eingabe ausgeführt, es sei denn, Sie geben eine geänderte Eingabe zurück,
updatedInput in TypeScript oder updated_input in Python. Vor v2.1.207 lehnte Claude Code ein Zulassungsergebnis ab, das updatedInput auslies, und lehnte den Tool-Aufruf mit einem Validierungsfehler ab.
Beim Ablehnen geben Sie eine Nachricht an, die erklärt, warum. Claude sieht diese Nachricht und kann seinen Ansatz anpassen.
- Genehmigen: Lassen Sie das Tool genau wie von Claude angefordert ausführen
- Mit Änderungen genehmigen: Ändern Sie die Eingabe vor der Ausführung (z. B. Pfade bereinigen, Einschränkungen hinzufügen)
- Genehmigen und merken: Geben Sie eine vorgeschlagene Berechtigungsregel zurück, damit übereinstimmende Aufrufe das nächste Mal die Aufforderung überspringen
- Ablehnen: Blockieren Sie das Tool und teilen Sie Claude mit, warum
- Alternative vorschlagen: Blockieren Sie, aber leiten Sie Claude zu dem hin, was der Benutzer stattdessen möchte
- Vollständig umleiten: Verwenden Sie Streaming-Eingabe, um Claude eine völlig neue Anweisung zu senden
- Genehmigen
- Mit Änderungen genehmigen
- Genehmigen und merken
- Ablehnen
- Alternative vorschlagen
- Vollständig umleiten
Der Benutzer genehmigt die Aktion unverändert. Geben Sie die
input aus Ihrem Callback unverändert durch und das Tool wird genau wie von Claude angefordert ausgeführt.Klärungsfragen verarbeiten
Wenn Claude mehr Anleitung zu einer Aufgabe mit mehreren gültigen Ansätzen benötigt, ruft es dasAskUserQuestion-Tool auf. Dies löst Ihren canUseTool-Callback mit toolName auf AskUserQuestion aus. Die Eingabe enthält Claudes Fragen als Multiple-Choice-Optionen, die Sie dem Benutzer anzeigen und deren Auswahl zurückgeben.
Die folgenden Schritte zeigen, wie Sie Klärungsfragen verarbeiten:
1
Übergeben Sie einen canUseTool-Callback
Übergeben Sie einen
canUseTool-Callback in Ihren Abfrageoptionen. Standardmäßig ist AskUserQuestion verfügbar. Wenn Sie ein tools-Array angeben, um Claudes Funktionen einzuschränken (z. B. einen schreibgeschützten Agent mit nur Read, Glob und Grep), fügen Sie AskUserQuestion in dieses Array ein. Andernfalls kann Claude keine Klärungsfragen stellen:2
Erkennen Sie AskUserQuestion
Überprüfen Sie in Ihrem Callback, ob
toolName gleich AskUserQuestion ist, um es anders als andere Tools zu behandeln:3
Analysieren Sie die Frageneingabe
Die Eingabe enthält Claudes Fragen in einem Siehe Frageformat für vollständige Feldbeschreibungen.
questions-Array. Jede Frage hat eine question (der anzuzeigende Text), options (die Auswahlmöglichkeiten) und multiSelect (ob mehrere Auswahlen zulässig sind):4
Sammeln Sie Antworten vom Benutzer
Präsentieren Sie die Fragen dem Benutzer und sammeln Sie deren Auswahl. Wie Sie dies tun, hängt von Ihrer Anwendung ab: ein Terminal-Prompt, ein Web-Formular, ein mobiler Dialog usw.
5
Geben Sie Antworten an Claude zurück
Erstellen Sie das
answers-Objekt als Datensatz, wobei jeder Schlüssel der question-Text ist und jeder Wert das label der ausgewählten Option ist:Für Multi-Select-Fragen übergeben Sie ein Array von Labels oder verbinden Sie sie mit
", ". Wenn Sie freie Texteingabe unterstützen, verwenden Sie den benutzerdefinierten Text des Benutzers als Wert.Frageformat
Die Eingabe enthält Claudes generierte Fragen in einemquestions-Array. Jede Frage hat diese Felder:
Die Struktur, die Ihr Callback erhält:
Optionsvorschau (TypeScript)
toolConfig.askUserQuestion.previewFormat fügt jedem Option ein preview-Feld hinzu, damit Ihre App ein visuelles Mockup neben dem Label anzeigen kann. Ohne diese Einstellung generiert Claude keine Vorschau und das Feld ist nicht vorhanden.
Das Format gilt für alle Fragen in der Sitzung. Claude fügt
preview bei Optionen ein, bei denen ein visueller Vergleich hilfreich ist (Layout-Auswahlmöglichkeiten, Farbschemas) und lässt es weg, wo nicht (Ja/Nein-Bestätigungen, nur Text-Auswahlmöglichkeiten). Überprüfen Sie auf undefined, bevor Sie rendern.
Antwortformat
Geben Sie einanswers-Objekt zurück, das jedes question-Feld der Frage dem label der ausgewählten Option zuordnet:
Für Multi-Select-Fragen übergeben Sie ein Array von Labels oder verbinden Sie sie mit
", ". Für benutzerdefinierte freie Texteingaben wie eine „Other”-Option geben Sie den Text des Benutzers in answers[question] ein, wie in Freie Texteingabe unterstützen gezeigt. Setzen Sie response nur, wenn Ihre Benutzeroberfläche dem Benutzer ermöglicht, die Fragenkarte zu schließen und eine allgemeine Antwort einzugeben, die keine Antwort auf eine bestimmte Frage ist. Wenn response gesetzt ist, erhält Claude „Der Benutzer hat geantwortet: …” anstelle der Liste der Antworten pro Frage.
Unterstützen Sie freie Texteingabe
Claudes vordefinierte Optionen decken nicht immer ab, was Benutzer möchten. Um Benutzern zu ermöglichen, ihre eigene Antwort einzugeben:- Zeigen Sie nach Claudes Optionen eine zusätzliche „Other”-Auswahlmöglichkeit an, die Texteingabe akzeptiert
- Verwenden Sie den benutzerdefinierten Text des Benutzers als Antwortwert (nicht das Wort „Other”)
Vollständiges Beispiel
Claude stellt Klärungsfragen, wenn er Benutzereingaben benötigt, um fortzufahren. Wenn Claude beispielsweise aufgefordert wird, bei der Entscheidung über einen Tech-Stack für eine mobile App zu helfen, könnte Claude Fragen zu Cross-Platform vs. Native, Backend-Vorlieben oder Zielplattformen stellen. Diese Fragen helfen Claude, Entscheidungen zu treffen, die den Vorlieben des Benutzers entsprechen, anstatt zu raten. Dieses Beispiel verarbeitet diese Fragen in einer Terminal-Anwendung. Hier ist, was bei jedem Schritt passiert:- Leiten Sie die Anfrage weiter: Der
canUseTool-Callback überprüft, ob der Tool-Name"AskUserQuestion"ist, und leitet zu einem dedizierten Handler weiter - Zeigen Sie Fragen an: Der Handler durchläuft das
questions-Array und druckt jede Frage mit nummerierten Optionen - Sammeln Sie Eingaben: Der Benutzer kann eine Nummer eingeben, um eine Option auszuwählen, oder direkt freien Text eingeben (z. B. „jquery”, „i don’t know”)
- Ordnen Sie Antworten zu: Der Code überprüft, ob die Eingabe numerisch ist (verwendet das Label der Option) oder freier Text (verwendet den Text direkt)
- Geben Sie an Claude zurück: Die Antwort enthält sowohl das ursprüngliche
questions-Array als auch dieanswers-Zuordnung
ask.ts und führen Sie sie mit npx tsx ask.ts aus, oder speichern Sie die Python-Version als ask.py und führen Sie sie mit python ask.py aus.
Einschränkungen
- Subagenten:
AskUserQuestionist derzeit nicht in Subagenten verfügbar, die über das Agent-Tool erzeugt werden - Fragenlimits: Jeder
AskUserQuestion-Aufruf unterstützt 1-4 Fragen mit jeweils 2-4 Optionen
Andere Möglichkeiten, Benutzereingaben zu erhalten
DercanUseTool-Callback und das AskUserQuestion-Tool decken die meisten Genehmigungs- und Klärungsszenarien ab, aber das SDK bietet andere Möglichkeiten, Eingaben von Benutzern zu erhalten:
Streaming-Eingabe
Verwenden Sie Streaming-Eingabe, wenn Sie:- Den Agent mitten in der Aufgabe unterbrechen: Senden Sie ein Abbruchsignal oder ändern Sie die Richtung, während Claude arbeitet
- Zusätzlichen Kontext bereitstellen: Fügen Sie Informationen hinzu, die Claude benötigt, ohne darauf zu warten, dass es fragt
- Chat-Schnittstellen erstellen: Lassen Sie Benutzer Folgenachrichten während langwieriger Operationen senden
Benutzerdefinierte Tools
Verwenden Sie benutzerdefinierte Tools, wenn Sie:- Strukturierte Eingaben sammeln: Erstellen Sie Formulare, Assistenten oder mehrstufige Workflows, die über das Multiple-Choice-Format von
AskUserQuestionhinausgehen - Externe Genehmigungssysteme integrieren: Verbinden Sie sich mit bestehenden Ticketing-, Workflow- oder Genehmigungsplattformen
- Domänenspezifische Interaktionen implementieren: Erstellen Sie Tools, die auf die Anforderungen Ihrer Anwendung zugeschnitten sind, wie Code-Review-Schnittstellen oder Bereitstellungs-Checklisten
canUseTool-Callbacks.
Verwandte Ressourcen
- Berechtigungen konfigurieren: Richten Sie Berechtigungsmodi und -regeln ein
- Ausführung mit Hooks steuern: Führen Sie benutzerdefinierten Code an Schlüsselpunkten im Agent-Lebenszyklus aus
- TypeScript SDK-Referenz: Vollständige canUseTool-API-Dokumentation