Claude API の Programmatic Tool Calling — tool 連打のレイテンシとトークン消費を 1/10 まで削減する

ANTHROPIC_API_KEY=

# claude-ptc-starter

Claude API の **Programmatic Tool Calling (PTC)** を最小構成で動かすテンプレート。
[記事本文](https://r43lab.com/blog/claude-programmatic-tool-calling) と対になります。

## Quick start

```bash
bun install
cp .env.example .env   # ANTHROPIC_API_KEY を入れる

# 1) 最小構成 — code_execution + 1 ツールで PTC を有効化
bun run src/basic.ts

# 2) tool_result を受けて handler を回すフルループ
bun run src/full-loop.ts

# 3) 比較 — 通常 tool use と PTC で usage を見比べる
bun run src/standard-vs-ptc.ts

# 4) caller フィールドの読み分け
bun run src/inspect-caller.ts
```

## 鍵となる設定 2 つ

```ts
tools: [
  // (1) code execution を有効化
  { type: "code_execution_20260120", name: "code_execution" },

  // (2) PTC で呼ばせたいツールに allowed_callers を付ける
  {
    name: "query_db",
    description: "...",
    input_schema: { /* ... */ },
    allowed_callers: ["code_execution_20260120"], // ← ここがキモ
  },
]
```

## 対応モデル(2026-04 時点)

- Claude Opus 4.7 / 4.6 / 4.5
- Claude Sonnet 4.6 / 4.5

(Haiku 4.5 は **PTC 非対応**、code_execution_20260120 を持たないモデルでは使えない)

## 守るべきこと

- **PTC 待ちのターンの送信メッセージは `tool_result` ブロックのみ**(`text` 混在は 400)
- assistant 履歴に **`server_tool_use`(コード本体)と `tool_use`(caller=code_execution_20260120)** を両方残す
- `tool_result.tool_use_id` は **PTC 側 `tool_use.id`**(`toolu_...`)を指す
- container は **idle 4.5 分** で破棄。長い tool 実行は短い timeout を切る

## 依存バージョン

`package.json` は **2026-04 時点のスナップショット**。

```bash
bun outdated
bun update
```

## Stack

`@anthropic-ai/sdk` v0.90 · code_execution_20260120

{
  "name": "claude-ptc-starter",
  "private": true,
  "type": "module",
  "scripts": {
    "basic": "bun src/basic.ts",
    "loop": "bun src/full-loop.ts",
    "compare": "bun src/standard-vs-ptc.ts",
    "caller": "bun src/inspect-caller.ts"
  },
  "dependencies": {
    "@anthropic-ai/sdk": "^0.90.0"
  },
  "devDependencies": {
    "@types/bun": "^1.3.0",
    "typescript": "^6.0.3"
  }
}

/**
 * basic.ts — PTC を有効化した最小リクエスト
 *
 * code_execution_20260120 ツールと、allowed_callers を指定したユーザー定義ツール
 * を併せて宣言するだけ。Claude が必要に応じて Python スクリプトを書き、
 * その中から query_database を呼び出してくる。
 *
 * このファイルは「リクエストの形」を確認するためのもので、tool_result を返す
 * ループは含めていない (それは src/full-loop.ts を参照)。
 */
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function main() {
  const response = await client.messages.create({
    model: "claude-opus-4-7",
    max_tokens: 4_096,
    messages: [
      {
        role: "user",
        content:
          "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue.",
      },
    ],
    tools: [
      // (1) Code execution を有効化 — これがないと PTC は成立しない
      { type: "code_execution_20260120", name: "code_execution" },

      // (2) PTC で呼ばせたいユーザー定義ツール
      {
        name: "query_database",
        description:
          "Execute a SQL query against the sales database. Returns a JSON array of rows like [{region: string, revenue: number, ...}].",
        input_schema: {
          type: "object",
          properties: {
            sql: { type: "string", description: "SQL query to execute" },
          },
          required: ["sql"],
        },
        // ★ ここが PTC の肝。
        // ["direct"]                        — Claude が直接呼ぶ (省略時のデフォルト)
        // ["code_execution_20260120"]      — PTC 専用
        // ["direct", "code_execution_20260120"] — 両方
        allowed_callers: ["code_execution_20260120"],
      },
    ],
  });

  console.log(JSON.stringify(response, null, 2));
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * full-loop.ts — PTC のフルループ
 *
 * コンテナ内で実行されている Python スクリプトが query_database を呼び出すと
 * APIから tool_use が返る → 我々が tool_result を返す → スクリプトが再開、
 * の流れを stop_reason: "end_turn" まで回す。
 *
 * 重要: PTC 待ちのターンの送信メッセージは tool_result ブロックのみ
 *       (text 混在は 400 になる)
 */
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// ─── ダミーの DB 実装(本番ではアプリのデータソースに差し替え) ───
async function queryDatabase(sql: string): Promise<unknown[]> {
  // ここでは region 名から決め打ちで返す
  const m = /region\s*=\s*'([A-Za-z]+)'/i.exec(sql);
  const region = m?.[1] ?? "Unknown";
  const seed = region.length;
  return [{ region, revenue: 100_000 * seed, orders: 50 * seed }];
}

// ─── ツール定義(再利用するため抽出) ───
const tools: Anthropic.MessageCreateParams["tools"] = [
  { type: "code_execution_20260120", name: "code_execution" },
  {
    name: "query_database",
    description:
      "Execute a SQL query against the sales database. Returns a JSON array of rows like [{region: string, revenue: number, orders: number}].",
    input_schema: {
      type: "object",
      properties: { sql: { type: "string", description: "SQL query to execute" } },
      required: ["sql"],
    },
    allowed_callers: ["code_execution_20260120"],
  },
];

async function main() {
  const messages: Anthropic.MessageParam[] = [
    {
      role: "user",
      content:
        "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue and how it compares to the others.",
    },
  ];

  // 同じコンテナを再利用したい場合、container を引き回す
  let container: string | undefined = undefined;

  for (let step = 0; step < 16; step++) {
    const response = await client.messages.create({
      model: "claude-opus-4-7",
      max_tokens: 4_096,
      ...(container ? { container } : {}),
      messages,
      tools,
    });
    container = response.container?.id ?? container;

    // assistant の content をそのまま履歴に push (server_tool_use / tool_use を含めて)
    messages.push({ role: "assistant", content: response.content });

    if (response.stop_reason === "end_turn") {
      console.log("\n--- final ---");
      for (const b of response.content) {
        if (b.type === "text") process.stdout.write(b.text);
      }
      console.log("\n\nusage:", response.usage);
      return;
    }

    // PTC 経由 tool_use を集めて、tool_result だけのメッセージを作る
    const ptcCalls = response.content.filter(
      (b): b is Anthropic.ToolUseBlock =>
        b.type === "tool_use" &&
        // @ts-expect-error caller フィールドは現行 SDK 型に未反映の可能性あり
        b.caller?.type === "code_execution_20260120"
    );

    if (ptcCalls.length === 0) {
      console.warn(
        "stop_reason:",
        response.stop_reason,
        "(no PTC calls — direct tool_use または上限到達)"
      );
      break;
    }

    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const call of ptcCalls) {
      if (call.name === "query_database") {
        const sql = (call.input as { sql: string }).sql;
        const rows = await queryDatabase(sql);
        results.push({
          type: "tool_result",
          tool_use_id: call.id,
          content: JSON.stringify(rows),
        });
      } else {
        results.push({
          type: "tool_result",
          tool_use_id: call.id,
          content: `unsupported tool: ${call.name}`,
          is_error: true,
        });
      }
    }

    // ★ 重要: PTC のターンでは text を混ぜない (混ぜると 400)
    messages.push({ role: "user", content: results });
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * inspect-caller.ts — レスポンスの caller フィールドを観察する
 *
 * 同じツールを direct と PTC 両方で呼び分けたいときの確認用。
 * `allowed_callers: ["direct", "code_execution_20260120"]` で両方許可しておき、
 * Claude がどちらで呼んでくるかを caller.type で読み分ける。
 */
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function main() {
  const response = await client.messages.create({
    model: "claude-opus-4-7",
    max_tokens: 2_048,
    messages: [
      {
        role: "user",
        content:
          "Get sales for West region. If revenue > 100k, get sales for the other regions and report top 3.",
      },
    ],
    tools: [
      { type: "code_execution_20260120", name: "code_execution" },
      {
        name: "query_database",
        description: "SQL query. Returns JSON array.",
        input_schema: {
          type: "object",
          properties: { sql: { type: "string" } },
          required: ["sql"],
        },
        // direct と PTC の両方を許可 (公式は片方推奨だが、観察用にあえて両方)
        allowed_callers: ["direct", "code_execution_20260120"],
      },
    ],
  });

  for (const block of response.content) {
    if (block.type === "tool_use") {
      // @ts-expect-error caller フィールドは現行 SDK 型に未反映の可能性あり
      const caller = block.caller;
      console.log(
        `tool_use id=${block.id} name=${block.name} caller=${caller?.type}` +
          (caller?.tool_id ? ` (from ${caller.tool_id})` : "")
      );
    } else if (block.type === "server_tool_use") {
      console.log(`server_tool_use id=${block.id} name=${block.name}`);
    } else if (block.type === "text") {
      console.log("text:", block.text);
    }
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * standard-vs-ptc.ts — 同じ要求を「通常 tool use」と「PTC」で 2 回投げて usage を比較
 *
 * 5 region の売上集計を、
 *   (a) 通常: tool_use → tool_result × 5 (Claude を再サンプリングしながら)
 *   (b) PTC: code_execution の中でループ → 集約後の最終 stdout のみ
 * の 2 通りで実行し、input/output token と turn 数を比較する。
 *
 * 観点: PTC では PTC 経由 tool_result の中身が input にカウントされない (公式 Note)
 */
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function queryDb(sql: string) {
  const m = /'([A-Za-z]+)'/.exec(sql);
  const region = m?.[1] ?? "Unknown";
  const seed = region.length;
  return JSON.stringify([{ region, revenue: 100_000 * seed }]);
}

const userQ =
  "Query sales for West, East, Central, North, and South regions, then return the region with the highest revenue.";

// ─── (a) 通常 tool use ───
async function runStandard() {
  const tools: Anthropic.MessageCreateParams["tools"] = [
    {
      name: "query_database",
      description: "Run SQL on the sales DB. Returns JSON array.",
      input_schema: {
        type: "object",
        properties: { sql: { type: "string" } },
        required: ["sql"],
      },
    },
  ];

  const messages: Anthropic.MessageParam[] = [{ role: "user", content: userQ }];
  let totalIn = 0;
  let totalOut = 0;
  let turns = 0;

  for (let step = 0; step < 16; step++) {
    const r = await client.messages.create({
      model: "claude-opus-4-7",
      max_tokens: 2_048,
      messages,
      tools,
    });
    turns++;
    totalIn += r.usage.input_tokens;
    totalOut += r.usage.output_tokens;
    messages.push({ role: "assistant", content: r.content });

    if (r.stop_reason === "end_turn") break;

    const calls = r.content.filter(
      (b): b is Anthropic.ToolUseBlock => b.type === "tool_use"
    );
    if (calls.length === 0) break;

    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const c of calls) {
      const sql = (c.input as { sql: string }).sql;
      results.push({
        type: "tool_result",
        tool_use_id: c.id,
        content: await queryDb(sql),
      });
    }
    messages.push({ role: "user", content: results });
  }

  return { mode: "standard", turns, input: totalIn, output: totalOut };
}

// ─── (b) PTC ───
async function runPtc() {
  const tools: Anthropic.MessageCreateParams["tools"] = [
    { type: "code_execution_20260120", name: "code_execution" },
    {
      name: "query_database",
      description: "Run SQL on the sales DB. Returns JSON array.",
      input_schema: {
        type: "object",
        properties: { sql: { type: "string" } },
        required: ["sql"],
      },
      allowed_callers: ["code_execution_20260120"],
    },
  ];

  const messages: Anthropic.MessageParam[] = [{ role: "user", content: userQ }];
  let totalIn = 0;
  let totalOut = 0;
  let turns = 0;
  let container: string | undefined;

  for (let step = 0; step < 16; step++) {
    const r = await client.messages.create({
      model: "claude-opus-4-7",
      max_tokens: 2_048,
      ...(container ? { container } : {}),
      messages,
      tools,
    });
    turns++;
    totalIn += r.usage.input_tokens;
    totalOut += r.usage.output_tokens;
    container = r.container?.id ?? container;
    messages.push({ role: "assistant", content: r.content });

    if (r.stop_reason === "end_turn") break;

    const calls = r.content.filter(
      (b): b is Anthropic.ToolUseBlock =>
        b.type === "tool_use" &&
        // @ts-expect-error
        b.caller?.type === "code_execution_20260120"
    );
    if (calls.length === 0) break;

    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const c of calls) {
      const sql = (c.input as { sql: string }).sql;
      results.push({
        type: "tool_result",
        tool_use_id: c.id,
        content: await queryDb(sql),
      });
    }
    messages.push({ role: "user", content: results });
  }

  return { mode: "ptc", turns, input: totalIn, output: totalOut };
}

async function main() {
  const a = await runStandard();
  const b = await runPtc();
  console.table([a, b]);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022"],
    "types": ["bun"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src/**/*"]
}