Claude API Programmatic Tool Calling（PTC）実践ガイド — ラウンドトリップ激減・トークン最大85%削減を実測で検証

[リクエスト1] ユーザーメッセージ送信
  ← tool_use: web_search
[リクエスト2] tool_result + 会話履歴を再送
  ← tool_use: web_fetch
[リクエスト3] tool_result + 会話履歴を再送（さらに膨張）
  ← tool_use: web_fetch
[リクエスト4] tool_result + 会話履歴を再送（最大サイズ）
  ← 最終回答

[リクエスト1] ユーザーメッセージ送信
  ← Claudeがコンテナ内でPythonコードを実行
    → コード内でweb_search呼び出し → 結果取得
    → コード内でweb_fetch呼び出し → 結果取得
    → コード内で集計・分析
  ← 最終回答（1往復で完了）

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const tools: Anthropic.Tool[] = [
  { type: "web_search_20260209", name: "web_search", max_uses: 3 },
  { type: "web_fetch_20260209", name: "web_fetch", max_uses: 3 },
];

async function traditionalApproach(query: string) {
  let messages: Anthropic.MessageParam[] = [
    { role: "user", content: query },
  ];
  let totalInputTokens = 0;
  let totalOutputTokens = 0;
  let roundTrips = 0;

  while (true) {
    roundTrips++;
    const response = await client.messages.create({
      model: "claude-sonnet-4-6-20260320",
      max_tokens: 4096,
      tools,
      messages,
    });

    totalInputTokens += response.usage.input_tokens;
    totalOutputTokens += response.usage.output_tokens;

    if (response.stop_reason === "end_turn") {
      return { totalInputTokens, totalOutputTokens, roundTrips, response };
    }

    // tool_useブロックを処理してtool_resultを返す
    const assistantContent = response.content;
    const toolResults: Anthropic.MessageParam = {
      role: "user",
      content: assistantContent
        .filter((b): b is Anthropic.ToolUseBlock => b.type === "tool_use")
        .map((toolUse) => ({
          type: "tool_result" as const,
          tool_use_id: toolUse.id,
          content: "/* サーバーツールのため自動処理 */",
        })),
    };

    messages = [
      ...messages,
      { role: "assistant", content: assistantContent },
      toolResults,
    ];
  }
}

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const tools: Anthropic.Tool[] = [
  { type: "code_execution_20260120", name: "code_execution" },
  {
    type: "web_search_20260209",
    name: "web_search",
    max_uses: 3,
    allowed_callers: ["code_execution_20260120"],
  },
  {
    type: "web_fetch_20260209",
    name: "web_fetch",
    max_uses: 3,
    allowed_callers: ["code_execution_20260120"],
  },
];

async function ptcApproach(query: string) {
  const start = Date.now();

  const response = await client.messages.create({
    model: "claude-sonnet-4-6-20260320",
    max_tokens: 16384,
    tools,
    messages: [{ role: "user", content: query }],
  });

  return {
    inputTokens: response.usage.input_tokens,
    outputTokens: response.usage.output_tokens,
    roundTrips: 1,
    elapsed: Date.now() - start,
    response,
  };
}

// パターン1: PTC専用（推奨）
{ allowed_callers: ["code_execution_20260120"] }

// パターン2: 従来方式専用（明示的に制限したい場合）
{ allowed_callers: ["direct"] }

// パターン3: 両方対応（移行期間用）
{ allowed_callers: ["direct", "code_execution_20260120"] }

const tools = [
  { type: "code_execution_20260120", name: "code_execution" },
  {
    type: "web_search_20260209",
    name: "web_search",
    max_uses: 5,
    allowed_callers: ["code_execution_20260120"],
  },
  {
    type: "web_fetch_20260209",
    name: "web_fetch",
    max_uses: 5,
    allowed_callers: ["code_execution_20260120"],
  },
  {
    name: "save_report",
    description: "分析レポートをDBに保存する",
    input_schema: {
      type: "object",
      properties: {
        title: { type: "string" },
        content: { type: "string" },
        sources: { type: "array", items: { type: "string" } },
      },
      required: ["title", "content"],
    },
    allowed_callers: ["code_execution_20260120"],
  },
];

// レスポンスからコンテナ情報を取得
for (const block of response.content) {
  if (block.type === "code_execution_result") {
    console.log(`Container ID: ${block.container_id}`);
    console.log(`Expires at: ${block.expires_at}`);
  }
}

const tools = [
  { type: "code_execution_20260120", name: "code_execution" },
  {
    name: "process_batch",
    description: "バッチ処理を実行し中間結果を返す。1バッチ10件以内に分割すること",
    input_schema: {
      type: "object",
      properties: {
        batch_ids: { type: "array", items: { type: "string" } },
      },
      required: ["batch_ids"],
    },
    allowed_callers: ["code_execution_20260120"],
  },
];

// NG: code_executionツールがない
const tools = [
  {
    name: "my_tool",
    allowed_callers: ["code_execution_20260120"],
    // ...
  },
];

// OK: code_executionツールを必ず含める
const tools = [
  { type: "code_execution_20260120", name: "code_execution" },
  {
    name: "my_tool",
    allowed_callers: ["code_execution_20260120"],
    // ...
  },
];