AWS AgentCore導入時の障害とデバッグの教訓
- •AWS Bedrock AgentCoreのデプロイで、開発者が5日間におよぶ予期せぬ障害のトラブルシューティングを経験した。
- •IAM権限の欠如により、エージェントの呼び出しが失敗してもシステムがHTTP 200 OKを返してしまう問題が発生した。
- •コンテナ実行環境において、ドキュメント化されていないUID 1000の指定が必要であるという仕様が開発を阻害した。
開発者のサルヴァル・ナダフ(Sarvar Nadaf)は、2026年7月にCrewAIのレジュメ添削エージェントをAmazon Bedrock AgentCoreランタイムへデプロイした際、4つの重大なサイレント障害に直面した。このプロジェクトでは、CrewAIによるエージェントオーケストレーションと、LLMタスクにおけるBedrock Nova Proの利用が行われた。AWSへの展開時、エラーログの欠如や誤解を招くシステム信号により、原因究明に5日間の工数を費やすことになった。
第一の失敗は、PyPI上で公開されている「bedrock-agentcore-client」というプレースホルダーパッケージに起因する。このパッケージはインストール可能だが実際のSDK機能を含んでおらず、本来は「amazon-agent-runtimes」ドメイン下のプライベートなAWS CodeArtifactレジストリから取得する必要がある。誤ったパッケージの使用は、コンテナビルド中に明示的なエラーを出さず、呼び出しペイロードが空になる事態を招いた。
第二に、IAM権限「bedrock:GetAgentRuntime」が不足していても、呼び出しエンドポイントが空のペイロードとともにHTTP 200 OKを返した。サービスはリクエストを受け入れるものの実行先へルーティングせず、CloudWatchにも原因を示すログが一切記録されなかった。第三に、Dockerfileに「USER 1000」ディレクティブが欠けていたため、コンテナが起動直後にログを吐かずにクラッシュした。AgentCoreはコンテナのUID 1000での実行を義務付けており、公式ドキュメントではなくサンプルリポジトリの分析を通じて初めて判明した仕様であった。
最後に、コントロールプレーンが名前のハイフンを拒否する正規表現を課しており、CLIとコンソールインターフェース間でバリデーション結果に矛盾が生じた。さらに、管理用の「bedrock-agentcore-control」とランタイム用の「bedrock-agentcore」という、名称が紛らわしい2つのPythonクライアントが混在していることも判明した。ナダフは、このようなサイレント障害を検知するためにSentryなどの可観測性ツールが不可欠であり、HTTP 200 OKを過信せずレスポンスボディの検証を徹底すべきだと提言している。