Skip to main content
カスタムツールは Agent SDK を拡張し、Claude が会話中に呼び出せる独自の関数を定義できるようにします。SDK のインプロセス MCP サーバーを使用すると、Claude にデータベース、外部 API、ドメイン固有のロジック、またはアプリケーションが必要とするその他の機能へのアクセスを提供できます。 このガイドでは、入力スキーマとハンドラーを使用してツールを定義し、それらを MCP サーバーにバンドルし、query に渡し、Claude がアクセスできるツールを制御する方法について説明します。また、エラーハンドリング、ツール注釈、および画像などの非テキストコンテンツを返す方法についても説明します。

クイックリファレンス

カスタムツールを作成する

ツールは 4 つの部分で定義され、TypeScript の tool() ヘルパーまたは Python の @tool デコレーターに引数として渡されます。
  • 名前: Claude がツールを呼び出すために使用する一意の識別子。
  • 説明: ツールが何をするかを説明します。Claude はこれを読んで、ツールをいつ呼び出すかを決定します。
  • 入力スキーマ: Claude が提供する必要がある引数。TypeScript では常に Zod スキーマであり、ハンドラーの args は自動的に型付けされます。Python では {"latitude": float} のような名前から型へのマッピングであり、SDK が JSON Schema に変換します。Python デコレーターは、列挙型、範囲、オプションフィールド、またはネストされたオブジェクトが必要な場合、完全な JSON Schema 辞書も受け入れます。
  • ハンドラー: Claude がツールを呼び出すときに実行される非同期関数。検証された引数を受け取り、以下を含むオブジェクトを返す必要があります。
    • content(必須):結果ブロックの配列。各ブロックは "text""image""audio""resource"、または "resource_link"type を持ちます。非テキストブロックについては、画像とリソースを返すを参照してください。
    • structuredContent(オプション):結果をマシン可読データとして保持する JSON オブジェクト。content と共に返されます。構造化データを返すを参照してください。
    • isError(オプション):ツール障害を通知するために true に設定し、Claude が対応できるようにします。エラーを処理するを参照してください。
ツールを定義した後、createSdkMcpServer(TypeScript)または create_sdk_mcp_server(Python)でサーバーにラップします。サーバーはアプリケーション内でインプロセスで実行され、別のプロセスとしては実行されません。

天気ツールの例

この例は get_temperature ツールを定義し、MCP サーバーにラップします。ツールのセットアップのみを行います。query に渡して実行するには、以下の カスタムツールを呼び出すを参照してください。