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

ツール使用のパブリックベータ版

ツール使用機能がパブリックベータ版としてリリースされたことをお知らせします!この機能を利用するには、APIリクエストに anthropic-beta: tools-2024-05-16 ヘッダーを含める必要があります。

ストリーミングツール使用の強制画像がサポートされるようになりました!詳細はベータ版の履歴をご覧ください。

今後数週間でこのオープンベータ版を改良していく予定ですので、皆様からのフィードバックをお待ちしております。アイデアや提案は、このフォームからお寄せください。

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" \
  -H "anthropic-beta: tools-2024-05-16" \
  -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": "サンフランシスコの天気はどうですか?"
      }
    ]
  }'

ベータ期間中は以下の点にご注意ください。

  • この機能は本番環境で使用可能ですが、最終リリースまでに複数のベータ版が導入される可能性があります。
  • ツール使用機能は、Vertex AIやAWS Bedrockなどのサードパーティのプラットフォームではまだ利用できませんが、近日中に対応予定です。現時点でVertex AIやAWS Bedrockでツール使用を行う方法については、レガシーツール使用を参照してください。

ツール使用の仕組み

Claudeでツールを使用するには、以下の手順が必要です。

  1. Claudeにツールとユーザープロンプトを提供する: (APIリクエスト)
    • Claudeにアクセスさせたいツールのセットを定義します。名前、説明、入力スキーマを含みます。
    • 「サンフランシスコの天気は?」のように、これらのツールの1つ以上を使用する必要があるユーザープロンプトを提供します。
  2. Claudeがツールを使用する: (APIレスポンス)
    • Claudeはユーザープロンプトを評価し、利用可能なツールがユーザーのクエリやタスクに役立つかどうかを判断します。役立つ場合は、どのツールをどのような入力で使用するかも決定します。
    • Claudeは適切な形式のツール使用リクエストを構築します。
    • APIレスポンスの stop_reasontool_use となり、Claudeが外部ツールを使用したいことを示します。
  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 オブジェクト。

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

JSON
{
  "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文を目安とし、ツールが複雑な場合はさらに長くしてください。
  • 例よりも説明を優先する: ツールの使用例をその説明や付随するプロンプトに含めることはできますが、ツールの目的とパラメータを明確かつ包括的に説明することの方が重要です。説明を十分に肉付けした後に、例を追加するようにしてください。

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

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

対照的に、不十分なツールの説明の例を以下に示します。

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

優れた説明は、ツールの機能、使用すべきタイミング、返されるデータ、ticker パラメータの意味を明確に説明しています。不十分な説明は短すぎて、ツールの動作や使用法についてClaude に多くの疑問を残します。


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

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

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

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

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>get_weatherを使用する必要があります。ユーザーはSFを求めていますが、これはおそらくサンフランシスコ、カリフォルニア州のことでしょう。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

ツール使用のレスポンスを受け取ったら、以下の手順を実行してください。

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

成功したツール結果を返す例を以下に示します。

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

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

JSON
{
  "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/4AAQSkZJRgABAQAAAQABAAD...",
          }
        }
      ]
    }
  ]
}

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

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

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

出力のない成功したツール結果を返すこともできます。

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

他のAPIとの違い

ツールの使用をモデルの主な出力とは別に返したり、特別な目的の tool または function メッセージの role を使用したりする他のAPIに慣れている方もいるかもしれません。

対照的に、AnthropicのモデルとAPIは、交互に行われる user メッセージと assistant メッセージを中心に構築されており、各メッセージは textimagetool_usetool_result の豊富なコンテンツブロックの配列になっています。

このフォーマットでは、user メッセージはクライアントサイドとユーザー/人間が管理するコンテンツを表し、assistant メッセージはサーバーサイドとAIが管理するコンテンツを表します。そのため、特別な toolfunction メッセージの role はなく、tool_result ブロックは user メッセージの content に含める必要があります。


ツール使用の強制

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

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

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

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

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


JSONの出力

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


エラー処理

Claudeでツールを使用する際に発生する可能性のあるエラーには、いくつかの種類があります。

ツール実行エラー

ツールの実行中にエラーが発生した場合(例:天気データの取得時のネットワークエラー)、エラーメッセージを content"is_error": true と一緒に返すことができます。

JSON
{
  "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は欠落している情報を補完してツールを再度使用しようとします。

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

思考の連鎖を伴うツール使用

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

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

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

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

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

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


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

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

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

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


ベータ版の履歴

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

次のステップ

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

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

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

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

ツール使用を使ってClaude の可能性の限界に挑戦する皆様の取り組みを楽しみにしています。ハッピービルディング!