ツール出力10万文字の境界で消える一行 — 実測から組み立てた出力封筒の設計
エージェントのツール出力が10万文字を超えると全文はファイルへ退避され、モデルには先頭を切り取ったプレビューだけが渡ります。手元のリポジトリで実測した生存率と、判断材料を先頭へ押し出す出力封筒の実装をまとめました。
出力は同じ、道筋は違う — エージェントの軌跡を不変条件で守る
既定モデルが入れ替わっても最終出力は正しいまま、ツール呼び出しの道筋だけが静かに変わることがあります。実行トレースを記録し、不変条件で機械的にアサートする軌跡回帰ハーネスを実装コードと実測値で整理しました。
Claude API の Context Editing を入れたらエージェントが同じ調査を繰り返したとき — クリア境界とキャッシュ無効化を計測する運用メモ
Context Editing でツール結果を自動クリアしたら、エージェントが直前に読んだ内容を忘れて同じツールを呼び直し、キャッシュも毎回壊れてコストが上がった。沈黙する劣化を計測ログで切り分け、trigger・keep・clear_at_least を実測で決める運用メモです。
Claude API でApp Storeの多言語ストア掲載情報を文字数制限つきで生成する
App Storeの掲載情報を翻訳のまま貼るとSubtitleの30文字などの制限で弾かれます。Claude APIのTool Useで文字数制限をスキーマとして強制し、生成後の再検証と超過フィールドだけを圧縮する修復ループで各ロケールの上限内に収める実装を、キーワード欄の使い切り方まで含めて解説します。
pause_turn の継続ループに上限を入れる — 無人で長時間サーバーツールを安全に回す
web_search や code execution など長時間サーバーツールを使うと返ってくる pause_turn を、無人運用で安全に継続する設計をまとめました。4種類の stop_reason を1ループで分岐し、継続回数と時間に上限を入れ、セグメントを跨ぐ usage を数える実装まで扱います。
検索結果を二度運ばない — response_inclusion で消費済みブロックを応答から外す設計
dynamic filtering を有効にしたエージェントで出力トークンが膨らむ原因は、code execution が消費し終えた検索結果ブロックが応答に二重で乗ることにあります。response_inclusion を excluded にして安全に外せる条件と、full を保つべき条件を実装と判断表で整理しました。
Claude API の構造化レスポンスを本番で安定させる — tool_use と JSON Schema、多層検証の実装メモ
Claude API の応答を JSON で受け取る実装は数行で書けますが、本番運用では「形は正しいが意味が壊れている」レスポンスにどう備えるかが分かれ目になります。tool_use・JSON Schema・ドメイン検証を組み合わせた多層パイプラインを、壁紙アプリの分類処理での実体験を交えて整理しました。
Claude API の tool_result could not be submitted が再発しないための回復ハンドラ設計
Claude API でエージェントを長時間動かしていると、ある日突然 'tool_result could not be submitted' が連発し始めることがあります。再試行しても直らない、ストリーミング途中で死ぬ、そして次のセッションでもまた出る — 常時稼働のエージェント基盤で実際に踏み抜いた4種類の原因と、TypeScript で書いた回復ハンドラの実装を整理しました。
Claude エージェントのツール返り値を圧縮する — 巨大レスポンスを文脈に積まずに集約する設計
データベースの数千行、Webスクレイプ後のHTML、ファイル読み込みの数MBといった巨大なツール出力をそのまま Claude に渡すと文脈が破裂し、コストも品質も同時に悪化します。スキーマ縮約・サマリ・参照渡しの3層で圧縮する本番アーキテクチャを実装パターン付きで整理しました。
Claude API の Tool Use でスキーマ定義ミスが出たとき：実際に遭遇した3つのパターンと診断手順
Claude API の Tool Use でよく起きるスキーマ定義ミス・invalid_tool_use・Claude がツールを呼ばない問題を、実際のアプリ開発で遭遇したケースをもとに診断手順と修正パターンで解説します。
Claude API のツール呼び出しを Zod で型安全にした — TypeScript 開発者が詰まるポイントと実装パターン
as anyが散らばったツール呼び出しコードを、TypeScriptとZodで型安全に作り直す実装パターンです。スキーマ自動変換とランタイムバリデーション、optionalとnullableの違いやネストしたunion型の変換など詰まりやすいポイント、複数ツールの管理方法までを実践コード付きで解説します。
Claude API × Python 実践：ツール呼び出しとストリーミングを組み合わせてAIアシスタントを作る
Claude API の Tool Use とStreamingを同時に使うPython実装を解説。ツールを定義してリアルタイム応答するAIアシスタントの完成コードと、組み合わせ時に詰まりやすいポイントを丁寧に解説します。