[小ネタ] Strands Agents の Context Offloader を試してみた

uv init context-offload
cd context-offload
uv add strands-agents

import json

from strands import tool

@tool
def generate_large_data(count: int = 100) -> str:
    """大量のユーザーデータを生成して返します。データ分析やレポート生成のシミュレーション用です。

    Args:
        count: 生成するユーザー数（デフォルト: 100）
    """
    users = []
    for i in range(1, count + 1):
        users.append(
            {
                "id": i,
                "name": f"User_{i}",
                "email": f"user{i}@example.com",
                "department": ["Engineering", "Sales", "Marketing", "Support", "HR"][i % 5],
                "role": ["Manager", "Senior", "Junior", "Lead", "Intern"][i % 5],
                "salary": 50000 + (i * 1000),
                "projects": [f"Project_{j}" for j in range(1, (i % 5) + 2)],
                "skills": [f"Skill_{j}" for j in range(1, (i % 3) + 4)],
                "location": ["Tokyo", "Osaka", "Nagoya", "Fukuoka", "Sapporo"][i % 5],
                "joined_date": f"202{i % 5}-{(i % 12) + 1:02d}-{(i % 28) + 1:02d}",
            }
        )

    return json.dumps({"total": count, "users": users}, ensure_ascii=False, indent=2)

from strands import Agent
from strands.models import BedrockModel
from tools import generate_large_data

model = BedrockModel(
    model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    region_name="us-east-1",
)

agent = Agent(
    model=model,
    tools=[generate_large_data],
    system_prompt="あなたはデータ分析アシスタントです。ユーザーの質問に日本語で回答してください。",
)

result = agent(
    "generate_large_dataツールを使って200件のユーザーデータを取得し、部署ごとの人数を集計してください。"
)

for i, cycle in enumerate(result.metrics.agent_invocations[0].cycles):
    print(f"サイクル{i+1}: input={cycle.usage['inputTokens']}, output={cycle.usage['outputTokens']}")
print(f"合計: {result.metrics.agent_invocations[0].usage}")

from strands import Agent
from strands.models import BedrockModel
from strands.vended_plugins.context_offloader import ContextOffloader, FileStorage
from tools import generate_large_data

model = BedrockModel(
    model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    region_name="us-east-1",
)

offloader = ContextOffloader(
    storage=FileStorage("./artifacts"),
    max_result_tokens=2_500,
    preview_tokens=1_000,
)

agent = Agent(
    model=model,
    tools=[generate_large_data],
    plugins=[offloader],
    system_prompt="あなたはデータ分析アシスタントです。ユーザーの質問に日本語で回答してください。",
)

result = agent(
    "generate_large_dataツールを使って200件のユーザーデータを取得し、部署ごとの人数を集計してください。"
)

for i, cycle in enumerate(result.metrics.agent_invocations[0].cycles):
    print(f"サイクル{i+1}: input={cycle.usage['inputTokens']}, output={cycle.usage['outputTokens']}")
print(f"合計: {result.metrics.agent_invocations[0].usage}")

uv run python without_offloader.py

generate_large_dataツールを使って200件のユーザーデータを取得します。
Tool #1: generate_large_data
完璧です！200件のユーザーデータを取得できました。部署ごとに人数を集計します。

## 部署ごとの人数集計結果

取得した200件のユーザーデータを部署別に集計すると、以下のようになります：

| 部署 | 人数 |
|------|------|
| **Engineering** | 40名 |
| **Sales** | 40名 |
| **Marketing** | 40名 |
| **Support** | 40名 |
| **HR** | 40名 |
| **合計** | **200名** |

サイクル1: input=897,   output=80    ← プロンプト送信、ツール呼び出しを決定
サイクル2: input=32,615, output=422   ← 85KBのJSON全体がコンテキストに入る
合計: inputTokens=33,512, outputTokens=502

uv run python with_offloader.py

200件のデータを取得して、部署ごとの人数を集計します。
Tool #1: generate_large_data
データが大きいため、オフロードされています。参照を使用して完全なデータを取得します。
Tool #2: retrieve_offloaded_content
完全なデータが取得できました。200件のデータから部署ごとの人数を集計いたします。

## 部署ごとの人数

| 部署 | 人数 |
|------|------|
| **Sales** | 40名 |
| **Marketing** | 40名 |
| **Support** | 40名 |
| **HR** | 40名 |
| **Engineering** | 40名 |
| **合計** | **200名** |

データから5つの部署に均等に配置されており、各部署に40名ずつ配置されています。

サイクル1: input=1,018,  output=80    ← プロンプト送信、ツール呼び出しを決定
サイクル2: input=2,747,  output=121   ← プレビューのみ！エージェントが全文取得を判断
サイクル3: input=34,506, output=358   ← retrieve_offloaded_content で全文取得
合計: inputTokens=38,271, outputTokens=559

[Offloaded: 1 blocks, ~21,301 tokens]
Tool result was offloaded to external storage due to size.
Use the preview below to answer if possible.
Use your available tools to selectively access the data you need.
You can also use retrieve_offloaded_content with a reference to get the full content.

{
  "total": 200,
  "users": [
    {
      "id": 1,
      "name": "User_1",
      "email": "user1@example.com",
      "department": "Sales",
      ...
    },
    ...（先頭約1,000トークン分のプレビュー）
  ]
}

[Stored references:]
  artifacts/1778588187704_1_tooluse_xxx_0.txt (text, 85,201 chars)

ls -la ./artifacts/

-rw-r--r--  70B  .metadata.json
-rw-r--r--  85K  1778588187704_1_tooluse_4CxnHQahp8G9LyDp6HfRFe_0.txt

{"1778588187704_1_tooluse_4CxnHQahp8G9LyDp6HfRFe_0.txt": "text/plain"}

{
  "total": 200,
  "users": [
    {
      "id": 1,
      "name": "User_1",
      "email": "user1@example.com",
      "department": "Sales",
      "role": "Senior",
      "salary": 51000,
      "projects": [
        "Project_1",
        "Project_2"
      ],
      "skills": [
        "Skill_1",
        "Skill_2",
        "Skill_3",
        "Skill_4"
      ],
      "location": "Osaka",
      "joined_date": "2021-02-02"
    },
    ...
  ]
}

agent = Agent(
    model=model,
    tools=[generate_large_data],
    plugins=[offloader],
    system_prompt="あなたはデータ分析アシスタントです。ユーザーの質問に日本語で簡潔に回答してください。",
)

result = agent(
    "generate_large_dataツールで200件のデータを取得して、データのフォーマット（どんなフィールドがあるか）を教えてください。"
)

for i, cycle in enumerate(result.metrics.agent_invocations[0].cycles):
    print(f"サイクル{i+1}: input={cycle.usage['inputTokens']}, output={cycle.usage['outputTokens']}")
print(f"合計: {result.metrics.agent_invocations[0].usage}")

200件のデータを取得して確認します。
Tool #1: generate_large_data
200件のデータを取得しました。以下がデータのフォーマットです：

## ユーザーデータのフィールド構成

生成されたデータには、以下の10個のフィールドが含まれています：

1. id (数値) - ユーザーの一意識別子
2. name (文字列) - ユーザー名（例：User_1）
3. email (文字列) - メールアドレス
4. department (文字列) - 所属部門
   - 例：Sales、Marketing、Support、HR、Engineering
5. role (文字列) - 職位
   - 例：Senior、Junior、Lead、Intern、Manager
6. salary (数値) - 給与金額
7. projects (配列) - 関連プロジェクト一覧
8. skills (配列) - 所有スキル一覧
9. location (文字列) - 勤務地
   - 例：Tokyo、Osaka、Nagoya、Fukuoka、Sapporo
10. joined_date (日付文字列) - 入社日

このデータは従業員情報の管理や分析に適した構造になっています。

サイクル1: input=1,029, output=70   ← プロンプト送信、ツール呼び出しを決定
サイクル2: input=2,748, output=343  ← プレビュー + 会話コンテキストのみで回答
合計: inputTokens=3,777, outputTokens=413, totalTokens=4,190