Human-in-the-loop für das Claude Agent SDK
Menschliche Entscheidungen für das Claude Agent SDK, mit einem canUseTool.
Braucht dein Claude-Agent für ein Tool eine Erlaubnis, tippt dein Nutzer auf dem Handy auf „Genehmigen“ oder „Ablehnen“.
Was Claude Agent SDK mitbringt
Der canUseTool-Callback
Im Claude Agent SDK kannst du einen Tool-Aufruf vor seiner Ausführung prüfen. Jedes Tool, das eine Erlaubnis braucht, läuft zuerst durch deinen canUseTool-Callback. Dort gibst du allow oder deny zurück und kannst die Eingabe ändern.
const result = query({
prompt,
options: {
canUseTool: async (toolName, input) => {
// your decision goes here
return { behavior: "allow", updatedInput: input }
},
},
})Wo es nicht weitergeht
- Der Callback antwortet innerhalb deines Prozesses. Er erreicht keine Person, die nicht an diesem Rechner sitzt.
- Er muss antworten, bevor das SDK aufhört zu warten. Lange menschliche Wartezeiten musst du daher außerhalb davon behandeln.
- Allow und deny hinterlassen keine Spur. Daraus entsteht kein Nachweis, den du später durchsuchen kannst.
Die Lösung
Pushary holt die Antwort deines Nutzers ein.
canUseTool entscheidet, ob ein Tool läuft. pusharyCanUseTool übernimmt diese Aufgabe: Die Frage geht auf das Handy deines Nutzers, sein Tipp kommt als allow oder deny zurück, und jede Antwort wird gespeichert.
Übergib pusharyCanUseTool() mit deiner eigenen Nutzer-ID in den Optionen von query(). Eine Freigabe führt das Tool mit unveränderter Eingabe aus. Ablehnung oder keine rechtzeitige Antwort liefern eine Ablehnung, die das Modell lesen kann. Auch Claudes AskUserQuestion-Fragen gehen als Auswahlfragen aufs Handy.
npm i @pushary/claude-agent-sdk @anthropic-ai/claude-agent-sdkimport { query } from "@anthropic-ai/claude-agent-sdk"
import { pusharyCanUseTool } from "@pushary/claude-agent-sdk"
for await (const message of query({
prompt: "Refund order 1234",
options: { canUseTool: pusharyCanUseTool({ externalId: user.id }) },
})) {
if (message.type === "result") console.log(message.subtype)
}So funktioniert es
Von der Installation zur ersten Antwort
Verbinde deinen Nutzer einmal. Sichere den riskanten Schritt mit einer Freigabe ab. Pushary schickt die Frage, wartet auf die Antwort und speichert sie.
- 01
Adapter installieren
Führe npm i @pushary/claude-agent-sdk @anthropic-ai/claude-agent-sdk aus und setze PUSHARY_API_KEY auf den Schlüssel aus dem Partner-Onboarding.
- 02
Das Handy jedes Nutzers einmal verbinden
connect() liefert einen Link. Dein Nutzer öffnet ihn einmal auf seinem Handy und installiert die kostenlose Pushary-App. Kein Pushary-Konto, keine Zahlung.
- 03
Die Freigabesperre an query() übergeben
Setze canUseTool auf pusharyCanUseTool() mit deiner eigenen Nutzer-ID. Nimm die ID vom angemeldeten Nutzer, niemals aus der Tool-Eingabe. Denn die Tool-Eingabe schreibt das Modell.
- 04
Auf die Antwort reagieren
Eine Freigabe führt das Tool unverändert aus. Ablehnung, fehlende Antwort oder ein abgebrochener Lauf liefern eine Ablehnung mit Begründung; das Tool läuft nicht.
Eine Frage kann ein Ja oder Nein verlangen, eine Auswahl aus einer Liste oder eine Texteingabe. Jede Antwort wird gespeichert.
Vor der Veröffentlichung
Stolperfallen bei Claude Agent SDK
- Deine Pushary-Regeln sind aus, bis du sie einschaltest
- Claudes Tools haben dieselben Namen wie in deinem eigenen Claude Code: Bash, Read, Write. Eine Regel für deine eigenen Sitzungen würde daher auch Aufrufe deiner Nutzer beantworten. Standardmäßig geht jeder gesperrte Aufruf deshalb an einen Menschen. Setze policy: true nur für Regeln, die du für diesen Agenten geschrieben hast.
- Eine Ablehnung ohne Grund verwirrt das Modell
- Ein deny ohne Begründung führt oft dazu, dass der Agent einen leicht geänderten Befehl für dasselbe Ziel versucht. Gib einen Grund zurück. So erkennt das Modell eine menschliche Entscheidung statt eines fehlerhaften Aufrufs und hört auf, umzuformulieren.
- Prüfe die Eingabe, nicht nur den Tool-Namen
- Bash umfasst unter einem Tool-Namen sowohl git status als auch rm -rf. Prüfst du nur den Namen, unterbrichst du entweder ständig oder lässt genau den kritischen Aufruf durch. Die Entscheidung muss die Argumente berücksichtigen.
- Auch Subagenten rufen Tools auf
- An einen Subagenten delegierte Arbeit führt weiterhin Tools aus. Wenn du nur mit einem Callback in einer geradlinigen Sitzung rechnest, können dich Aufrufe aus delegierter Arbeit überraschen.
Der Partner-Tarif
Dein Agent fragt deine Nutzer, nicht nur dich
Stelle deinen Nutzern deinen Agenten bereit. Jeder gibt dessen riskante Aktionen vom eigenen Handy aus frei, unter deiner Marke.
Deine Nutzer brauchen kein Pushary-Konto und zahlen nichts an uns.
Deine Nutzer antworten auf ihren eigenen Handys
Verbinde jeden Nutzer einmal über einen Link. Er installiert die kostenlose Pushary-App und antwortet vom Sperrbildschirm aus, ohne eigenes Konto.
Keine Antwort heißt Nein
Führe die Aktion nur nach einer ausdrücklichen Freigabe aus. Eine wartende, abgelaufene oder abgebrochene Anfrage zählt nie als Ja. Pushary behält jede Anfrage, damit dein Code sie nach einem Neustart wieder aufnehmen kann.
Erreicht sie auf dem Handy
Die App kommt zuerst, denn nur sie zeigt „Genehmigen“ und „Ablehnen“ auf dem Sperrbildschirm. Browser-Benachrichtigungen folgen danach. Du musst kein Zustellsystem bauen.
Jede Antwort gespeichert
Zu jeder Antwort wird gespeichert, wer wann geantwortet hat. Du kannst sie durchsuchen und exportieren. Mit einer Callback-URL geht jede Antwort außerdem als signierter Webhook an deinen Server.
FAQ
Fragen und Antworten
Brauche ich für das Claude Agent SDK ein Pushary-npm-Paket?
Welche Tool-Namen erlaube ich für den MCP-Server?
Funktioniert das im Python Claude Agent SDK?
Wer beantwortet die Frage?
Was passiert, wenn niemand vor Ablauf des Zeitfensters antwortet?
Lass deinen Claude Agent SDK-Agenten fragen, bevor er handelt.
Verbinde einen Nutzer einmal, frage mit einem Aufruf und führe die Aktion nur bei einem Ja aus. Jede Antwort wird gespeichert.
Start freePartner-Tarif, $99 im Monat. Deine Nutzer brauchen kein Pushary-Konto und zahlen nichts an uns.