Claude API Automatic Prompt Caching実践ガイド — cache_control一行でAPIコストを最大90%削減する

// Before: 手動管理 — ターンが増えるたびにcache_controlの位置を移動する必要がある
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "あなたはTypeScriptの専門家です。...(長いシステムプロンプト)...",
      cache_control: { type: "ephemeral" }, // ← システムプロンプト末尾に手動配置
    },
  ],
  messages: [
    { role: "user", content: "関数型プログラミングについて教えて" },
    { role: "assistant", content: "関数型プログラミングとは..." },
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "具体的なコード例を見せて",
          cache_control: { type: "ephemeral" }, // ← 最新メッセージの直前に手動配置
        },
      ],
    },
  ],
});

// After: 自動管理 — トップレベルに一行追加するだけ
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  cache_control: { type: "ephemeral" }, // ← これだけ
  system: "あなたはTypeScriptの専門家です。...(長いシステムプロンプト)...",
  messages: [
    { role: "user", content: "関数型プログラミングについて教えて" },
    { role: "assistant", content: "関数型プログラミングとは..." },
    { role: "user", content: "具体的なコード例を見せて" },
  ],
});

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

const client = new Anthropic();

async function chat(conversationHistory: Anthropic.MessageParam[]) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 4096,
    cache_control: { type: "ephemeral" }, // 自動キャッシュ有効化
    system:
      "あなたはフルスタック開発のエキスパートです。...(長いシステムプロンプト)...",
    messages: conversationHistory,
  });

  // キャッシュヒット状況を確認
  console.log(`Cache read: ${response.usage.cache_read_input_tokens ?? 0}`);
  console.log(
    `Cache creation: ${response.usage.cache_creation_input_tokens ?? 0}`
  );

  return response;
}

import anthropic

client = anthropic.Anthropic()

def chat(conversation_history: list[dict]):
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        cache_control={"type": "ephemeral"},
        system="あなたはフルスタック開発のエキスパートです。...",
        messages=conversation_history,
    )

    print(f"Cache read: {response.usage.cache_read_input_tokens or 0}")
    print(f"Cache creation: {response.usage.cache_creation_input_tokens or 0}")
    return response

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

const client = new Anthropic();

const tools: Anthropic.Tool[] = [
  {
    name: "search_codebase",
    description: "コードベースをキーワード検索する",
    input_schema: {
      type: "object" as const,
      properties: {
        query: { type: "string", description: "検索クエリ" },
      },
      required: ["query"],
    },
    cache_control: { type: "ephemeral", ttl: 3600 }, // 1時間TTL
  },
  // ... 他のtools定義
];

async function agentStep(messages: Anthropic.MessageParam[]) {
  const response = await client.messages.create({
    model: "claude-opus-4-6",
    max_tokens: 8192,
    tools,
    system: [
      {
        type: "text",
        text: "あなたは自律的にコードを読み書きするAIエージェントです。...(長いシステムプロンプト)...",
        cache_control: { type: "ephemeral", ttl: 3600 }, // 1時間TTL
      },
    ],
    messages: [
      ...messages.slice(0, -1),
      // 最新メッセージのみ5分TTLでキャッシュ
      {
        ...messages[messages.length - 1],
        ...(messages[messages.length - 1].role === "user" && {
          content: [
            {
              type: "text" as const,
              text:
                typeof messages[messages.length - 1].content === "string"
                  ? messages[messages.length - 1].content
                  : "",
              cache_control: { type: "ephemeral" }, // デフォルト5分TTL
            },
          ],
        }),
      },
    ],
  });

  return response;
}

async function handleAgentLoop(messages: Anthropic.MessageParam[]) {
  const response = await agentStep(messages);

  // キャッシュ状況をログ出力して確認
  const { usage } = response;
  console.log(
    [
      `input: ${usage.input_tokens}`,
      `cache_read: ${usage.cache_read_input_tokens ?? 0}`,
      `cache_creation: ${usage.cache_creation_input_tokens ?? 0}`,
    ].join(" | ")
  );
  // Compaction後でも cache_read が大きければ system/tools キャッシュが効いている

  return response;
}

function logCacheMetrics(usage: Anthropic.Usage & {
  cache_read_input_tokens?: number;
  cache_creation_input_tokens?: number;
}) {
  const total = usage.input_tokens;
  const cacheRead = usage.cache_read_input_tokens ?? 0;
  const cacheWrite = usage.cache_creation_input_tokens ?? 0;
  const uncached = total - cacheRead - cacheWrite;
  const hitRate = total > 0 ? ((cacheRead / total) * 100).toFixed(1) : "0.0";

  console.log(
    `[Cache] hit: ${hitRate}% | read: ${cacheRead} | write: ${cacheWrite} | uncached: ${uncached}`
  );

  // キャッシュが全く効いていない場合に警告
  if (cacheRead === 0 && cacheWrite === 0) {
    console.warn(
      "[Cache] WARNING: キャッシュが効いていません。最小トークン要件またはプロンプト内容を確認してください"
    );
  }
}