Claude Advisor Tool実践ガイド — Sonnet×Opus二層構成でコスト80%削減しつつOpus級品質を実現する実装パターン

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

const client = new Anthropic();

const advisorTool = {
  type: "advisor_20260301" as const,
  name: "advisor",
  model: "claude-opus-4-7",
  max_uses: 3,
};

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

  while (true) {
    const response = await client.beta.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 4096,
      tools: [advisorTool, ...yourCustomTools],
      messages,
      betas: ["advisor-tool-2026-03-01"],
    });

    // end_turnならループ終了
    if (response.stop_reason === "end_turn") {
      return response.content;
    }

    // tool_use の場合、自前ツールのみ処理
    // server_tool_use（advisor）はサーバー側で自動処理済み
    if (response.stop_reason === "tool_use") {
      const toolResults = [];
      for (const block of response.content) {
        if (block.type === "tool_use") {
          const result = await executeYourTool(block.name, block.input);
          toolResults.push({
            type: "tool_result" as const,
            tool_use_id: block.id,
            content: result,
          });
        }
      }
      messages.push({ role: "assistant", content: response.content });
      messages.push({ role: "user", content: toolResults });
    }
  }
}

function trackAdvisorCost(response: Anthropic.Message) {
  const usage = response.usage;
  
  // executorトークン（トップレベルのusage）
  const executorInputTokens = usage.input_tokens;
  const executorOutputTokens = usage.output_tokens;
  
  // advisorトークン（usage.iterations内のadvisor_message）
  let advisorInputTokens = 0;
  let advisorOutputTokens = 0;
  
  if ("iterations" in usage) {
    for (const iter of (usage as any).iterations ?? []) {
      if (iter.type === "advisor_message") {
        advisorInputTokens += iter.input_tokens;
        advisorOutputTokens += iter.output_tokens;
      }
    }
  }

  console.log(`Executor: ${executorInputTokens}in / ${executorOutputTokens}out`);
  console.log(`Advisor:  ${advisorInputTokens}in / ${advisorOutputTokens}out`);
}

const advisorTool = {
  type: "advisor_20260301" as const,
  name: "advisor",
  model: "claude-opus-4-7",
  max_uses: 3,  // 1リクエストあたり最大3回まで
};

let totalAdvisorTokens = 0;
const ADVISOR_BUDGET = 50_000; // 会話全体のadvisorトークン上限

function getToolsForTurn(): Anthropic.Tool[] {
  const tools = [...yourCustomTools];
  
  if (totalAdvisorTokens < ADVISOR_BUDGET) {
    tools.push(advisorTool);
  } else {
    console.warn("Advisor budget exceeded — running without advisor");
  }
  
  return tools;
}

// advisorを除外する場合、会話履歴からadvisor関連ブロックも除去
function stripAdvisorFromMessages(
  messages: Anthropic.MessageParam[]
): Anthropic.MessageParam[] {
  return messages.map((msg) => {
    if (!Array.isArray(msg.content)) return msg;
    return {
      ...msg,
      content: msg.content.filter(
        (block: any) =>
          block.type !== "server_tool_use" &&
          block.type !== "advisor_tool_result"
      ),
    };
  });
}

// 各ターン後にadvisorトークンを加算
function updateBudget(response: Anthropic.Message) {
  if ("iterations" in response.usage) {
    for (const iter of (response.usage as any).iterations ?? []) {
      if (iter.type === "advisor_message") {
        totalAdvisorTokens += iter.input_tokens + iter.output_tokens;
      }
    }
  }
}

const stream = client.messages.stream({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  tools: [advisorTool, ...yourCustomTools],
  messages,
  betas: ["advisor-tool-2026-03-01"],
});

for await (const event of stream) {
  if (event.type === "content_block_start") {
    if (event.content_block.type === "server_tool_use") {
      // advisor呼び出し中 — ユーザーにプログレス表示
      console.log("Consulting advisor...");
    }
  } else if (event.type === "content_block_delta") {
    // テキスト差分をストリーム出力
  }
}