Anthropic SDK Tool Helpers実践ガイド — betaZodToolとtoolRunnerで型安全なツール呼び出しを最小コードで実現する

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

const client = new Anthropic();

const tools: Anthropic.Tool[] = [
  {
    name: "get_weather",
    description: "指定都市の現在の天気を取得する",
    input_schema: {
      type: "object" as const,
      properties: {
        city: { type: "string", description: "都市名" },
        unit: { type: "string", enum: ["celsius", "fahrenheit"] },
      },
      required: ["city"],
    },
  },
  {
    name: "search_cities",
    description: "キーワードで都市を検索する",
    input_schema: {
      type: "object" as const,
      properties: {
        query: { type: "string", description: "検索キーワード" },
        limit: { type: "number", description: "最大件数" },
      },
      required: ["query"],
    },
  },
];

async function run(userMessage: string) {
  let messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  while (true) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-5-20250929",
      max_tokens: 1024,
      tools,
      messages,
    });

    if (response.stop_reason === "end_turn") {
      return response.content;
    }

    const toolResults: Anthropic.MessageParam = {
      role: "user",
      content: response.content
        .filter((block): block is Anthropic.ToolUseBlock => block.type === "tool_use")
        .map((toolUse) => {
          const input = toolUse.input as Record<string, unknown>;
          let result: string;
          switch (toolUse.name) {
            case "get_weather":
              result = JSON.stringify({ temp: 22, condition: "晴れ", city: input.city });
              break;
            case "search_cities":
              result = JSON.stringify([{ name: "東京" }, { name: "大阪" }]);
              break;
            default:
              result = "Unknown tool";
          }
          return { type: "tool_result" as const, tool_use_id: toolUse.id, content: result };
        }),
    };

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

import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";

const getWeather = betaZodTool({
  name: "get_weather",
  description: "指定都市の現在の天気を取得する",
  inputSchema: z.object({
    city: z.string().describe("都市名"),
    unit: z.enum(["celsius", "fahrenheit"]).optional(),
  }),
  // input の型は自動的に { city: string; unit?: "celsius" | "fahrenheit" } に推論される
  run: async (input) => {
    return JSON.stringify({ temp: 22, condition: "晴れ", city: input.city });
  },
});

const searchCities = betaZodTool({
  name: "search_cities",
  description: "キーワードで都市を検索する",
  inputSchema: z.object({
    query: z.string().describe("検索キーワード"),
    limit: z.number().optional().describe("最大件数"),
  }),
  run: async (input) => {
    // input.query は string 型。typoするとコンパイルエラー
    return JSON.stringify([{ name: "東京" }, { name: "大阪" }]);
  },
});

const client = new Anthropic();

const runner = client.beta.messages.toolRunner({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 1024,
  messages: [{ role: "user", content: "東京の天気を教えて" }],
  tools: [getWeather, searchCities],
  max_iterations: 5, // 無限ループ防止
});

// awaitするだけで最終メッセージが得られる
const finalMessage = await runner;
console.log(finalMessage.content);

const runner = client.beta.messages.toolRunner({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 1024,
  messages: [{ role: "user", content: "東京の天気を教えて" }],
  tools: [getWeather, searchCities],
  stream: true,
});

for await (const messageStream of runner) {
  for await (const event of messageStream) {
    if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
      process.stdout.write(event.delta.text);
    }
  }
}

import { ToolError } from "@anthropic-ai/sdk/lib/tools/BetaRunnableTool";

const getWeather = betaZodTool({
  name: "get_weather",
  description: "指定都市の天気を取得する",
  inputSchema: z.object({ city: z.string() }),
  run: async (input) => {
    const data = await fetchWeather(input.city);
    if (!data) {
      // モデルに is_error: true の tool_result として自動送信される
      throw new ToolError(`都市 "${input.city}" の天気データが見つかりません`);
    }
    return JSON.stringify(data);
  },
});

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
async def get_weather(city: str, unit: str = "celsius") -> str:
    """指定都市の現在の天気を取得する"""
    return json.dumps({"temp": 22, "condition": "晴れ", "city": city})

runner = client.beta.messages.tool_runner(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    tools=[get_weather],
    messages=[{"role": "user", "content": "東京の天気は？"}],
)
for message in runner:
    print(message)