API / SDK
開発者向けの Claude API / SDK 連携ガイドです。認証、ストリーミング、ツール呼び出し、コスト管理、エージェント構築まで、動くコード例とともに本番運用の勘所を解説します。個人開発での実運用の実例も交えて紹介しています。
夜間バッチが勝手に上位モデルで走っていた — タスクごとにモデル上限を宣言して機械で守る
モデル名をコードに散らすと、いつのまにか安いはずのバッチが上位モデルで走ります。タスクごとの上限を宣言するマニフェストと、既定拒否の解決レイヤ、そして逸脱を検出する差分監査の設計をコード付きでまとめました。
出力は同じ、道筋は違う — エージェントの軌跡を不変条件で守る
既定モデルが入れ替わっても最終出力は正しいまま、ツール呼び出しの道筋だけが静かに変わることがあります。実行トレースを記録し、不変条件で機械的にアサートする軌跡回帰ハーネスを実装コードと実測値で整理しました。
RAG が自信たっぷりに間違え始めたとき — 検索の取りこぼしを接地率で計測する運用メモ
Claude API の RAG で、回答は流暢なのに事実がずれ始める。多くの場合、原因は検索側で答えを含む文書を取りこぼすサイレントなリコール低下です。接地率と検索ヒット率を計測し、段階的に立て直した運用メモを、動くコードと実数値付きで残します。
20万トークンの崖で夜間バッチの請求が跳ねた — count_tokens プリフライトで長コンテキスト単価を避ける
Sonnet 5 のネイティブ1Mコンテキストは、入力が20万トークンを超えた瞬間にリクエスト全体が長コンテキスト単価へ切り替わります。無人バッチで請求が静かに倍増する崖を、課金対象外の count_tokens プリフライトで手前に止めた実装を、Python と TypeScript の動くコードで記録します。
無人エージェントの挙動変更を、フィーチャーフラグで少しずつ試す設計
無人で走るエージェントのプロンプトや挙動を一度に全変更すると、劣化が朝まで見えません。フィーチャーフラグで一部の実行にだけ新挙動を割り当て、品質を見てから広げる設計と、決定論的バケット・自動ロールバック・監査証跡の実装を紹介します。
MCP コネクタを申請・無人運用に回す前に、各ツールを契約テストで確かめる
手元で動いた MCP コネクタをそのまま無人ジョブに繋ぐと、応答形状の誤読や書き込みの二重発火で静かに壊れます。ツール記述・応答契約・冪等性・レイテンシを機械検証する小さなハーネスの作り方を、実測値とともにまとめました。
4サイト分のClaude費用が一つの請求に混ざる — ワークスペース単位で支出を割り当て、絞るパイプラインを見極める
複数プロジェクトのClaude API費用が一つの組織請求に合算されて判断を誤る問題を、Cost Report / Usage Report の group_by でワークスペース別に割り当てて解く実装メモです。防御的パース・showback表・費用対効果での選別まで扱います。
Claude API が本番で突然 429 を返し始めたとき — レート制限の余白をヘッダから計測して枯渇前に絞る運用メモ
429 が出てから慌ててリトライを入れるのは後手です。Claude API のレスポンスヘッダには残量が毎回書かれています。余白を継続計測し、枯渇する前に自分から絞る運用メモを、実装フックと計測ログの読み方でまとめます。
Fable 5 が全世界に戻り、Sonnet 5 が既定になった — 個人運用の自動化スタックで3モデルをどの層に置くか
Fable 5 の全世界提供再開と Sonnet 5 の既定化で、個人運用の自動化に使える上位モデルが一気に3つ揃いました。優劣で選ぶのではなく、タスクの持ち場でモデルを割り当てる方針オブジェクトを、フォールバック梯子と記録つきの実装でまとめます。
Opus 4.7 の fast mode 廃止（7/24）で無人ジョブを落とさない — speed パラメータの事前検査と移行
claude-opus-4-7 の fast mode が 2026-07-24 に廃止され、speed: fast がエラーになります。無人パイプラインを静かに壊さないための、使用箇所の機械検出・fail-closed な実行時ガード・4.8 への移行シムを実装コード付きでまとめました。
Claude apps gateway の発表を読んで、個人開発の管制面を作り直した話
セルフホスト型 Claude apps gateway の設計を管制面と実行面の分離として読み解き、個人開発の規模に縮約します。アプリ別コスト帰属・モデル許可リスト・fail-closed の支出上限を Cloudflare Workers で実装した記録です。
claude-opus-4-7 の speed:fast が 7/24 で失効する — 能力ペア単位で守る preflight
Opus 4.7 の fast モードが 2026-07-24 に廃止されます。モデルIDは有効なまま speed 指定だけがエラーになるため、モデルID監査では取りこぼします。能力ペア単位の preflight と自動移行を実装します。
同時リクエスト数はいくつまで持つのか — Little の法則と実測メモリで決める Claude API 本番デプロイのインフラ要件
同時リクエスト数・待ち行列長・メモリはいくつに設定すべきか。Claude API 本番デプロイのインフラ要件を Little の法則と実測ハーネスで数字から導く手順を、夜間バッチで OOM を踏んだ経験をもとに整理しました。
単価が40%下がっても、タスク単価は下がるとは限らない — Opus 4.8 から Sonnet 5 への移行損益をトークン消費プロファイルで測る
Sonnet 5 の導入価格は Opus 4.8 より約40%安ですが、ツール往復が増えるとタスク単価は逆転し得ます。消費ベクトルの記録・並走ハーネス・損益分岐ターン数の逆算までを動くTypeScriptと実測で示します。
9月1日に単価は1.5倍へ戻る — Sonnet 5 導入価格の期限を織り込む実効日付きコスト予測
Claude Sonnet 5 の導入価格 $2/$10 は 2026-08-31 で終わり、9月からは $3/$15 になります。静的な単価表のままでは月次予測が3割ずれる問題を、有効期間つき単価テーブルと予測シミュレータで解く設計をまとめました。
Message Batches に2万件投げたら41件だけ静かに欠けていたとき — 部分失敗を照合して再投入する運用メモ
Message Batches API の processing_status: ended は全件成功を意味しません。errored・expired が結果に静かに混ざる仕組みと、custom_id 台帳で欠落を照合し二重処理なく再投入する実装を、実運用の計測値とともに整理します。
モデルを切り替えた朝、キャッシュヒット率はゼロに戻る — Opus 4.8 から Sonnet 5 への段替えとプロンプトキャッシュ再ウォーム設計
プロンプトキャッシュはモデル単位で分離されるため、モデル移行の初日はヒット率が0%から始まります。割合ベースの段階移行が二重にコストを壊す構造と、タスク系統単位で切り替えるコホート・カットオーバー設計を実測コードつきで整理します。
モデルは残るのにパラメータだけ期限切れになる — Claude API リクエストの廃止を日付で先回りする設計
モデル名は有効なまま、指定していたパラメータだけが廃止日を迎えてバッチが落ちることがあります。リクエストを部品に分解し、部品ごとに廃止期限を持たせて起動前に先回りする設計を、TypeScript の動くコードと運用の実測でまとめました。
Claude API のドキュメント抽出が「自信満々に間違える」とき — 沈黙する誤りを不変条件で捕まえる運用メモ
請求書や契約書の構造化抽出で一番怖いのは、クラッシュではなく「スキーマも通り信頼度も高いのに値だけ間違っている」沈黙の誤りです。不変条件・二段抽出・フィールド単位の誤り率で運用する実装メモを共有します。
新モデルが増えてもコスト集計をズラさない Claude API 単価レジストリと fail-closed 設計
Opus 4.8 と Haiku 4.5 が Messages API に加わったとき、コード中に散らばった単価がコスト集計を静かに狂わせます。単価を1か所に集約し、未知モデルを fail-closed で弾く実装を、実コード付きで紹介します。
「同じ 429」が経路ごとに違う顔で返る — Claude を Anthropic 直叩きと Azure Foundry の二経路で安全に回す
Claude が Microsoft Foundry でも一般提供されたことで、直叩きと Azure 経由の二経路が現実的になりました。同じ 429 が経路ごとに違う形で返る問題を、正規化エラー型と retry-after の両形式パースで畳む実装をまとめます。
ツール出力が大きすぎてコンテキストを溶かす問題 — カーソルで小分けに返すページング設計
一覧系のツールが数百件をそのまま返すと、エージェントのコンテキストは一回の呼び出しで溶けます。カーソルベースのページングでツール出力を小分けに返し、トークン予算を守る設計を実装コード付きで解説します。
中間ファイルを毎回作り直さない — Code Execution のコンテナを跨いで多段パイプラインの状態を保つ
Code Execution ツールのコンテナを container ID で再利用し、生成済みファイルや前処理結果を次のリクエストへ持ち越す設計を解説します。実行時間課金の落とし穴と container_expired の安全な扱い方まで、実装コード付きで整理しました。
ツールが返す画像を Claude に「見せる」 — tool_result を画像ブロックにしてトークンを約10分の1にする
ツールが返した画像を tool_result に文字列で詰めると、同じ画像が約10〜20倍のトークンを消費します。image コンテンツブロックとして返す正しい組み立て方と、SDK 実装・コスト見積もり・落とし穴を実コードでまとめました。
Claude API の Context Editing を入れたらエージェントが同じ調査を繰り返したとき — クリア境界とキャッシュ無効化を計測する運用メモ
Context Editing でツール結果を自動クリアしたら、エージェントが直前に読んだ内容を忘れて同じツールを呼び直し、キャッシュも毎回壊れてコストが上がった。沈黙する劣化を計測ログで切り分け、trigger・keep・clear_at_least を実測で決める運用メモです。
接続が切れた瞬間、その投稿は通ったのか — 無人パイプラインで MCP 書き込みを二重実行せずにやり直す
接続断で中断した MCP の書き込みツール呼び出しは、サーバー側で実行されたかどうか分かりません。素朴な再試行が二重投稿を生む理由と、冪等キーと照合読み取りで安全にやり直すラッパーの実装を、無人パイプラインの実例とともにまとめました。
ストリーミング応答のCPUと取りこぼしを実測して長時間バッチを安定させる
夜間の長時間バッチが朝には半分しか進んでいない——原因はCPUの張り付きとストリームの中断でした。ストリーミングの資源消費を実測する手順、中断を検知して安全に再開する監視ラッパー、バッチ全体を冪等な単位で回す構成まで、無人運用の取りこぼしを減らす実装を紹介します。
ツール呼び出しは成功しているのに前進しない — 無人エージェントの停滞を検知して止める設計
エラーは出ていないのに同じ手を繰り返し、予算だけが溶けていく。無人エージェントの『成功し続ける停滞』を、行動フィンガープリントと進捗オラクルで検知して安全に止める設計をPythonの実装つきでまとめました。
弱いモデルへ静かに落ちる方がエラーより怖い — Claude API のモデル降格に「下限」を設ける設計
無人運用のパイプラインでモデルが使えなくなったとき、弱いモデルへ自動で落ちる実装は危険です。タスクごとの能力契約と降格予算で「どこまで落ちたら止めるか」を決める設計を、個人開発の自動運用の実体験から解説します。
自己修復ループに「諦める条件」を設計する — エラーを4分類して再試行予算を割り当てる
LLMの自己修復ループは「直し続ければいつか通る」という前提で組むと破綻します。エラーを4つのクラスに分類し、クラスごとに再試行予算を割り当てて諦める条件を明示する設計を、動くTypeScriptの分類器実装、コスト天井の置き方、構造化した試行ログ、フォールバックの段構えとともに解説します。
Claude API のストリーミングが「エラーも出さずに」止まるとき — 沈黙する停止を検知して途中から続ける運用メモ
Claude API のストリーミングが例外も出さずに無言で止まる「沈黙停止」を、トークン間隔のウォッチドッグで検知し、受信済みテキストを引き継いで途中から再開する実装と、長時間の自動運用で崩れないためのタイムアウト予算の設計をまとめます。
漏洩しても請求が膨らむ前に止める — 無人パイプラインのAPIキー被害半径設計
漏洩を前提にAPIキーの被害半径を縮める設計。ワークスペース単位のキー分離、無停止ローテーション、使用量のローリングベースライン＋中央絶対偏差でスパイクを検知する番犬の実装を、定期実行への組み込みまで通します。
同じモデル名で挙動が変わったとき — 無人パイプラインに起動時カナリアを置いて差分を捕まえる
同じモデル名のまま挙動が変わる無言の上方更新は、無人パイプラインでは誰も気づけません。起動時に小さなカナリアを走らせて構造の指紋を比べ、ベースラインとの差分でドリフトを判定してバッチを止める設計を、ゴールデンデータセット回帰テストとの違いや実測したコストとともに紹介します。
Claude API でApp Storeの多言語ストア掲載情報を文字数制限つきで生成する
App Storeの掲載情報を翻訳のまま貼るとSubtitleの30文字などの制限で弾かれます。Claude APIのTool Useで文字数制限をスキーマとして強制し、生成後の再検証と超過フィールドだけを圧縮する修復ループで各ロケールの上限内に収める実装を、キーワード欄の使い切り方まで含めて解説します。
API リクエスト1本でリモート MCP サーバーに直接つなぐ — Messages API の MCP コネクタ実装メモ
ローカルに MCP クライアントを立てずに、Messages API の mcp_servers と mcp_toolset だけでリモート MCP サーバーのツールを呼ぶ実装をまとめました。allowlist/denylist 設計、レスポンス処理、無人運用での落とし穴まで。
前の実行が終わらないうちに次が走り出すとき — リースとフェンシングトークンで定期エージェントの多重起動を抑える
毎朝の定期実行が前回の処理を追い越して二重に走り出す問題を、リースとフェンシングトークンで抑える設計を解説します。素朴なロックが破れる瞬間の分析から、任意ストア上の最小リース実装、副作用直前のトークン検証、上限付きキャッチアップまで、運用で固めた既定値とともに実装コード付きで整理しました。
サポートAIが本番で「自信満々に間違える」とき — 根拠の外を踏ませず、迷ったら人へ渡す運用メモ
Claude API のカスタマーサポートエージェントが、テストでは完璧でも本番で存在しない情報を断言してしまう問題への対処。検索段階で「答えない」を決める設計、根拠付き生成、誤自信率の計測、エスカレーション精度の調整までを運用視点でまとめます。
ツール定義を一行直しただけで、キャッシュが丸ごと作り直しになりました — cache_control ブレークポイントの置き場所
ヒット率が突然ゼロに張り付いた原因は、揮発するブロックを安定したブロックより上流に置いていたことでした。prefix キャッシュのカスケード失効の仕組みと、安定→揮発でブロックを並べ替え、4つしかない cache_control ブレークポイントをどこに置くかを実装と判断表で整理します。
上限が倍になった日に決めたこと — 共有APIキーで定期ジョブを束ねる余白予算の設計
レート上限が倍になってもジョブ間隔を詰めなかった理由と、共有APIキーで複数の定期ジョブを束ねる「余白予算」の設計をまとめました。レスポンスヘッダーからの現状計測、ジョブ別の消費割り当て、予算を据え置いた判断の背景、本番運用で見えた落とし穴までを実コードとともに紹介します。
Claude API の従量課金で、Stripe の請求額と自分の帳簿がズレるとき — 使用量イベントの突合運用メモ
Claude API の従量課金は「使った分だけ請求」が理想ですが、実運用ではStripe側の集計と自前の使用量台帳が静かにズレます。Billing Meters の冪等化・突合ジョブ・モデル変更耐性まで、運用で効いた設計を整理します。