Claude Agent SDK のカスタムツール｜自社の処理をAIに渡す

公開 更新 著者 永上裕之マルチエージェント
#Claude Agent SDK#カスタムツール#MCP#AIエージェント#Python
AIの手元に、会社専用の工具を1本ずつ手渡していくイメージ

この記事の要点

  • カスタムツールは、自社の関数・API・データベースの処理を、AI が会話の途中で呼べるようにする仕組み
  • 道具は「名前・説明・入力の形・処理」の4つで作り、アプリの中で動く MCP サーバーに入れて渡す
  • 使える道具は2段階（見えるか・確認なしで動くか）で絞れる。書き換える道具は承認を必須にできる

活用例：社内の在庫・顧客データを AI に調べさせる

部署
開発・業務改善
使うもの
Claude Agent SDK・社内API
AIに任せる
必要なデータの照会・結果のまとめ
人が決める
どの処理を道具として渡すか・書き換えを許すか

Claude Agent SDK を使うと、Claude Code と同じ仕組みの AI エージェントを、自社のアプリの中で動かせます。SDK の全体像は Claude Agent SDK とは で解説しました。

この記事はその続きです。公式ドキュメント「Give Claude custom tools」（2026年11月7日確認）にもとづいて、自社の処理を AI に「道具」として渡す方法 を、仕事で使う視点から整理します。

結論：「自社専用の道具」を作って、AI に持たせる

AI エージェントは、ファイルを読む・コマンドを動かす、といった最初から入っている道具で作業します。ただ、自社の在庫データを調べる、社内の仕組みに問い合わせる といったことは、そのままではできません。

そこで、自分の関数を「道具」として定義して渡します。すると AI は会話の途中で必要だと判断したときに、その道具を呼んで結果を受け取り、次の作業に使います。

やりたいことすること
道具を作る名前・説明・入力の形・処理を決める
AI に渡すアプリの中で動く MCP サーバーに入れて、呼び出しに渡す
確認なしで使わせる許可リストに入れる
承認を必須にする・禁止する道具ごとに方針を付ける
エラーを分かりやすく伝えるエラーの印を付けて、自分で書いた説明を返す
画像やファイルを返す結果に画像やリソースのかたまりを入れる
道具が多い必要な時だけ読み込む「ツール検索」を使う
AIが会話の途中で自社の道具を呼び、結果を受け取って作業を続ける流れの図
AIが会話の途中で自社の道具を呼び、結果を受け取って作業を続ける流れの図（イメージ）

道具は4つの部品でできている

道具1つは、次の4つで定義します（Python なら @tool、TypeScript なら tool()）。

部品中身ポイント
名前AI が呼ぶときの識別子重ならないものにする
説明何をする道具かAI はこれを読んで、いつ使うかを決める
入力の形受け取る値と型各項目にも説明を付けられる
処理呼ばれたときに動く関数結果を決まった形で返す

いちばん大事なのは「説明」です。 説明があいまいだと、AI は使うべきときに使わなかったり、違う場面で呼んだりします。「何を受け取り、何を返す道具か」を短く正確に書きます。

処理が返すものは3種類あります。

入力の項目を省略可能にしたいときは、入力の形で「なくてもよい」と宣言し、処理の中で既定の値を入れます。

AI に渡す：MCP サーバーに入れる

作った道具は、SDK の関数（Python は create_sdk_mcp_server、TypeScript は createSdkMcpServer）で MCP サーバーにまとめます。 このサーバーは別のプログラムとして動くのではなく、自分のアプリの中で動きます。

そのサーバーを呼び出しの mcpServers に渡し、確認なしで使わせたい道具を許可リストに入れます。許可リストに書く名前は次の形です。

mcp__{サーバーの名前}__{道具の名前}

サーバーの名前に「.」や空白が入っている場合は、「_」に置き換えて書きます。MCP そのものの考え方は Claude Code の MCP で解説しています。

道具を増やしたいときは、2つ目の道具を定義して、同じサーバーの一覧に足すだけです。

道具の性質を書き添える

道具には、どんな動き方をするかの 目印（注釈） を付けられます。

目印既定意味
readOnlyHintfalse読むだけで何も変えない。読むだけの道具どうしは同時に呼べる
destructiveHinttrue壊す・消すような変更をするかもしれない
idempotentHintfalse同じ入力で何回呼んでも結果が変わらない（参考情報）
openWorldHinttrue外の仕組みにつながる（参考情報）

調べるだけの道具に readOnlyHint を付けると、AI が並べて呼べるので速くなります。ただし 目印はただの宣言で、強制ではありません。 読むだけと書いた道具が実際に書き込めば書き込んでしまうので、中身と合った目印を付けることが大切です。

使える道具を絞る

業務で使うときに一番気になるのは、「AI に何をさせて、何をさせないか」です。SDK では、2段階 で絞れます。

段階意味使う設定
見えるかAI の候補に道具が出るかどうかtools（最初から入っている道具を選ぶ）・名前だけの禁止リスト
確認なしで動くか呼ぼうとしたときに承認が要るか許可リスト・条件つきの禁止ルール

たとえば tools を空にすると、最初から入っている道具が全部消え、自分で作った道具だけを使うエージェント になります。

完全に使わせたくない道具は、候補から外すのが確実です。条件つきの禁止ルールだと道具自体は見えたままなので、AI が試そうとして1回むだにすることがあります。権限の考え方は Claude Code の権限 も参考になります。

書き換える道具は承認を必須にする

TypeScript の SDK では、道具ごとに 「必ず確認する」「必ず断る」という方針 を付けられます（Agent SDK v0.3.301 以降）。

お金や顧客データを書き換えるような道具には「必ず確認する」を付け、人が判断してから動くようにするのが安全です。なお、自動モードや計画モードで使う場合は、その道具に destructiveHint を明示的に付けておかないと、判定の仕組みが承認してしまうことがあると公式は注意しています。

エラーの返し方

道具の処理でエラーが起きても、エージェント自体は止まりません。 違うのは、AI が読むメッセージです。

起きたことAI が受け取るもの
処理の中でエラーをそのまま投げた生のエラーメッセージ
自分でエラーをつかまえて、エラーの印を付けて返した自分で書いた説明

どちらの場合も、AI はやり直したり、別の道具を試したり、失敗を説明したりできます。「どの問い合わせが失敗したか」「代わりに何を試せばよいか」を書いて返す と、AI が次の一手を選びやすくなります。

画像・ファイル・JSON を返す

結果の中身には、文字のほかに次のものを入れられます。

仕事に入れるときの考え方

カスタムツールを作るときは、「調べる道具」から始めて、「変える道具」は後から が安全です。

  1. まず読むだけの道具（在庫の照会・顧客情報の検索など）を作り、readOnlyHint を付ける
  2. 結果をまとめる・報告を書くところまでを AI に任せる
  3. 書き換える道具を足すときは、必ず承認を通す方針を付ける

最後に AI の答えを決まった形の JSON で受け取りたいときは、Claude Agent SDK の構造化出力 を組み合わせます。

まとめ

出典

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール＆コミュニティを運営しています。

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

関連する記事

Claude Agent SDK の構造化出力｜AIの答えをJSONで受け取る2026-11-07・マルチエージェント
Claude Code マーケットプレイスの作り方｜社内配布の手順2026-11-07・マルチエージェント
Claude Code の仕組み｜考えて動いて確かめる流れ2026-11-05・マルチエージェント