【AI】Claude APIのProgrammatic Tool Callingを使う方法

当ページのリンクには広告が含まれています。
いずみ

こんな悩みを解決できる記事を書きました!

僕は現役フリーランスエンジニア(歴年)で、資格は個保有しています。

Claude APIで多数のツールを呼ぶエージェントのトークン消費を抑えたい」とお考えではありませんか?

複数のツールを順番に呼ぶ処理を組んでいて、モデルとの往復のたびにコンテキストが膨らんで困っている方へ。

Programmatic Tool Callingを使えば、Claudeがコード実行コンテナ内でツールを関数として呼び出し、中間結果をモデルのコンテキストに載せずに処理できます

いずみ

仕組みと手順をサクッと解説します。

ということで、本記事ではClaude APIのProgrammatic Tool Callingを使う方法を解説します。

いずみ

すぐ読み終わるので、ぜひ最後まで読んでくださいませ。

スクロールできます
【当サイト】おすすめフリーランスエージェント3選
エージェント評価ポイント公式サイト
レバテックフリーランス

5.0
業界最大級のエージェント。
高単価案件が豊富。
公式
Midworks

4.8
満足度調査で
3年連続3冠を達成。
公式
ITプロパートナーズ

4.6
週2〜3向けの案件が豊富。公式
執筆者/監修者
  • フリーランスエンジニア(保有資格個、企業と直接契約
  • ブログ・アフィリエイト歴7年(2018年〜)
  • ブランドせどりで月利50万円⇨脱サラ
  • 投資(仮想通貨・FX)歴7年(2018年〜)
  • X(旧Twitter)フォロワー約1,900人
  • 運営者情報はこちら
いずみです
目次

【AI】Claude APIのProgrammatic Tool Callingを使う方法

早速ですが、Claude APIのProgrammatic Tool Callingを使う方法を解説します。

Programmatic Tool Callingとは

通常のtool useでは、ツールを1回呼ぶたびにモデルへ往復し、ツールの実行結果がすべてコンテキストに積み上がります。

Programmatic Tool Callingでは、ClaudeがPythonコードを書き、書いたコードの中からツールを関数として呼び出します。

コードはcode execution(コード実行ツール)のサンドボックスコンテナ内で動きます。

ツールの結果は実行中のコードに渡され、モデルのコンテキストには最終的な出力だけが入ります。

Anthropicの社内評価では、75個のツールを持つプロジェクト管理エージェントのベンチマークで、課金対象の入力トークンが約38%減り、タスクの精度は変わらなかったと報告されています。

いずみ

ツールの往復をコード側でまとめてしまう、というアイデアですね。

使う前の準備

まずは、Programmatic Tool Callingを使う準備をします。

STEP
anthropicライブラリを用意する

Python用の公式SDKをインストールします。

pip install anthropic

APIキーは環境変数ANTHROPIC_API_KEY に設定しておきます。

STEP
対応モデルとツールバージョンを確認する

Programmatic Tool Callingには、コード実行ツールのcode_execution_20260120 以降のバージョンが必要です。

Claude Opus 5やClaude Sonnet 5などが対応しています。

Claude Haiku 4.5はcode_execution_20260120 を受け付けますが、Programmatic Tool Callingには対応していません。

実装(コード付き)

簡単に実装してみます。

STEP
ツール定義にallowed_callersを付ける

tools配列にcode executionツールと自作ツールを渡し、自作ツールにallowed_callers を追加します。

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "West、East、Centralの売上を調べて、売上が最も高いリージョンを教えて",
        }
    ],
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "売上DBにSQLを実行する。行のリストをJSON文字列で返す。",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "実行するSQL"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

allowed_callerscode_execution_20260120 を指定したツールが、コード実行コンテナ内から呼べるツールになります。

いずみ

出力フォーマット(JSONの構造やフィールド)をdescriptionに具体的に書くほど、Claudeがコード側で結果を扱いやすくなります。

STEP
コードからのツール呼び出しに応答する

Claudeがコードを書いてツールを呼ぶと、レスポンスはstop_reasontool_use になり、container のIDと、caller がコード実行を指すtool_use ブロックを含みます。

ツールを実行した結果をtool_result として返します。

tool_use = next(b for b in response.content if b.type == "tool_use")
rows = run_sql(tool_use.input["sql"])  # 自前のDB実行関数

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    container=response.container.id,  # 同じコンテナを再利用
    messages=[
        {"role": "user", "content": "West、East、Centralの売上を調べて、売上が最も高いリージョンを教えて"},
        {"role": "assistant", "content": response.content},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use.id,
                    "content": rows,  # JSON文字列
                }
            ],
        },
    ],
    tools=tools,  # 初回とまったく同じtools配列を渡す
)

応答リクエストではcontainer のIDが必須で、tools配列は初回と同じものを送ります。

保留中の呼び出しがある間、結果を返すメッセージにはtool_result ブロックだけを入れます(テキストは混ぜられません)。

STEP
最終レスポンスを受け取る

コード実行が終わると、code_execution_tool_resultstdout と、Claudeの回答テキストが返ります。

コード実行が完了するとstop_reasonend_turn になります。

途中でツールを何回呼んでいても、モデルのコンテキストに載るのは最終出力だけです。

いずみ

3リージョン程度なら効果は小さいですが、数十件のルックアップになるとトークン差がはっきり出ます。

向いているケースと制限

Programmatic Tool Callingが向いているのは、次のようなワークロードです。

  • 多数の項目に対するファンアウト処理(50個のエンドポイント確認、20件のレコード検索など)
  • 大きなツール結果を、フィルタ・集約・要約してからコンテキストに載せたい場合
  • 反復的なクエリと結果の絞り込みが中心になるエージェント検索

逆に、各呼び出しがClaudeの推論結果に依存する完全な逐次処理や、呼び出し回数もレスポンスも小さい処理では、コンテナ起動のオーバーヘッドが上回ることがあります。

制限として、MCPコネクタ経由のツール、computer useツール、browser useツールはProgrammatic Tool Callingでは呼び出せません。

strict: true を付けた構造化出力のツールも非対応です。

コードへ渡せるtool_result の中身は、文字列またはテキストブロックだけで、画像やドキュメントは受け付けられません。

いずみ

迷ったら、代表的なトラフィックでallowed_callersのあり・なしを比べて、課金トークンを測ってから広げるのが安全です。

スクロールできます
【当サイト】おすすめフリーランスエージェント3選
エージェント評価ポイント公式サイト
レバテックフリーランス

5.0
業界最大級のエージェント。
高単価案件が豊富。
公式
Midworks

4.8
満足度調査で
3年連続3冠を達成。
公式
ITプロパートナーズ

4.6
週2〜3向けの案件が豊富。公式

【厳選】フリーランスエンジニアにおすすめなエージェント3選

フリーランスエンジニアになるにはエージェントから案件をもらう必要があります。

僕が実際に利用しているおすすめエージェントを紹介しますね。

いずみ

エージェントは必ず複数登録してください。

担当者によっては「全然案件紹介してくれない…」みたいなこともあるので…

僕は実際に5つのエージェントを使い回していますよ。

フリーランスを始めるなら「

案件数マージン率単価
約88,000件非公開
初心者福利厚生申し込み
無料
Good Point
  • 業界最大級の案件数。
  • 業界トップクラスの高単価報酬、低マージン(平均年収862万円)。
  • 案件参画中のフォローの充実。

※詳細は「【業界最大手】レバテックフリーランスとは?メリットや利用手順を解説!」を参照。

は業界最大手のフリーランスエージェントです。

とにかく案件数が多いので、とりあえず登録しておけば間違いないエージェントです!

いずみ

僕もはじめてフリーランスの案件を貰ったのはです。

保有している案件数が多いので、業務経験がなくても何かしらの案件は紹介してもらえますよ(僕はJavaの経験3年でも案件を貰えました)。

手厚い保障を重視したいなら「

案件数マージン率単価
約10,000件非公開
初心者福利厚生申し込み
無料
Good Point
  • 手厚い保障で正社員並みの安心感。
  • 還元率60%超え&単価公開でクリアな契約。
  • 給与保障制度(審査あり)。

は手厚い保障が特徴のフリーランスエージェントです。

フリーランスを目指しているけど不安な方や保障を重視したい方におすすめです。

いずみ

僕も何度か案件を紹介してもらいました。

自分のスキルに合った案件を紹介してもらえましたし、電話のやり取りも非常に丁寧でした。

週2〜3日の案件探しなら「

案件数マージン率単価
約5,000件非公開
初心者福利厚生申し込み
経験者向け無料
Good Point
  • IT案件に特化したフリーランスエージェント。
  • 週2〜3日の案件が豊富。
  • リモート案件が多く、直エンドなので単価も高い。

※詳細は「【週2・3案件】ITプロパートナーズとは?メリットや利用手順を解説!」を参照。

はIT案件に特化したフリーランスエージェントです。

週2〜3日から参画できる案件が豊富なので、起業したい人にもおすすめです。

いずみ

週2〜3日の案件はある程度スキルがないと紹介してもらえない印象です。

とはいえ、週5の案件ももちろんありますし、僕が利用した時は迅速・丁寧に対応していただきました!

よくある質問

通常のtool useと何が違いますか?

通常のtool useは、ツールを1回呼ぶたびにモデルへ往復し、結果がコンテキストに積み上がります。

Programmatic Tool Callingでは、Claudeが書いたコードの中からツールを呼び、中間結果はコンテキストに入りません。

どのモデルで使えますか?

コード実行ツールのcode_execution_20260120 以降に対応したモデルで使えます。

Claude Opus 5やClaude Sonnet 5などが対象で、Claude Haiku 4.5はコード実行は使えるものの、Programmatic Tool Callingには対応していません。

トークン課金はどうなりますか?

コード内から呼んだツールの結果は、入力・出力トークンに計上されません。

最終的なコード実行結果とClaudeの応答だけが課金対象になります。

結果を返すメッセージにテキストを添えてもいいですか?

保留中のProgrammatic Tool Callingがある間は、結果を返すメッセージにtool_result ブロックだけを入れる必要があります。

テキストブロックを混ぜるとエラーになります。

まとめ

今回は、Claude APIのProgrammatic Tool Callingを使う方法について解説しました。

以下が本記事のまとめになります。

まとめ
  • Programmatic Tool Callingは、Claudeが書いたコードの中からツールを関数として呼ぶ仕組み。
  • コード実行ツールのcode_execution_20260120 以降が必要で、対応モデルはClaude Opus 5やClaude Sonnet 5など。
  • 自作ツールにallowed_callers を付けると、コンテナ内から呼べるようになる。
  • 中間結果はコンテキストに載らないため、多数のツール呼び出しでトークンを節約できる。
まとめ
いずみ

最後までお読みいただき、ありがとうございました!

スクロールできます
【当サイト】おすすめフリーランスエージェント3選
エージェント評価ポイント公式サイト
レバテックフリーランス

5.0
業界最大級のエージェント。
高単価案件が豊富。
公式
Midworks

4.8
満足度調査で
3年連続3冠を達成。
公式
ITプロパートナーズ

4.6
週2〜3向けの案件が豊富。公式
  • クソおすすめ本
¥4,480 (2024/06/01 23:28時点 | Amazon調べ)
いずみ

海外のエンジニアがどういった思考で働いているかが理解できます。

海外に行く気はないけど海外エンジニアの動向が気になる雑魚エンジニアにおすすめです(本当におすすめな本しか紹介しないのでご安心を)。

この記事が気に入ったら
フォローしてね!

シェアしてね!
  • URLをコピーしました!
目次