◉CLAUDE LABEN
●CC 2.1.330 — Claude Code 2.1.330 で、長い会話を圧縮した直後に数分固まる問題が直りました●SONNET 4.5 — Claude API の Sonnet 4.5 は 11/30 で提供終了、残り8日です。推奨の移行先は claude-sonnet-5-5 です●MCP 401 — MCP サーバーが 401 を返しても、エラーにならず無言でタイムアウトする、という報告が出ています●NEW — 新着:Desktop が毎回 worktree を作るとき、確かめる3か所●OPUS 4.5 — Opus 4.5 の 11/24 は「これより前には廃止しない」下限日で、廃止の告知ではありません●SCHEMA — Agent SDK と Messages API の構造化出力は、同じスキーマでも返り値の形を一度見比べると安心です●CC 2.1.330 — Claude Code 2.1.330 で、長い会話を圧縮した直後に数分固まる問題が直りました●SONNET 4.5 — Claude API の Sonnet 4.5 は 11/30 で提供終了、残り8日です。推奨の移行先は claude-sonnet-5-5 です●MCP 401 — MCP サーバーが 401 を返しても、エラーにならず無言でタイムアウトする、という報告が出ています●NEW — 新着:Desktop が毎回 worktree を作るとき、確かめる3か所●OPUS 4.5 — Opus 4.5 の 11/24 は「これより前には廃止しない」下限日で、廃止の告知ではありません●SCHEMA — Agent SDK と Messages API の構造化出力は、同じスキーマでも返り値の形を一度見比べると安心です
記事一覧/API & SDK
⬡ API & SDK/2026-06-30上級

ツール出力が大きすぎてコンテキストを溶かす問題 — カーソルで小分けに返すページング設計

一覧系のツールが数百件をそのまま返すと、エージェントのコンテキストは一回の呼び出しで溶けます。カーソルベースのページングでツール出力を小分けに返し、トークン予算を守る設計を実装コード付きで解説します。

Claude API148Agent SDK5MCP63コンテキスト管理3トークン最適化3

✦ プレミアム記事

個人開発で4つの技術ブログを自動運用していると、エージェントに「公開済みの記事一覧を見せて」と頼む場面が一日に何度も訪れます。あるとき、その一覧を返すMCPツールが400件あまりのタイトルとスラッグをまるごと返し、たった一回の呼び出しでコンテキストウィンドウの体感2割ほどを食い潰しました。

会話のまだ序盤です。これから記事を生成し、品質ゲートをかけ、pushまで走らせなければなりません。にもかかわらず、最初のツール呼び出しだけで予算の入り口がふさがれてしまった。手が止まりました。

原因ははっきりしています。ツールが「全部」を返していたからです。エージェントが本当に必要としていたのは、最新の数十件と「まだ続きがある」という事実だけでした。以下では、その落とし穴を埋めるカーソルベースのページングを、署名付き不透明カーソルの実装まで含めて組み立てます。

なぜ「全件返す」ツールがエージェントを壊すのか

通常のWeb APIなら、レスポンスが多少大きくてもクライアントが受け取って捨てるだけです。ところがエージェントの場合、ツールの戻り値はそのまま次のターンの入力トークンになります。一覧が大きいほど、以降の全ターンでその重みを背負い続けることになります。

実測してみました。私の記事一覧ツールは、1件あたりタイトル・スラッグ・カテゴリ・公開日・タグを返します。日本語タイトルを含むので、1件あたりおよそ45トークン。400件で約18,000トークンです。これが会話の冒頭に居座ると、後続のシステムプロンプト・生成指示・コード片と合わさって、まだ何も作っていないのに予算の足元が崩れます。

さらに厄介なのは、この出力がプロンプトキャッシュと相性が悪い点です。一覧は記事を追加するたびに変わるため、巨大かつ揮発性の高いブロックになります。キャッシュの安定ブロックと揮発ブロックを分離する設計をしていても、この一覧だけは毎回キャッシュミスを生み続けます。

オフセット方式では足りない理由

「ではページングすればよい」と考えて、まずオフセット方式(offset と limit)を試しました。実装は最も単純です。

def list_articles_offset(offset: int = 0, limit: int = 20):
    rows = db.query(
        "SELECT slug, title, category, published_at "
        "FROM articles WHERE status = 'published' "
        "ORDER BY published_at DESC LIMIT ? OFFSET ?",
        (limit, offset),
    )
    return {"items": rows, "next_offset": offset + limit}

これで1ページ20件、約900トークンに収まりました。18,000トークンからおよそ95%の削減で、トークン量だけ見れば成功です。

ところが運用に乗せてすぐ、エージェントが同じ記事を二度処理する事故が起きました。エージェントが1ページ目を見て検討している最中に、別のスケジュールタスクが新しい記事を1本publishしたのです。published_at DESC の並びでは、新記事が先頭に割り込みます。その結果、もともと20番目だった記事が21番目へ押し出され、offset=20 の2ページ目で再び現れました。逆に、削除が起きれば取りこぼしが発生します。

オフセット方式は「並びが固定されている」という前提に立っています。エージェントの世界では、その前提がしばしば成り立ちません。複数のタスクが同じデータを並行して触るからです。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦一覧系ツールが400件を一括返却して約18,000トークンを消費していた箇所を、1ページ20件・カーソル方式で約900トークンまで削減した実装手順
✦オフセット方式が陥る重複・取りこぼしを避ける、不透明カーソル(opaque cursor)の署名付きエンコード実装(Python / TypeScript)
✦エージェントが『次のページを取りに行くべきか』を自分で判断できるよう、has_more と要約メタ情報をツール結果に同梱する設計指針
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

関連記事

⬡ API & SDK2026-07-24
共通エージェント定義をセッション単位で使い分ける運用設計
Managed Agents で土台のエージェント定義を1つに畳み、バージョン固定とセッションローカルな上書きを使い分ける設計を、検証付きのコードと運用の落とし穴とともにまとめました。
⬡ API & SDK2026-05-14
Claude API でアプリ内 AI チャットを実装して踏んだ6つの罠 — 本番投入までの設計記録
Claude APIをアプリ内チャットに組み込んで本番で直面した6つの設計ミスを、個人開発での実運用経験から解説。コンテキスト設計、ストリーミング、セッション管理、コスト監視の実装パターンを動くコード付きで紹介します。
⬡ API & SDK2026-04-25
Claude API × Convex でリアクティブな AI アプリを本番構築する — データフロー設計とエージェントパターン
Convex のリアクティブデータベースと Claude API を組み合わせて、本番運用に耐えるチャット・エージェント系アプリを構築する方法をまとめました。スキーマ設計、Action/Mutation/Query の境界、ストリーミング、ツール状態管理、冷え始めの落とし穴まで、開発現場の判断軸を共有します。