---
title: "ツール周回の要約による圧縮（default.compaction）"
description: "長い tool loop の履歴をモデル自身の要約で圧縮する方法。"
---

MCP・サブエージェント・カスタムシェルツールの tool loop([MCP サーバーのツールを使う](/mcp)
参照)は、ラウンドを重ねるたびにメッセージ履歴(モデルのツール呼び出し + ツール実行結果)が
積み上がっていきます。`max_tool_rounds`(既定 8)に達する前に、接続先モデルの**コンテキスト
ウィンドウ/トークン上限**(lait 自身の制限ではなく、接続先プロバイダー側の制限)に達して
エラーになることがあります。`default.compaction:` は、一定ラウンドごと(またはトークン数が一定を超えたとき)にモデル自身へ「ここまでの
会話を要約して」と依頼し、古いラウンドを要約1件に置き換えることで、この履歴の増大を抑えます。

## 使い方

```yaml
# lait.config.yml
default:
  compaction:
    trigger_rounds: 6      # この倍数ラウンドの直前で要約する
    trigger_tokens: 60000  # 直前のラウンドの prompt_tokens がこの値以上なら要約する
    keep_last_n: 4         # 省略可(既定4)。直近何件のメッセージをそのまま残すか
    model: cheap           # 省略可。要約リクエストを送るモデル(alias または モデル ID)
```

`lait.config.yml` の `default:` にのみ指定できます(CLI フラグ・agent frontmatter・
ワークフローステップ個別の上書きは今のところありません)。

| フィールド | 説明 |
| --- | --- |
| `trigger_rounds` | ラウンド数の倍数(`round % trigger_rounds == 0`)ごとに、そのラウンドのリクエストを送る**前**に圧縮します。1以上の整数である必要があります(`0` は設定エラー)。 |
| `trigger_tokens` | **直前のラウンド**のリクエストでサーバーが報告した `prompt_tokens` がこの値以上になったら、次のラウンドのリクエストを送る前に圧縮します。1以上の整数である必要があります。サーバーが `usage` を報告しない場合は発動しません。 |
| `keep_last_n`（省略可、既定4） | 先頭のシステムメッセージ(あれば無条件に残ります)を除いた、直近何件のメッセージをそのまま残すかです。残りのメッセージ数が `keep_last_n` 以下の場合、まだ圧縮する意味がないため何もしません。 |
| `model`（省略可） | 要約リクエストを送るモデルです。`lait.config.yml` の `models:` の alias または生のモデル ID を指定します(ワークフローに埋め込んだ `models:` は参照しません)。省略時はそのリクエスト自身のモデルを使います。 |

`trigger_rounds` と `trigger_tokens` の少なくとも一方が必要です(どちらもない場合は、
tool loop が最初に圧縮の要否を判定した時点で設定エラーになります)。両方を指定した場合は、
どちらかの条件を満たしたときに圧縮します。

`trigger_tokens` の判定に使うのは直前のラウンドのリクエスト全体のトークン数なので、そのラウンドで
追加されたツール実行結果の分はまだ含まれていません。上限に対して余裕のある値を指定してください。

## 動作の仕組み

1. 対象ラウンドのリクエストを送る前に、これまでの会話履歴 + 「ここまでの会話を要約してください」
   という指示を1回だけモデルへ送信します。
2. 返ってきた要約テキストを1件の assistant メッセージとして、先頭のシステムメッセージ(あれば)の
   直後、`keep_last_n` 件の直近メッセージの前に挿入します。
3. 圧縮後の(短くなった)メッセージ履歴で、そのラウンド自身のリクエストを続けて送信します。

要約のためのリクエストも、通常のラウンドと**全く同じ経路**(`--cache`/`--record`/`--replay`/
[実行トレース](/trace))を通ります。つまり:

- `--record` で記録したカセットには要約リクエストの分も含まれ、`--replay`/`lait test` で
  再生する際は要約リクエスト用のカセットも必要です。`default.compaction:` を後から有効にした
  場合、既存のカセットには要約リクエストが記録されていないため再記録が必要です。
- [実行トレース](/trace)には、要約リクエスト自体の `"chat"` イベントに加えて、
  `"compact"` という専用のイベントが記録されます(`lait.compaction.round`/
  `lait.compaction.messages_before`/`lait.compaction.messages_after` 属性付き)。

## 制限事項

- `lait run`(ワークフローの `prompt`/`agent` ステップ)・`lait agent run`・チャット
  (`--stream` の有無を問わず、`lait chat` を含む)の tool loop に適用されます。要約リクエスト
  自体は `--stream` 使用時もストリーミングせずに送ります。
- `--stream` 使用時に `trigger_tokens` を指定すると、`--show-usage` を付けなくても各ラウンドで
  サーバーに usage の報告(`stream_options.include_usage`)を要求します。
- `max_tool_rounds` 自体は伸びません — 圧縮はラウンドあたりのメッセージ量を抑えるだけで、
  ラウンド数の上限そのものを緩和するものではありません。