AgentCoreハーネスでプロンプトキャッシュを有効にする方法

Amazon Bedrockのエージェント構築基盤「AgentCore」において、プロンプトキャッシュが効かない問題が確認されている。Qiitaのmoritalous氏が2026年7月18日に公開した記事では、この問題に対する具体的な回避策が提示された。AgentCoreハーネスをランタイムにエクスポートし、コードを直接修正することで、強制的にキャッシュを有効化する手法だ。

プロンプトキャッシュは、LLMに送信するプロンプトの繰り返し部分をキャッシュすることで、応答時間の短縮とAPIコストの削減を実現する機能。特にシステムプロンプトやツール定義が長大になりがちなエージェント型アプリケーションでは、その効果は大きい。Strands AgentsフレームワークはClaudeとの連携においてプロンプトキャッシュを比較的容易に有効化できるが、AgentCoreハーネスの標準構成ではこの機能が無効化されたままとなっていた。

問題の所在

AgentCoreはAmazon Bedrock上でエージェントを開発・デプロイするための統合フレームワークだ。GUIベースでエージェントを構築できる「AgentCoreハーネス」は直感的な操作性を提供する一方、内部で生成されるコードがプロンプトキャッシュに対応していない。moritalous氏の検証によれば、ハーネスからエクスポートされたコードをそのまま実行しても、キャッシュは機能しない。

この問題の核心は、エクスポートされるPythonコード（Strands Agents）のモデル読み込み部分にある。デフォルトではキャッシュ設定が一切行われておらず、手動で修正を加える必要がある。

具体的な解決手順

ハーネスの作成とエクスポート

まず、AgentCoreコンソール上でハーネスを作成する。クイック作成で十分だ。作成後、画面に表示される「コードへのエクスポート手順を表示」をクリックする。ここで表示されるエクスポート手順には、ハーネスのARNが含まれる。

AgentCore CLI（バージョン0.24.1）をインストールする。

npm install -g @aws/agentcore

次にAgentCoreプロジェクトを作成する。この手順はエクスポート手順には記載されていないが、必須の準備作業となる。

agentcore create myharness

作成時の質問「What would you like to build?」に対しては「Skip」を選択する。プロジェクトディレクトリに移動後、ハーネスをエクスポートする。

cd myharness
agentcore export harness --arn arn:aws:bedrock-agentcore:us-east-1:123456789012:harness/harness_adhn1-V8gQRoqV92

エクスポートが成功すると、app/harness_adhn1Agent/ディレクトリ以下にStrands AgentsベースのPythonコードが生成される。

コードの修正

修正対象はapp/harness_adhn1Agent/model/load.pyだ。このファイルで、モデルクライアントのインスタンス化時にキャッシュ設定を追加する。

まず、インポート文にCacheConfigを追加する。

from strands.models.bedrock import BedrockModel, CacheConfig

次に、load_model関数内でBedrockModelの生成時にパラメータを追加する。

return BedrockModel(
 model_id="global.anthropic.claude-sonnet-4-6",
 cache_tools="default",
 cache_config=CacheConfig(strategy="auto"),
)

cache_tools="default"はツール定義のキャッシュを有効化し、CacheConfig(strategy="auto")は自動戦略でキャッシュを適用する。これにより、Claude Sonnet 4.6との通信においてプロンプトキャッシュが機能するようになる。

デプロイと動作確認

修正後、以下のコマンドでデプロイを実行する。

agentcore deploy

ここで注意すべき点がある。修正したコードは元のAgentCoreハーネスにデプロイすることはできず、AgentCoreランタイムとしてデプロイされる。ランタイム環境で複数回の会話を実行すると、プロンプトキャッシュが正常に機能することが確認できる。

ハーネスとランタイムの機能差

このワークアラウンドは、AgentCoreのアーキテクチャ上の課題を浮き彫りにする。AgentCoreハーネスはStep Functionsとの統合に優れており、ワークフロー内でエージェントを呼び出す用途に適している。一方、AgentCoreランタイムはAPIゲートウェイの背後に設定でき、ガードレール（安全機構）を追加できる点が利点だ。

moritalous氏の指摘では、これらの機能を「統一してほしい」という願望が記されている。ハーネスとランタイムで機能セットが異なることは、ユーザーにとって判断を複雑にする要因となる。プロンプトキャッシュの有効化も、結局はランタイムに移行しなければ実現できないという制約がある。

実運用への示唆

今回の回避策は、AgentCoreの導入を検討するチームにとって重要な知見となる。特に、長いシステムプロンプトや多数のツール定義を持つエージェントを運用する場合、プロンプトキャッシュの有無はコストとレイテンシに直接影響する。各会話でプロンプトの大部分を再送信する状態では、キャッシュ有効時と比較して応答時間が数倍に増加し、API費用も比例して膨らむ。

Strands Agentsの公式ドキュメントでは、Claudeにおけるプロンプトキャッシュの有効化は比較的シンプルな手順で説明されている。AgentCoreのエクスポートコードがデフォルトでこの設定を適用しないのは、フレームワーク側の成熟度の問題と言える。

編集部の見解

短期的には、今回のワークアラウンドがAgentCoreユーザーの間で広く共有される可能性が高い。AWSが公式にこの問題に対応するまでは、コード修正は必須の作業になる。特に、コスト最適化を重視するチームにとって、この回避策の有無はAgentCore採用の判断を左右する要素だ。AgentCoreはまだ急速に進化している基盤であり、プロンプトキャッシュの非対応は早期導入者が直面する典型的なギャップと考えられる。 長期的な視点では、ハーネスとランタイムの機能統合の方向性が注目される。ユーザーは「Step Functionsから呼べるハーネス」と「ガードレールが付けられるランタイム」の二者択一を強いられている。両方の利点を併せ持つ統一基盤が登場すれば、AgentCoreの実用性は大きく向上する。AWSがコミュニティからのフィードバックをどの程度の速度で製品に反映するかが、競合となるGoogle Vertex AI Agent BuilderやAzure AI Agent Serviceとの差別化要因になる。 編集部としては、以下の論点を提起したい。

参考

• 「AgentCoreハーネス、プロンプトキャッシュが効かなくなくなくない？」, by moritalous — Qiita, 2026-07-18T15:35:16.000Z (ARR)
• 元記事URL: https://qiita.com/moritalous/items/03d273f74e6ed63b70c3?utm_campaign=popular_items&utm_medium=feed&utm_source=popular_items