ツールの使用（関数の呼び出し）

Claudeは、外部のクライアントサイドのツールや関数と対話することができ、カスタムツールを装備してより幅広いタスクを実行できるようになっています。

Messages APIを使用してClaudeにツールを提供する方法の例を以下に示します：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "指定された場所の現在の天気を取得します",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "都市と州、例：San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "サンフランシスコの天気はどうですか？"
      }
    ]
  }'

​

ツールの使用方法

Claudeでツールを使用するには、以下の手順が含まれます：

1. Claudeにツールとユーザープロンプトを提供する：（APIリクエスト）
   • 使用可能にしたいツールのセットを定義し、名前、説明、入力スキーマを含めます。
   • 「サンフランシスコの天気は？」のように、これらのツールの1つ以上を使用する必要があるかもしれないユーザープロンプトを提供します。
2. Claudeがツールを使用する：（APIレスポンス）
   • Claudeはユーザープロンプトを評価し、利用可能なツールのいずれかがユーザーのクエリやタスクに役立つかどうかを判断します。もしそうであれば、どのツールをどのような入力で使用するかも決定します。
   • Claudeは適切にフォーマットされたツール使用リクエストを構築します。
   • APIレスポンスには、Claudeが外部ツールを使用したいことを示すstop_reasonのtool_useが含まれます。
3. ツール入力を抽出し、コードを実行し、結果を返す：（APIリクエスト）
   • クライアント側で、Claudeのツール使用リクエストからツール名と入力を抽出します。
   • クライアント側で実際のツールコードを実行します。
   • tool_resultコンテンツブロックを含む新しいuserメッセージで会話を続けることで、結果をClaudeに返します。
4. Claudeはツールの結果を使用して応答を作成する：（APIレスポンス）
   • ツールの結果を受け取った後、Claudeはその情報を使用して、元のユーザープロンプトに対する最終的な応答を作成します。

ステップ（3）と（4）はオプションです。一部のワークフローでは、Claudeがツールを使用することがすべての必要な情報であり、ツールの結果をClaudeに返す必要がない場合があります。

​

ツールの指定

ツールは、APIリクエストのtoolsトップレベルパラメータで指定します。各ツール定義には以下が含まれます：

• name：ツールの名前。正規表現^[a-zA-Z0-9_-]{1,64}$に一致する必要があります。
• description：ツールが何をするのか、いつ使用すべきか、どのように動作するかについての詳細なプレーンテキストの説明。
• input_schema：ツールの期待されるパラメータを定義するJSON Schemaオブジェクト。

シンプルなツール定義の例を以下に示します：

{
  "name": "get_weather",
  "description": "指定された場所の現在の天気を取得します",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "都市と州、例：San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "温度の単位。'celsius'または'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

このget_weatherという名前のツールは、必須のlocation文字列と、“celsius”または”fahrenheit”のいずれかでなければならないオプションのunit文字列を持つ入力オブジェクトを期待しています。

​

ツール定義のベストプラクティス

ツールを使用する際にClaudeから最高のパフォーマンスを引き出すには、以下のガイドラインに従ってください：

• 非常に詳細な説明を提供する。 これはツールのパフォーマンスに最も重要な要因です。説明には以下を含むツールのすべての詳細を説明する必要があります：
  • ツールが何をするか
  • いつ使用すべきか（そしていつ使用すべきでないか）
  • 各パラメータが何を意味し、ツールの動作にどのように影響するか
  • ツール名が不明確な場合にツールが返さない情報など、重要な注意点や制限事項 Claudeにツールについてより多くのコンテキストを提供すればするほど、それらをいつどのように使用するかをより適切に判断できるようになります。ツールが複雑な場合は、ツールの説明ごとに少なくとも3〜4文を目指してください。
• 例よりも説明を優先する。 ツールの使用方法の例をその説明や付随するプロンプトに含めることはできますが、ツールの目的とパラメータを明確かつ包括的に説明することの方が重要です。説明を十分に肉付けした後にのみ、例を追加してください。

優れたツールの説明の例を以下に示します：

{
  "name": "get_stock_price",
  "description": "指定されたティッカーシンボルの現在の株価を取得します。ティッカーシンボルは、NYSEやNASDAQなどの主要な米国証券取引所で公開されている企業の有効なシンボルでなければなりません。このツールは、最新の取引価格をUSDで返します。特定の株式の現在または最新の価格について尋ねられたときに使用します。株式や企業に関するその他の情報は提供しません。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "株式のティッカーシンボル。例：Apple Inc.の場合はAAPL"
      }
    },
    "required": ["ticker"]
  }
}

対照的に、以下は貧弱なツールの説明の例です：

{
  "name": "get_stock_price",
  "description": "ティッカーの株価を取得します。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

優れた説明は、ツールが何をするのか、いつ使用するのか、どのようなデータを返すのか、tickerパラメータが何を意味するのかを明確に説明しています。貧弱な説明は短すぎて、ツールの動作や使用法についてClaudeに多くの疑問を残しています。

​

ツール使用とツール結果のコンテンツブロック

Claudeが提供したツールのいずれかを使用することを決定した場合、APIレスポンスにはstop_reasonがtool_useとなり、以下を含む1つ以上のtool_useコンテンツブロックが含まれます：

• id：この特定のツール使用ブロックの一意の識別子。後でツールの結果を照合するために使用されます。
• name：使用されるツールの名前。
• input：ツールのinput_schemaに準拠して、ツールに渡される入力を含むオブジェクト。

tool_useコンテンツブロックを含むAPIレスポンスの例を以下に示します：

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>get_weatherを使用する必要があり、ユーザーはSFを求めています。これはおそらくSan Francisco, CAを指しています。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

ツール使用レスポンスを受け取ったら、以下を行う必要があります：

1. tool_useブロックからname、id、inputを抽出します。
2. そのツール名に対応するコードベースで実際のツールを実行し、ツールのinputを渡します。
3. [オプション] roleがuserの新しいメッセージを送信し、tool_resultタイプと以下の情報を含むcontentブロックを含めることで、会話を続けます：
   • tool_use_id：これが結果であるツール使用リクエストのid。
   • content：文字列（例："content": "15度"）またはネストされたコンテンツブロックのリスト（例："content": [{"type": "text", "text": "15度"}]）としてのツールの結果。これらのコンテンツブロックは、textまたはimageタイプを使用できます。
   • is_error（オプション）：ツールの実行がエラーになった場合はtrueに設定します。

ツールの結果を正常に返す例を以下に示します：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15度"
    }
  ]
}

contentでは画像もサポートされています：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15度"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

エラー結果を返す例を以下に示します：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: 天気サービスのAPIが利用できません（HTTP 500）",
      "is_error": true
    }
  ]
}

ツールの結果を受け取った後、Claudeはその情報を使用して、元のユーザープロン​​プトへの応答の生成を続けます。

空のcontentで非エラーのツール結果を返すこともできます。これは、ツールが出力なしで正常に実行されたことを示します：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

​

ツールの使用を強制する

場合によっては、Claudeがツールを使用せずに回答を提供できると考えていても、ユーザーの質問に答えるために特定のツールを使用するようClaudeに指示したい場合があります。これは、以下のようにtool_choiceフィールドでツールを指定することで実現できます：

tool_choice = {"type": "tool", "name": "get_weather"}

get_weatherツールを使用するようClaudeに明示的に指示することで、使用したいツールを使用するよう促すことができます。この手法は、ツール統合のテストとデバッグに役立つほか、入力に関係なくツールを常に使用する必要があることがわかっている場合に便利です。

また、{"type": "any"}を通じて、提供されたツールのいずれかを使用するようClaudeに指示することもできます。デフォルトのtool_choiceは{"type": "auto"}で、Claudeがツールを使用するかどうかを決定できるようにします。

tool_choiceをanyまたはtoolにすると、ツールの使用を強制するためにアシスタントメッセージが事前に入力されることに注意してください。つまり、明示的に指示された場合でも、モデルはtool_useコンテンツブロックの前に思考の連鎖のtextコンテンツブロックを出力しません。私たちのテストでは、これがパフォーマンスを低下させることはないはずです。（特にOpusで）思考の連鎖を維持しながら、特定のツールを使用するようモデルに要求したい場合は、tool_choiceに{"type": "auto"}（デフォルト）を使用し、userメッセージに明示的な指示を追加できます。例：ロンドンの天気はどうですか？回答ではget_weatherツールを使用してください。

​

JSONの出力

ツールは必ずしもクライアントサイドの関数である必要はありません。提供されたスキーマに従うJSONの出力をモデルに返してほしい場合は、いつでもツールを使用できます。例えば、特定のスキーマを持つrecord_summaryツールを使用するかもしれません。完全な実働例については、ツール使用の例を参照してください。

​

エラー処理

Claudeでツールを使用する際に発生する可能性のあるエラーには、いくつかの異なるタイプがあります：

​

ツールの実行エラー

ツールの実行中にツール自体がエラーをスロー​​した場合（例：天気データの取得時のネットワークエラー）、"is_error": trueとともにエラーメッセージをcontentで返すことができます：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: 天気サービスのAPIが利用できません（HTTP 500）",
      "is_error": true
    }
  ]
}

その後、Claudeはこのエラーをユーザーへの応答に組み込みます。例：「申し訳ありませんが、天気サービスのAPIが利用できないため、現在の天気を取得できませんでした。後でもう一度お試しください。」

​

最大トークン数の超過

Claudeの応答がmax_tokensの制限に達したために切り捨てられ、切り捨てられた応答に不完全なツール使用ブロックが含まれている場合、max_tokensの値を大きくしてリクエストを再試行し、完全なツール使用を取得する必要があります。

​

無効なツールの使用

Claudeによるツールの使用の試みが無効な場合（必須のパラメータが欠落しているなど）、通常、Claudeがツールを正しく使用するための十分な情報がなかったことを意味します。開発中の最善の方法は、ツール定義のdescriptionの値をより詳細にしてリクエストを再試行することです。

ただし、エラーを示すtool_resultで会話を続行することもでき、Claudeは欠落している情報を補完してツールの使用を再試行します：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "エラー：必須の'location'パラメータがありません",
      "is_error": true
    }
  ]
}

​

思考の連鎖を用いたツールの使用

ツールを使用する際、Claudeは「思考の連鎖」、つまり問題を分解し、どのツールを使用するかを決定するために使用する段階的な推論を示すことがよくあります。Claude 3 Opusモデルは、tool_choiceがautoに設定されている場合（これはデフォルト値です。ツールの使用を強制するを参照）、これを行います。SonnetとHaikuはそれを行うようプロンプトを出すことができます。

例えば、「今サンフランシスコの天気はどうですか？そこは今何時ですか？」というプロンプトが与えられた場合、Claudeは次のように応答するかもしれません：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>この質問に答えるために、私は次のようにします：1. get_weatherツールを使用して、サンフランシスコの現在の天気を取得します。2. get_timeツールを使用して、サンフランシスコ（CA）をカバーするAmerica/Los_Angelesタイムゾーンの現在の時刻を取得します。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

この思考の連鎖は、Claudeの推論プロセスに洞察を与え、予期しない動作のデバッグに役立ちます。

Claude 3 Sonnetモデルでは、デフォルトでは思考の連鎖はあまり一般的ではありませんが、ユーザーメッセージやシステムプロンプトに「回答する前に、タグ内で段階的に推論を説明してください。」のようなものを追加することで、Claudeに推論を示すようプロンプトを出すことができます。より詳細な例については、思考の連鎖を用いたツール使用の例を参照してください。

Claudeが思考の連鎖を示すために使用する一般的な規則は<thinking>タグですが、この XMLタグの名前など、正確な形式は時間とともに変更される可能性があることに注意してください。コードでは、思考の連鎖をアシスタントが生成したその他のテキストのように扱い、<thinking>タグの存在や特定の書式設定に依存しないようにする必要があります。

​

ツール使用のベストプラクティスと制限事項

Claudeでツールを使用する際は、以下の制限事項とベストプラクティスに留意してください：

• 複雑なツールの使用にはClaude 3 Opusを、シンプルなツールの場合はHaikuを使用する：Opusは、他のモデルと比較して、最も多くの同時ツールを処理でき、欠落している引数をより適切に検出できます。明示的に与えられていない曖昧なケースや、ツールが必ずしもユーザーリクエストを完了するために必要ではない場合に、明確化を求める可能性が高くなります。Haikuは、（クエリに関連していなくても）ツールをより頻繁に使用しようとするデフォルトの傾向があり、明示的に与えられていないパラメータを推測します。
• ツールの数：すべてのClaude 3モデルは、数百の単純なツールを使用しても90％以上の精度を維持でき、少数の複雑なツールでも同様です。「複雑な」ツールとは、多数のパラメータや複雑なスキーマ（ネストされたオブジェクトなど）を持つパラメータを持つツールを指します。
• 複雑で深くネストされたツール：人間と同様に、Claudeはよりシンプルなインターフェースとシンプルなツールでより適切に動作できます。Claudeがツールを正しく使用するのに苦労している場合は、入力スキーマを深くネストされたJSONオブジェクトから平坦化し、入力の数を減らしてみてください。
• 順次的なツールの使用：Claudeは通常、一度に1つのツールを使用し、そのツールの出力を使用して次のアクションを決定することを好みます。プロンプトとツールを慎重に設計することで、Claudeに並行して複数のツールを使用するようプロンプトを出すことはできますが、これにより、以前のツール使用の結果に依存するパラメータにダミー値が入力される可能性があります。最良の結果を得るには、ワークフローとツールを設計して、Claudeから一連の順次的なツールの使用を引き出し、それに対応するようにしてください。
• リトライ：Claudeのツール使用リクエストが無効であるか、必須のパラメータが欠落している場合、エラー応答を返すとClaudeは通常、欠落している情報を補完してリクエストを再試行します。ただし、2〜3回の失敗の後、Claudeはさらに再試行するのではなく、ユーザーに謝罪を返す可能性があります。
• デバッグ：予期しないツール使用の動作をデバッグする際は、Claudeの思考の連鎖の出力（ある場合）に注目して、なぜそのような選択をしているのかを理解してください。また、特定のツールを使用するようClaudeにプロンプトを出して、期待される動作につながるかどうかを確認することもできます。Claudeがツールを誤用している場合は、ツールの説明とスキーマが明確で明確であることを再確認してください。
• <search_quality_reflection>タグ：検索ツールを使用する際、モデルは<search_quality_reflection> XMLタグと検索品質スコアを応答で返すことがあります。モデルがこれを行うのを止めるには、プロンプトの最後に「返された検索結果の品質について、応答で考察しないでください。」という文を追加します。

これらの制限事項とガイドラインを念頭に置くことで、Claudeの機能を大幅に拡張し、さまざまなタスクに取り組むことができる効果的なツールとエージェントのオーケストレーションを設計できます。

​

ベータ版の履歴（レガシー）

ツールの使用は、2024年5月30日の時点でベータ版ではなく、一般に利用可能になりました。

• tools-2024-05-16
  • 1回のターンで複数のツールの使用が必要なシナリオをより適切に処理するためのOpusのシステムプロンプトの変更
• tools-2024-04-04：ツール使用の初期ベータリリース

​

次のステップ

ツールの使用は、Claudeを外部のデータソースと機能に接続することで、Claudeの機能を拡張するための強力な手法です。適切に設計されたツールのセットを使用することで、基本的な知識だけでは不可能な、さまざまなタスクに取り組むことができます。

いくつかの潜在的な次のステップを以下に示します：

• ツール使用のクックブックを参照する：すぐに実装できるツール使用のコード例のリポジトリを探索します。例：
  • Claudeで計算ツールを使用する
  • クライアントサイドのツールを使用して顧客サービスエージェントを作成する
  • ClaudeとツールでJSON構造体を抽出する
• ツール使用の品質と信頼性を向上させる：ツールの説明とプロンプトを反復し、改善して、Claudeからより信頼性が高く正確なツールの使用を引き出します。
• Claudeの機能を拡張する：
  • さまざまなツールとスキーマを試して、Claudeがさまざまな種類の入力と出力形式をどのように処理するかを確認します。
  • 複数のツールを連鎖させて、複雑なタスクをより単純な一連のステップに分解します。
  • Claudeがアシスタントであるかのように、さまざまなタスクをエンドツーエンドで完了できるエージェントのオーケストレーションを構築します。
  • Claudeにツールを与えてRAG検索を行ったり、Haikuなどのより小さなモデルのサブエージェントを呼び出してタスクを代行させたりするなど、複雑なツール使用アーキテクチャを探ります。

ツールの使用を構築する際は、ぜひフィードバックをお寄せいただき、作成したものを見せていただきたいと思います！開発者向けのDiscordに参加して、プロジェクトを共有し、他の開発者とのヒントやテクニックについて議論してください。

ツールの使用を通じて、Claudeで可能なことの限界に挑戦する皆さまの姿を楽しみにしています。ハッピービルディング！