Agent SDK で人に確認する｜承認と質問の受け方

AI エージェントに仕事を任せていると、「このファイルを消してもいいですか」「どちらのやり方で進めますか」 と、AI のほうから聞きたくなる場面があります。自社の画面にこの確認をどう出すかを決めておかないと、AI は返事を待ったまま止まってしまいます。

この記事では、公式ドキュメント「Handle approvals and user input」（2026年11月10日確認）にもとづいて、Claude Agent SDK で人に確認を求める場面の扱い方を整理します。SDK の全体像は Claude Agent SDK とは で解説しています。

結論：人に聞く場面は2つ、届く先は1つ

AI が人に聞くのは、「道具を使う許可がほしい時」と「やり方を選んでほしい時」の2つだけ です。どちらも、あなたが渡した canUseTool という関数 に届きます。

関数が返事をするまで、AI は止まって待ち続けます。 返事に何時間もかかりそうな仕組みなら、道具の手前のフックで「あとに回す（defer）」を返し、あとから再開する作りにします。フックは Agent SDK のフック で解説しています。

許可を求められた時の返し方

関数には、道具の名前、AI が渡そうとしている中身（コマンドやファイルの場所など）が届きます。これを画面に出して、人に判断してもらいます。返事は「許可」か「拒否」の2種類ですが、組み合わせで6通りの答え方ができます。

1. そのまま許可：AI が頼んだとおりに実行する
2. 直して許可：中身を書き換えてから実行する（場所を安全な所に変えるなど）
3. 許可して覚える：提案された許可のルールを返し、次から同じ物は聞かない
4. 拒否する：理由を添えて止める。AI は理由を読んでやり方を変える
5. 別の案を示す：止めたうえで、こうしてほしいと伝える
6. 指示を出し直す：まったく新しい指示を送る（会話を続けながら入力を送る形で）

なお、dontAsk モードのように、そもそもこの関数を呼ばない設定もあります。 どこで許可が決まるかは Agent SDK の権限設定 を参照してください。

質問された時の答え方

やり方が何通りもある時、AI は AskUserQuestion という道具で、選択肢つきの質問 を出します。質問と選択肢は AI が作ります。あなたの仕事は、それを画面に出して、選ばれた答えを返すことです。

答えは、「質問の全文」をかぎに、「選ばれた選択肢の見出し」を値にして返します。 複数選べる質問なら、見出しを並べて返します。選択肢に合う物が無い人のために「その他」を出し、打ち込まれた文章をそのまま答えにする作りもできます。

TypeScript 版では、選択肢ごとに見た目の見本（文字の図や HTML のかけら）を付けてもらう設定もあります。画面の配置や色を選ぶ質問で役立ちます。

つまずきやすい点

• 使える道具を絞っている時は、AskUserQuestion も入れておく。 入れないと AI は質問できない
• 質問は1回に1〜4問・選択肢は2〜4個まで
• サブエージェントからは質問できない（親の会話だけ）
• この流れに 自分の質問を混ぜることはできない。 自分で聞きたいことは、アプリの側で別に聞く
• 許可待ちを担当者に知らせたいときは、許可を求める時のフックで、チャットやメールに通知する

仕事で使うときの考え方

確認を入れる場所は、取り消せるかどうかで決めます。 下書きの作成や調べ物は任せ、送信・削除・支払いのような取り消せない操作の手前だけで確認を入れると、待ち時間と安全のつり合いが取れます。

まとめ

• 人に聞くのは 許可 と 質問 の2場面。どちらも canUseTool に届く
• 許可は そのまま・直して・覚える・拒否・別案・出し直し の6通りで返せる
• 質問は 質問文をかぎ、選んだ見出しを値 にして返す。サブエージェントからは聞けない

出典

• Claude Code 公式ドキュメント「Handle approvals and user input」

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。