【第4回】Amazon Bedrock AgentCore 入門 — 本番運用に向けたベストプラクティスとよくあるハマりポイント総まとめ

AWS

前回はAgentCore GatewayとMemoryを組み合わせたマルチターン対応エージェントの構築を紹介しました。第4回はシリーズ最終回。いよいよ「本番で動かすとき何に気をつけるか」という話をまとめていきます。

ローカルでは動いてたのに本番でコケる、というのはどんなサービスでもあるあるで、エージェント系のアプリは特にそれが顕著だと思っています。非決定論的な動きをするLLMをベースにしている以上、通常のWebアプリよりも「動いてるっぽいけど実は壊れてる」状態に気づきにくい。そのあたりの話を実体験ベースで書きます。

この記事でわかること

  • AgentCore CLIを使ったデプロイの基本フロー
  • IAMとIdentityまわりのよくある詰まりどころ
  • Observabilityの設定と使いどころ
  • 本番運用で意識したいベストプラクティス
  • 個人的にハマったポイントと回避策

デプロイのフロー：starter-toolkitからAgentCore CLIへ

以前は bedrock-agentcore-starter-toolkit のPython CLIを使うのが一般的でしたが、現在は AgentCore CLI（@aws/agentcore） が推奨になっています。npmパッケージとして配布されていて、Node.js 20+が必要です。最初に知らなくてスターターツールキットを使い続けていたのはここだけの話。

基本的なプロジェクト構成はこんな感じになります。

MyAgent/
├── agentcore/
│   ├── agentcore.json       # エージェント・リソース設定
│   ├── aws-targets.json     # デプロイ先アカウント・リージョン
│   └── cdk/                 # CDKインフラ（自動管理）
└── app/
    └── MyAgent/
        ├── main.py          # エージェントのエントリポイント
        └── pyproject.toml

agentcore.json はエージェント、MemoryStore、Gateway、認証情報などを定義するメインの設定ファイルで、agentcore add や agentcore remove コマンドで管理されます。agentcore deploy を叩くとCDK経由でAWSにデプロイされます。

# インストール
npm install -g @aws/agentcore

# プロジェクト作成（Strands + Claude 3.5 Sonnetの例）
agentcore create --name MyAgent --framework strands

# ローカル開発（ホットリロード付き）
agentcore dev

# デプロイ
agentcore deploy

# 動作確認
agentcore invoke --input "注文履歴を教えて"

agentcore dev はPython仮想環境を作成し、依存関係をインストールして、ホットリロード付きのローカルサーバーを起動し、ブラウザでエージェントインスペクターが開くので、トレースを見ながら開発できます。これが思ったより便利でした。本番デプロイ前にローカルで一通り叩いておくのが正直いちばん効果的な事前確認です。

また、AgentCoreでエージェントを構築するアプローチは2種類あります。Code-based agent（GA）はPythonでエージェントループを書いて AgentCore Runtime にデプロイするもの。Managed harness（プレビュー）はモデル・プロンプト・ツール・メモリを設定ファイルで宣言するだけで、AgentCoreがループを実行してくれるため、フレームワークもオーケストレーションコードも不要です。

IAMとIdentityまわりで詰まりがちなポイント

個人的にいちばんハマったのがここです。AgentCoreのエージェントはIAMロールを「引き受けて」動くので、ロールの設定が甘いとデプロイ自体は成功するのにInvoke時に403が返ってくるという地獄を見ます。

エージェント実行ロールに必要な最低限の権限

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": "arn:aws:bedrock:*::foundation-model/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:GetAgentRuntime"
      ],
      "Resource": "*"
    }
  ]
}

DynamoDBやS3を触るツールをエージェントに持たせる場合は当然それらの権限も追加が必要です。最小権限の原則で、使わないアクションは入れないようにしています。

boto3からエージェントを呼び出す場合は、bedrock-agentcore:InvokeAgentRuntime の権限が必要とされています。デプロイ済みエージェントのARNは agentcore status コマンドで確認できます。

AgentCore Identityでサードパーティ連携する場合

AgentCore Identityは、AIエージェントが、ユーザーに代わって、またはユーザーの事前同意のもとで、AWSサービスやGitHub・Salesforce・Slackなどのサードパーティツールに安全にアクセスできるようにする仕組みです。OAuthフローをAgentCoreが管理してくれるので、トークン管理をエージェントコードに書かなくてよくなります。ただしセットアップが独特で、最初は「これ本当に動いてる？」となりやすい。

認証情報を追加するのはCLIからできます。

# APIキー形式の認証情報を追加
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

そういえば最近、AgentCore Policyというサービスもあるらしく、コンテンツフィルタリングや認可ルールをエージェントレベルで設定できるそうです。まだ自分は本番で使えていないですが、マルチユーザー向けのサービスを作るなら早めに触っておいたほうがよさそうです。

Observabilityの設定：本番では絶対に入れておくべき

AgentCore Observabilityは、あらゆるフレームワーク・モデルを使った本番環境でのエージェントのトレース・デバッグ・パフォーマンス監視を支援するマネージドサービスです。エージェントワークフローの各ステップを詳細に可視化し、実行パスの検査・中間出力の監査・パフォーマンスボトルネックのデバッグが可能です。

Amazon CloudWatchを基盤として、トレース・セッション数・レイテンシー・実行時間・トークン使用量・エラーレートなどのキーメトリクスをリアルタイムで可視化するダッシュボードを提供します。

エージェントは非決定論的に動くため、通常のアプリのデバッグ手法だと「なんか変な答えが返ってくる」の原因特定が非常に難しいです。ステップ実行の可視化なしで本番運用するのは、航空機をレーダーなしで飛ばすようなものです。

OpenTelemetry（OTEL）互換のテレメトリーに対応しており、Arize Phoenix・Amazon CloudWatch・Braintrust・Dynatrace・Datadog・LangfuseなどOTELをサポートする既存の監視ツールと統合できます。CloudWatch Logsへの書き出しはAgentCore CLIでデプロイすると自動的に設定されるようです。カスタムで外部ツールに繋ぎたい場合だけ追加設定が必要です。

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# LangfuseのOTLPエンドポイントに繋ぐ例（ここはプロジェクトごとに要調整）
exporter = OTLPSpanExporter(
    endpoint=os.environ["LANGFUSE_OTLP_ENDPOINT"],
    headers={"Authorization": f"Bearer {os.environ['LANGFUSE_SECRET_KEY']}"}
)
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

正直ここはまだ「とりあえずCloudWatchで見てる」段階なので、もっとスマートなやり方があるのかもしれません。

本番運用で意識したいベストプラクティス（特に刺さったもの）

AWSのブログに「エンタープライズ向けの9つのベストプラクティス」という記事があって、かなり参考になりました。全部は書ききれないので、個人的に刺さったものを抜粋します。

① A/Bテストとトラフィック分割で段階的にロールアウトする

AgentCore Runtimeはバージョニングとトラフィック分割を組み込みでサポートしています。新モデルや異なるプロンプト戦略を試す場合、いきなりすべてを切り替えるのは避けてください。たとえばトラフィックの10%を新バージョンにルーティングし、1週間かけてパフォーマンスを比較します。精度、レイテンシー、コスト、ユーザー満足度を測定し、新バージョンの方が優れていれば段階的にロールアウトします。

「そんな丁寧にやる必要ある？」と思っていたけど、プロンプトをちょっと変えただけで全然違う挙動をすることがあって、考えを改めました。

② 継続的テストパイプラインを組む

すべての更新時に実行される継続的テストパイプラインを構築します。一般的なケースとエッジケースを網羅する代表的なクエリを含むテストを整備します。プロンプトの変更、ツールの追加、モデルの切り替えを行うと、パイプラインがテストを実行して結果をスコアリングします。精度がしきい値を下回った場合、デプロイは自動的に失敗します。

評価まわりは、少なくともAWS CLI側に bedrock-agentcore evaluate のようなコマンドが用意されているので、CIに組み込んでおくと安心です。

③ 本番ドリフトを継続的にモニタリングする

ユーザーのパターンは時間とともに変化します。以前はまれだった質問が頻出するようになったり、新製品がリリースされたり、用語が変わったりします。ライブのインタラクションを継続的にサンプリングし、品質指標に照らしてスコアリングします。ドリフトを検知した場合（例えば、精度が2週間で92%から84%に低下した場合）、根本原因を調査して対処します。

④ コールドスタートを意識した設計にする

AgentCore Runtimeは実際に使用した分だけ課金されます。事前にCPUのコア数やメモリを見積もっておく必要はないとされています。また、LLMの出力を待機する時間などI/O待ち時間はカウントされない仕組みのようです。その反面、コールドスタートが発生することがあります。レイテンシーが許容できないユースケースでは、セッションを維持する工夫や、EventBridgeで定期的にウォームアップリクエストを入れる設計を検討する価値があります。

よくハマるポイントまとめ

最後に、実際に詰まったところを雑にまとめておきます。

  • リージョン問題：AgentCoreが使えるリージョンは限られています。2026年5月現在、東京リージョンはAgentCore Runtimeなど多くの機能で対応していますが、Managed harness（プレビュー）は東京リージョンがまだ対象外なので注意が必要です。
  • Node.js依存：AgentCore CLIはnpmパッケージとして配布されており、Node.js 20+が必要です。Pythonだけでいけるつもりでいると環境を揃えるところから始まります。
  • CDKのバージョン：デプロイにAWS CDKを使うので、CDKのバージョンが古いとエラーになることがあります。npm install -g aws-cdk で最新版にしておくのが無難です。
  • Memoryのネームスペース設計：MemoryはセッションIDとユーザーIDで管理されますが、ここの設計を最初に決めておかないと後から変えるのが大変です。特にマルチユーザー対応する場合は注意。
  • starter-toolkitは「レガシー」扱い：starter-toolkitは既存のPythonベースのワークフロー向けには引き続き利用可能ですが、新規プロジェクトの推奨起点ではなくなっています。新しく始める場合はAgentCore CLIを使いましょう。

シリーズを終えて

4回にわたって書いてきたAgentCore入門、最終回は少し駆け足になりましたが、Runtime→Memory→Gateway→本番運用という流れで一通りカバーできたかなと思います。自分自身も書きながら整理できた部分が多かったです。

AgentCoreはまだ進化の途中で、AgentCore CLIが推奨になったのも最近の話ですし、Managed Harnessはまだプレビュー中です。半年後にはまた書き直しが必要になりそうな気もしていますが、それはそれで楽しみです。

※この記事にはプロモーションが含まれます

ちなみに、お名前.com レンタルサーバー（WordPressに特化した高速レンタルサーバー。月額990円〜、独自ドメイン実質0円）も気になっています。お名前.com レンタルサーバー

📚 シリーズ「Amazon Bedrock AgentCore 入門」（第4回 / 全4回）

← 前回の記事: 前回の記事はこちら

🎉 このシリーズは今回で完結です！

参考になったらクリックしてもらえると嬉しいです!

Blogmura CloudAWS Ranking
タイトルとURLをコピーしました