0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Agent SDK カスタムツール仕様ガイド — ツール定義からエラー処理・結果ブロックまで

0
Posted at

Claude Agent SDK では、自分で書いた関数を「ツール」として Claude に渡し、エージェントループの中から呼ばせることができます。本稿は公式ドキュメント(Custom Tools)の検証済み記述に基づき、ツールの定義方法・登録・許可設定・結果の返し方・言語ごとの差異を仕様ベースで整理します(検証日: 2026-08-20 JST)。すべての技術的主張は末尾 References の出典に対応します。

ツール定義の 4 要素

ツールは 4 つの構成要素で定義され、TypeScript では tool() ヘルパー、Python では @tool デコレータに渡されます [1]。

A tool is defined by four parts

具体的には、ツールを呼ぶときに Claude が使う一意の名前(Name)、何をするツールかを説明する記述(Description)、入力スキーマ、そしてハンドラの 4 つです。

入力スキーマ — TypeScript と Python の差

TypeScript では入力スキーマに常に Zod スキーマを使います。ハンドラの引数はそのスキーマから自動的に型付けされます [1]。

In TypeScript this is always a Zod schema

Python では扱いが異なります。dict スキーマはすべてのキーを必須として扱います [1]。

the dict schema treats every key as required

したがってオプションパラメータを表現したい場合は、そのパラメータをスキーマから外し、説明文で言及し、ハンドラ内で args.get() を使って読み取ります [1]。

インプロセスサーバーとしての登録

定義したツールは createSdkMcpServer(Python では create_sdk_mcp_server)でラップします。このサーバーはアプリケーション内でインプロセス動作し、別プロセスとして起動しません [1]。

The server runs in-process inside your application, not as a separate process.

完全修飾名

mcpServers に登録する際のキーが、各ツールの完全修飾名 mcp__{server_name}__{tool_name} における {server_name} セグメントになります [1]。

becomes the {server_name} segment in each tool's fully qualified name

パーミッションと allowedTools

ツールの完全修飾名を allowedTools に列挙すると、そのツールはパーミッションプロンプトなしで実行されます [1]。

List that name in allowedTools so the tool runs without a permission prompt.

同一サーバー上の全ツールを一括で許可するにはワイルドカードが使えます [1]。

use the wildcard mcp__weather__* to cover every tool the server exposes

ツールサーチ(デフォルト有効)

ツールサーチはデフォルトで有効で、SDK MCP ツールを遅延ロードします [1]。Claude はコンパクトなリストで各ツール名を確認し、必要になったときにフルスキーマをオンデマンドで読み込みます。

Tool search is on by default and defers SDK MCP tools

ツールアノテーション

アノテーションはツールの振る舞いに関するメタデータです。readOnlyHint のデフォルトは false で、環境を変更しないことを示します [1]。この値は、他の読み取り専用ツールとの並列呼び出し可否を制御します。

Controls whether the tool can be called in parallel with other read-only tools.

destructiveHint のデフォルトは true で、破壊的更新を行いうることを示しますが、情報提供のみで強制力はありません [1]。

destructiveHint true Tool may perform destructive updates. Informational only.

なお idempotentHint および openWorldHint のデフォルト値については、本稿の検証範囲では確認しておらず、別途公式ドキュメントでの確認が必要です。

重要なのは、アノテーションはメタデータであって強制ではない点です [1]。

Annotations are metadata, not enforcement.

つまり readOnlyHint: true を付けたツールでも、ハンドラの実装次第でディスクへ書き込むことは可能です。

エラー処理

ハンドラのエラーはエージェントループを止めません [1]。SDK のインプロセス MCP サーバーが、キャッチされない例外を捕捉してエラー結果に変換します。

A handler error doesn't stop the agent loop.

ツールの失敗を Claude に明示的に伝えたい場合は、結果に isError(Python では is_error)を設定します [1]。

set to true to signal a tool failure so Claude can react to it.

結果ブロック — 画像・音声・リソースリンク

画像ブロックの data フィールドは base64 エンコードされたバイト列で、生の base64 のみを受け付けます [1]。

Raw base64 only, no data:image/...;base64, prefix

音声ブロックの扱いは言語で異なります。TypeScript では SDK が音声ブロックをディスクに保存し、Claude は保存先のファイルパスを含むテキストブロックを受け取ります [1]。Python では音声ブロックはツール結果からドロップされ、警告がログに記録されます [1]。

the SDK drops audio blocks from the tool result and logs a warning.

リソースリンクブロックは、リンクの name・URI・description を含むテキストブロックに変換されます [1]。

The SDK converts resource link blocks to a text block containing the link's name, URI, and description.

structuredContent

structuredContent は結果に付与できるオプションの JSON オブジェクトで、content 配列とは独立しています。テキストや画像からパースさせるのでなく、正確なフィールドとして値を Claude に読ませるために使います [1]。

Use it to return raw values that Claude can read as exact fields

structuredContent を設定すると、content 内のテキストブロックは構造化データの複製とみなされ、転送されません [1]。

Text blocks in content are not forwarded

Python では制約があります。@tool デコレータはハンドラの戻り値から content と is_error のみを転送します [1]。

The Python @tool decorator forwards only content and is_error from the handler's return dict.

そのため Python から structuredContent を返すには、インプロセス SDK サーバーではなくスタンドアロンの MCP サーバーを動かす必要があります。

ビルトインツールの制御

tools オプションにビルトインツール名を列挙すると、列挙されたものだけが Claude のコンテキストに残り、未列挙のビルトインは除去されます(MCP ツールは影響を受けません)[1]。

Only the listed built-ins are in Claude's context. Unlisted built-ins are removed.

一方 disallowedTools にスコープ付きルール(例: "Bash(rm *)")を指定すると、ツールはコンテキストに残したまま、一致する呼び出しだけを拒否します [1]。

leaves the tool in context and denies only matching calls

References

[1] https://code.claude.com/docs/en/agent-sdk/custom-tools

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?