agents-debug

debug

AgentCore エージェントまたは環境が正しく動作しない原因を診断します。

使用する場面

• エージェントが間違った回答を返したり、エラーが発生したりする
• ツール呼び出しが失敗したり、タイムアウトしたりする
• エージェントがローカルでは動作するのに、デプロイ後は失敗する
• CloudWatch にログが表示されない
• AgentCore CLI が動作しない、または環境に問題があるように見える
• agentcore コマンドが見つからない、または前提条件が不足している

次の用途には使用しないでください：

• デプロイの失敗（CDK エラー、デプロイ時の IAM）→ agents-deploy を使用
• 新しいプロジェクトの足場作り → agents-get-started を使用
• 品質の測定やモニタリングのセットアップ → agents-optimize を使用

入力

$ARGUMENTS は省略可能です：

/agents-debug                      # interactive — describe what's wrong
/agents-debug traces               # read and explain recent traces
/agents-debug logs                 # search recent logs for errors
/agents-debug memory               # diagnose memory recall issues specifically
/agents-debug doctor               # check environment prerequisites

手順

ステップ 0：問題の種類を特定する

開発者の問題が CLI 自体（コマンドが見つからない、前提条件、環境のセットアップ）に関する場合は、references/doctor.md を読み込み、そこに記載された診断チェックリストに従ってください。

問題がエージェントの動作（間違った回答、エラー、タイムアウト、ツールの失敗）に関する場合は、以下のステップ 1 に進んでください。

ステップ 1：CLI のバージョンを確認する

agentcore --version を実行します。このスキルには v0.9.0 以降が必要です。バージョンが古い場合は、先に agentcore update を実行するよう開発者に伝えてください。

ステップ 2：症状を把握する

次のように質問します（または、文脈から推測します）：

「何が起きていますか？

1. エージェントがエラーメッセージを返す
2. エージェントが間違った回答、または役に立たない回答を返す
3. 特定のツール呼び出しが失敗する
4. メモリが機能しない（エージェントが情報を記憶しない）
5. エージェントの応答が遅い、またはタイムアウトする
6. 特定のセッションでエージェントが何をしたのか知りたい」

ステップ 3：トレースとログを自動的に読み取る

開発者にログの貼り付けを求めず、直接読み取ってください。

# List recent traces
agentcore traces list --runtime <AgentName> --since 1h

# Get the most recent trace ID
agentcore traces list --runtime <AgentName> --since 1h --limit 1

# Download and read the trace
agentcore traces get <traceId> --runtime <AgentName>

# Search logs for errors
agentcore logs --runtime <AgentName> --since 1h --level error

# Search logs for a specific pattern
agentcore logs --runtime <AgentName> --since 2h --query "timeout"
agentcore logs --runtime <AgentName> --since 2h --query "model access"

重要： CloudWatch の書き込みから取得までのレイテンシはエンドツーエンドで約 10 秒です。これは、スパンが出力されてから agentcore traces get または agentcore run eval で読み取り可能になるまでの遅延です。「トレースは取り込まれたが、評価はまだ準備中」という別個の時間帯はありません。同じ取り込み処理によって、どちらの経路も利用可能になります。以前のスキルやドキュメントには、トレースは 30～60 秒、評価は 2～5 分と記載されていましたが、いずれも古い情報です。エージェントを呼び出した直後であれば、約 15 秒待つと、トレースの読み取りと評価の両方が可能になります。

エージェント名が指定されていない場合は、agentcore/agentcore.json を読み取ってください。

ステップ 4：症状に応じて診断する

---

症状：「model access denied」またはモデルエラー

最も一般的な原因： お使いのリージョンで、Bedrock コンソールのモデルが有効になっていません。

対処方法：

1. AWS コンソール → Amazon Bedrock → Model access に移動します
2. エージェントが使用するモデルを有効にします
3. アクセスが反映されるまで 1～2 分待ちます

2 番目の原因： 実行ロールに bedrock:InvokeModel がありません。

確認方法：

aws iam simulate-principal-policy \
  --policy-source-arn $(agentcore status --json | jq -r '.runtimes[0].executionRoleArn') \
  --action-names bedrock:InvokeModel \
  --resource-arns "arn:aws:bedrock:*::foundation-model/*"

3 番目の原因： クロスリージョン推論プロファイルでは、すべてのリージョンでモデルへのアクセスが必要です。

地理的なプレフィックスで始まるモデル ID は、該当する地理的範囲内でリクエストをルーティングするクロスリージョン推論プロファイルです：

プレフィックス	地理的範囲	宛先リージョンの例
us.	米国	us-east-1, us-east-2, us-west-2
eu.	欧州	eu-central-1, eu-west-1, eu-west-2, eu-west-3
apac.	アジア太平洋	ap-northeast-1, ap-southeast-1, ap-southeast-2, ap-south-1
global.	世界中のすべての商用リージョン	サポートされているすべてのリージョン

AgentCore CLI では、デフォルトで global. が設定されます（例：global.anthropic.claude-sonnet-4-5-20250929-v1:0）。すべてのプレフィックスで、そのプロファイルが対象とするすべての宛先リージョンにおいて、モデルへのアクセスを有効にする必要があります。us. プロファイルではすべての米国リージョン、eu. ではすべての EU リージョン、global. ではサポートされているすべてのリージョンで有効にしてください。すべてのモデルがすべてのプレフィックスをサポートしているわけではありません。現在、global. は一部のモデルでのみ利用できます。利用可能な場合はスループットを最大化するために global. を使用するか、推論を実行できる場所にデータ所在地の要件がある場合は地理的なプレフィックスを使用してください。モデルとプレフィックスの現在の対応状況については、Bedrock の推論プロファイルに関するドキュメントを確認してください。

症状：ツール呼び出しが失敗する

手順 1： トレースで失敗したツール呼び出しを探します。

agentcore traces get <traceId> --runtime <AgentName>

エラーステータスのツール呼び出しエントリを探してください。

手順 2： ゲートウェイのステータスを確認します。

agentcore status --type gateway
agentcore fetch access --name <AgentName> --type agent

手順 3： ツール呼び出しでよくある失敗：

ゲートウェイ URL が設定されていない（ローカル開発）： AGENTCORE_GATEWAY_*_URL 環境変数はデプロイ後にのみ設定されます。agentcore dev ではゲートウェイツールを使用できません。これは想定どおりの動作です。エージェントはこの状況を適切に処理する必要があります。

ツール呼び出し時の認証失敗：

agentcore logs --runtime <AgentName> --since 1h --query "auth"

認証情報が正しく設定されていることを確認します：agentcore status --type credential

Lambda 関数のエラー： Lambda 自体でエラーが発生しています。Lambda のログを直接確認します。

aws logs tail /aws/lambda/<function-name> --since 1h

ポリシーによる拒否： ポリシーエンジンが接続されている場合は、ポリシー判定ログを確認します。

agentcore logs --runtime <AgentName> --since 1h --query "policy"
agentcore status --type policy-engine

---

症状：回答が間違っている、または役に立たない

手順 1： トレースを読み、エージェントの推論を確認します。

agentcore traces get <traceId> --runtime <AgentName>

トレースには、モデルの推論手順、実行されたツール呼び出し、最終応答が表示されます。次の点を確認してください。

• エージェントは適切なツールを使用しましたか？
• ツール呼び出しで期待どおりのデータが返されましたか？
• システムプロンプトに適切なコンテキストが指定されていますか？

手順 2： メモリが関係しているかどうかを確認します。 エージェントがメモリのコンテキストを使用するはずなのに使用していない場合は、このスキル内の後述の「症状：メモリが保持されない」セクションを参照してください。環境の問題であれば、references/doctor.md を読み込んでください。

手順 3： よくある原因：

• システムプロンプトが曖昧すぎる、または重要なコンテキストが不足している
• エージェントが適切なツールを呼び出していない（ツールの説明を改善する必要がある）
• ツールから予期しない形式のデータが返されている
• タスクに対してモデル ID が適切でない（例：複雑な推論に小型モデルを使用している）

---

症状：メモリが機能しない

セッションをまたいでメモリが保持されない（LTM）：

1. LTM 戦略（SEMANTIC または USER_PREFERENCE）が設定されていることを確認します。

agentcore status --type memory --json | jq '.memories[].strategies'

1. セッション終了後、5～30 秒待ちます。LTM の抽出は非同期です。事実が抽出される前に、エージェントのセッションが終了している必要があります。

2. セッション ID に UUID（v4）を使用します。プラットフォームでは 33 文字以上が必要です。「session-1」のような短い ID を使うと、LTM はエラーを表示せずに失敗します。agentcore invoke はデフォルトで要件を満たす ID を生成します。

3. メモリリソースが ACTIVE であることを確認します。

agentcore status --type memory

セッション開始時にメモリが読み込まれない：

1. MEMORY_*_ID 環境変数が設定されていることを確認します。

agentcore status --type memory --json | jq '.memories[].id'

1. セッション間で actor_id が一貫していることを確認します。メモリはアクターごとにスコープが設定されています。

2. 検索設定の名前空間パスが、書き込み時に使用した名前空間と一致していることを確認します。

---

症状：エージェントがタイムアウトする

手順 1： トレースで時間がかかっている箇所を確認します。

agentcore traces get <traceId> --runtime <AgentName>

時間のかかっている処理（モデル呼び出し、ツール呼び出し、メモリ操作）を探してください。

手順 2： タイムアウトのよくある原因：

エージェントの初期化が遅い： アイドル期間後の初回呼び出しは遅いものの、その後のリクエストが速い場合、エージェントの初期化に時間がかかりすぎています。モジュールレベルでの重いインポート、グローバルスコープでのデータベース接続、起動時の MCP クライアント初期化を確認してください。負荷の高いセットアップはリクエストハンドラーに移すか、遅延初期化を使用してください。最適化の手引きについては、agents-harden スキルを参照してください。

モデル呼び出しのタイムアウト： モデルの処理に時間がかかりすぎています。時間が重要な処理では、より高速なモデルの使用を検討してください（例：単純なタスクには Sonnet ではなく Haiku を使用）。

ツール呼び出しのタイムアウト： Lambda または外部 API の応答が遅れています。ツール自体のログを確認してください。

メモリ検索のタイムアウト： メモリストアが大きい場合、セマンティック検索に時間がかかることがあります。検索設定の top_k を小さくすることを検討してください。

VPC 接続の問題： エージェントが VPC 内にある場合は、セキュリティグループのルールとルートテーブルを確認してください。VPC 固有のデバッグについては、agents-build（references/vpc.md を読み込みます）を参照してください。

症状：ServiceQuotaExceededException: maxVms limit exceeded（観測された同時実行数が少ないにもかかわらず発生）

CloudWatch の「同時セッション」メトリクスは控えめな数値（おそらく 30～50）を示しているのに、InvokeAgentRuntime の呼び出しで ServiceQuotaExceededException: maxVms limit exceeded が返されます。

実際に起きていること： CloudWatch の同時セッション数メトリクスは、稼働中のマイクロ VM 数と同じではありません。maxVms クォータでは、呼び出しを終えたものの、まだ解放されていない環境も含め、アカウントでアクティブなすべての環境がカウントされます。アイドル状態でもまだ解放されていない環境は、idleRuntimeSessionTimeout（デフォルトは 900 秒／15 分）が経過するか、明示的に停止するまでクォータを消費します。

リクエストごとに新しいセッション ID を使い、StopRuntimeSession を呼び出していない場合、リクエストのたびに環境がアイドル状態のまま 15 分間残り、クォータを消費します。

対処する順序（クォータの引き上げを申請する前に、この順に試してください）：

1. 論理的なリクエストが完了したら、毎回 StopRuntimeSession を呼び出します。 このセッションでこれ以上リクエストを送らない場合は、明示的に停止してください。

   client.stop_runtime_session(
       agentRuntimeArn=runtime_arn,
       runtimeSessionId=session_id,
   )
   

2. 関連するリクエスト間でセッション ID を再利用します。 ユーザーとのやり取りから複数のバックエンド呼び出しが発生する場合は、呼び出しごとに新しいセッション ID を生成するのではなく、同じセッションにルーティングしてください。

3. idleRuntimeSessionTimeout を短くします。 セッションの有効期間が短く、すべての箇所に StopRuntimeSession を追加できない場合は、agentcore/agentcore.json のランタイムの lifecycleConfiguration を編集し、agentcore deploy を実行してタイムアウトを短くしてください。

4. 上記を試した後でのみ、クォータの引き上げを申請してください。 agents-harden（references/limits.md を読み込みます）を参照してください。申請先は Service Quotas コンソール（Amazon Bedrock AgentCore）です。サポートチケットを直接送信しないでください。

詳しいパターンについては、agents-harden の「セッションのライフサイクル管理」セクションを参照してください。

---

症状：invoke で 424 Failed Dependency が発生する

通常、エージェントコンテナの起動に失敗したか、初期化中にクラッシュしたことを意味します。

ステップ 1： エージェントのログで起動エラーを確認します。

agentcore logs --runtime <AgentName> --since 30m --level error

ステップ 2： よくある原因：

Python 依存関係の不足： エージェントのコードが、pyproject.toml に含まれていないパッケージをインポートしています。コンテナは起動しますが、最初のリクエストでクラッシュします。対処法：依存関係を追加して、再デプロイしてください。

エントリポイントのクラッシュ： main.py がインポート中または app.run() の実行中に例外をスローしています。トレースバックをログで確認してください。

コンテナイメージのプル失敗： Container ビルドを使用している場合、ECR イメージが存在しないか、実行ロールに ecr:BatchGetImage 権限がない可能性があります。以下を確認してください。

agentcore status --runtime <AgentName> --json

メモリーリソースが ACTIVE ではない： エージェントのコードがメモリーを利用できることを前提としている一方で、メモリーリソースがまだ CREATING 状態の場合、エントリポイントが失敗することがあります。以下を確認してください。

agentcore status --type memory

初期化のタイムアウト： エージェントが最初のリクエストを受け付けられる状態になるまでに時間がかかりすぎています。モジュールレベルでの重いインポート、同期的なデータベース接続、起動時の MCP クライアント初期化などによって、サービスのヘルスチェック時間を超えることがあります。最初の invoke で 424 が発生する一方、その後の呼び出しは正常に動作するという症状が見られます。対処法：負荷の高いセットアップをモジュールレベルから移動し、遅延初期化を使うか、本番トラフィックを受ける前にエージェントをウォームアップしてください。パターンについては、agents-harden の「初期化にかかる時間」セクションを参照してください。

---

症状：ローカルでの呼び出しが接続拒否／終了コード 7 で失敗する

通常、これはエージェントのバグではありません。開発サーバーが想定とは異なるポートで動作しています。

agentcore dev がバインドするデフォルトのポート：

プロトコル	デフォルト
HTTP	8080
MCP	8000
A2A	9000

デフォルトのポートが使用中の場合（2 つ目の開発セッション、前回の実行から残っているプロセス、8080 を使用している別のサービスなど）、CLI は警告なしにポート番号を自動で増やします：8080 → 8081 → 8082。8080 に固定されたテストハーネスや curl スクリプトは、エージェントが 8082 で正常に動作していても「Connection refused」（curl の終了コード 7）になります。

次の順序で原因を特定してください。

1. agentcore dev が出力する CLI のバナーを確認します。実際にバインドされたポートと URL が表示されます。これが常に正確な情報源です。

2. バナーが表示されなくなった場合（ターミナルをクリアした、バックグラウンドで実行しているなど）は、ログファイルを確認します。

   tail -20 agentcore/.cli/logs/dev/*.log
   

3. または、プロセスを直接見つけます。

   # macOS / Linux
   ps aux | grep -E 'agentcore dev|uvicorn' | grep -v grep
   lsof -iTCP -sTCP:LISTEN -n -P | grep -E '8080|8081|8082|8000|9000'
   

解決方法：

• ポートを明示的に固定します：agentcore dev --port 8080
• デフォルトのポートを占有しているプロセスを終了します：lsof -tiTCP:8080 -sTCP:LISTEN | xargs kill
• テストハーネスで固定されているポートを、CLI の出力または環境変数から読み取るように変更します

「ある日はローカルで動くのに、翌日は失敗する」という報告でも、この問題がよく原因になります。実行ごとにポートが変わっているためです。

---

症状：ゲートウェイのツール呼び出しが認証エラーで失敗する

手順 1： 認証タイプがターゲットタイプと一致していることを確認します。ターゲットに対して誤った送信時認証を使用するのが、最もよくあるゲートウェイエラーです。

ターゲットタイプ	有効な送信時認証
mcp-server	none、oauth、または IAM（API 経由の SigV4）
lambda-function-arn	IAM のみ（自動）
open-api-schema	oauth または api-key（必須）
api-gateway	none、api-key、または IAM
smithy-model	IAM または oauth

手順 2： OAuth トークンの有効期限が切れていないか確認します。ゲートウェイターゲットが OAuth を使用している場合、アクセストークンの有効期限が切れている可能性があります。認証関連のエラーを確認します。

agentcore logs --runtime <AgentName> --since 1h --query "auth"
agentcore logs --runtime <AgentName> --since 1h --query "401"
agentcore logs --runtime <AgentName> --since 1h --query "403"

トークンの有効期限が切れている場合は、OAuth 認証情報プロバイダーのトークンエンドポイントに到達できることと、クライアント認証情報が引き続き有効であることを確認します。OAuth を使用する MCP サーバーターゲットでは、ゲートウェイがトークンの更新を自動的に処理します。更新に失敗する場合は、認証情報プロバイダーの設定が誤っている可能性があります。

手順 3： 認証情報が設定されていることを確認します。

agentcore status --type credential
agentcore status --type gateway --json

---

症状：トレースが表示されない

約 15 秒待ちます。呼び出しからトレースが利用可能になるまで、短い遅延（通常は約 10 秒）があります。

約 30 秒待ってもトレースが表示されない場合：

1. エージェントのデプロイ時にオブザーバビリティが有効になっていたことを確認します
2. エージェントが実際に呼び出されたことを確認します：agentcore logs --runtime <AgentName> --since 1h
3. 実行ロールの CloudWatch 権限を確認します

---

症状：CloudWatch のログが表示されない

これは、特に Container／Docker ビルドで最もよくあるオブザーバビリティの問題です。

AgentCore は未加工の stdout をキャプチャしません。OpenTelemetry を使ってログを CloudWatch に送信します。次の 3 つすべてが満たされている必要があります。

1. エントリーポイントが opentelemetry-instrument でラップされていること。

CodeZip ビルドでは自動的に設定されます。Docker／Container ビルドでは手動で追加する必要があります。これを忘れるケースが最もよくあります。

Dockerfile の CMD に追加します。

# ✅ Correct — wrapped with opentelemetry-instrument
CMD ["opentelemetry-instrument", "python", "main.py"]

# ❌ Wrong — no OTEL wrapper, logs won't appear
CMD ["python", "main.py"]

2. ランタイムの IAM ロールに CloudWatch と X-Ray の権限があること：

logs:CreateLogGroup
logs:CreateLogStream
logs:PutLogEvents    → scoped to /aws/bedrock-agentcore/runtimes/*
xray:PutTelemetryRecords
xray:PutTraceSegments → scoped to *

AgentCore CLI と CodeZip を使用する場合、CDK のスキャフォールドがこれらを自動的に追加します。カスタムロールまたは Container ビルドを使用する場合は、必要な権限が含まれていることを確認してください。

3. print() ではなく Python の logging モジュールを使用すること。

OTEL は自動的に logging と連携するため、カスタムハンドラーは必要ありません。print() 文は CloudWatch に表示されません。

import logging
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

# ✅ This appears in CloudWatch
logger.info("Processing request")

# ❌ This does NOT appear in CloudWatch
print("Processing request")

また、次の点も確認してください： アカウントで CloudWatch Transaction Search が有効になっていること。有効でない場合、GenAI オブザーバビリティダッシュボードにトレースとスパンが表示されません。

Terraform／CDK／IaC でデプロイしたランタイムのログが表示されない

よくあるパターンとして、Terraform、CDK、またはカスタム IAM ロールを使ってデプロイしたランタイムが正常に動作して応答を返すものの、CloudWatch のログストリームが表示されないことがあります。同じエージェントコードを AgentCore Console からデプロイすると、ログは正常に記録されます。

これはほとんどの場合、IAM のスコープ設定の問題です。Console からデプロイしたランタイムの実行ロールには、デフォルトで幅広い CloudWatch 権限が付与されます。一方、IaC テンプレートでは、これらの権限の範囲を /aws/bedrock-agentcore/runtimes/* に限定していることが多く、ログストリームの作成に失敗します。

解決方法： logs:DescribeLogGroups の Resource は、スコープを限定せず "*" にする必要があります。他のログ関連アクションは、ランタイムのロググループにスコープを限定できます。

{
  "Effect": "Allow",
  "Action": [
    "logs:DescribeLogGroups"
  ],
  "Resource": "*"
},
{
  "Effect": "Allow",
  "Action": [
    "logs:CreateLogGroup",
    "logs:CreateLogStream",
    "logs:PutLogEvents"
  ],
  "Resource": "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/bedrock-agentcore/runtimes/*:*"
}

実行ロールの IAM ポリシーを更新したら、agentcore deploy でランタイムを再デプロイし、新しい権限を適用してください。

---

症状：ストリーミング接続が応答の途中で切断される

エージェントが SSE またはロングポーリング形式の応答を使用しており、ストリームの途中で接続が切断されます。クライアントコードでの症状：

• RemoteProtocolError: peer closed connection without sending complete message body
• ストリームの反復中に IncompleteRead 例外が発生する
• エラーも [DONE] イベントもなく、応答が突然停止する
• 複数のツールを使用する会話（連続するツール呼び出しが 5 回以上）で発生する
• クライアント側のタイムアウトよりかなり前に失敗する

根本原因： ストリーミング接続に対するインフラストラクチャ層のアイドルタイムアウトです。応答ストリーム上で数分間データが流れない場合（たとえば、ツールの実行中にデータが送信されない時間がある場合）、ランタイムの前段にあるロードバランサーが TCP 接続を切断します。

タイムアウトの対象は、リクエスト全体の所要時間ではなく、ストリームを流れるデータです。定期的にバイトを送信している限り、接続は維持されます。

解決方法：長時間実行されるツールの実行中に、キープアライブイベントを送信します。

ストリーミングエントリーポイントでの Python のパターン：

import asyncio
import json
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

async def emit_keepalive(tool_task):
    """Yield heartbeat events every 30s while tool_task is running."""
    while not tool_task.done():
        yield f"data: {json.dumps({'type': 'heartbeat'})}\n\n"
        try:
            await asyncio.wait_for(asyncio.shield(tool_task), timeout=30)
        except asyncio.TimeoutError:
            continue  # tool still running, emit another heartbeat

@app.entrypoint
async def invoke(payload, context):
    async def stream():
        tool_task = asyncio.create_task(run_long_tool(payload))

        # Emit heartbeats while the tool runs
        async for event in emit_keepalive(tool_task):
            yield event

        # Tool completed — emit the real result
        result = await tool_task
        yield f"data: {json.dumps({'type': 'result', 'content': result})}\n\n"
        yield "data: [DONE]\n\n"

    return stream()

ハートビートの間隔は約 30 秒に設定してください。間隔が長すぎるとアイドルタイムアウトに達するおそれがあり、短すぎると帯域幅を無駄に消費します。

クライアント側では、ハートビートイベントをユーザーに表示する前にフィルタリングしてください。

for chunk in response.iter_lines():
    if not chunk:
        continue
    data = json.loads(chunk.removeprefix(b"data: "))
    if data.get("type") == "heartbeat":
        continue  # ignore keepalives
    # process real events

代替方法：SDK の非同期タスク API を使って、結果を待たないパターンを実装します。 クライアントが結果を待つ必要がない場合は、add_async_task／complete_async_task でタスクを登録し、呼び出しへの応答をすぐに返します。詳しくは「agents-harden」の「長時間実行されるバックグラウンドタスク」セクションを参照してください。

---

症状：並行するエージェント呼び出しのトレースが統合されて表示される

一意の runtimeSessionId を使って複数のエージェント呼び出しを並行して実行しているのに、AI Observability ダッシュボードではそれらが 1 つのセッションとしてグループ化され、個別の実行を切り分けられません。データプレーンのログでは、セッション ID がリクエスト ID と 1 対 1 で正しく一意になっていますが、トレースビューでは依然として統合されて表示されます。

最も一般的な原因：呼び出し元で Active Tracing が有効になっていないため、上流のスパンが Sampled=0 で届いています。 AgentCore はデフォルトで、上流のトレースサンプリングの判断に従います。親コンテキストが「サンプリングしない」と示している場合、スパンが破棄され、ダッシュボード上で並行する呼び出しが統合されて表示されることがあります。

呼び出し元の種類ごとの解決方法：

Lambda 呼び出し元： Lambda 関数で Active Tracing を有効にします。

aws lambda update-function-configuration \
  --function-name my-caller-function \
  --tracing-config Mode=Active

または Lambda コンソールで、「設定」→「モニタリングと運用ツール」→「AWS X-Ray」→「アクティブトレース」を選択します。

ECS／EC2／コンテナの呼び出し元： AWS X-Ray SDK を初期化し、AgentCore への送信呼び出しが計測されるようにします。Python の場合は aws-xray-sdk を使い、SDK にパッチを適用します。

from aws_xray_sdk.core import xray_recorder, patch_all
patch_all()  # patches boto3, requests, etc.

X-Ray を使用しない直接 SDK 呼び出し元： 上流のトレースを有効にできない場合は、エージェントに環境変数を設定して、ランタイムがサンプリングするように強制します。

OTEL_TRACES_SAMPLER=always_on

これにより、親コンテキストのサンプリング判断にかかわらず、ランタイムはすべてのトレースをサンプリングします。トレードオフとしてトレースのコストは高くなりますが、トレースは正しく記録されます。

こちらも確認：エージェント ARN ではなくエンドポイント ARN で呼び出していないか

トレースに子スパンのない最上位の AgentCore.Runtime.Invoke スパンが 1 つだけ表示される場合は、呼び出し元が使用している ARN を確認してください。呼び出し対象には、エージェントランタイム ARN を指定する必要があります。

arn:aws:bedrock-agentcore:<region>:<account>:runtime/<runtime-name>

エンドポイント ARN ではありません。

arn:aws:bedrock-agentcore:<region>:<account>:runtime/<runtime-name>/runtime-endpoint/DEFAULT

エンドポイント ARN で呼び出すと、完全なトレースの計測パスを経由しないことがあります。これは見落としやすい問題です。どちらの ARN でも呼び出しは成功しますが、完全なトレースが生成されるのはエージェント ARN のみです。

---

症状：ランタイムが何時間も DELETING のままになる

DeleteAgentRuntime を呼び出して成功レスポンス（status: DELETING）を受け取った後、ランタイムが 30 分以上その状態のままになっています。デフォルトエンドポイントを別途削除しようとすると、ConflictException: Default endpoints are removed when you delete the agent. が返されます。

何が起きているのか： 削除ワークフローがサービス側で停止しています。DeleteAgentRuntime を再試行しても解決しません。呼び出しはすぐに成功し（DELETING を返します）が、停止しているのはバックエンドのワークフローです。お客様側のツールで強制的に完了させることはできません。

対処方法：

1. 再試行を続けないでください。 ワークフローの停止は解消されません。
2. https://console.aws.amazon.com/support で AWS Support ケースを作成してください。次の情報を含めます。
   • AWS アカウント ID
   • リージョン
   • ランタイム ARN（または agentRuntimeId）
   • 元の DeleteAgentRuntime 呼び出しの requestId とタイムスタンプ（CloudTrail から確認）
   • ランタイムが DELETING 状態になってからの経過時間
3. その間は回避策を利用してください。 作業を続ける必要がある場合は、別の名前で新しいランタイムをデプロイします。停止したリソースによって作業が妨げられないようにしてください。

削除が停止したことで残されたリソース（ENI、ワークロード ID）は、同じサポートケースの一環として、サービスチームによる手動クリーンアップが必要になる場合があります。

---

フレームワーク固有の問題

LangGraph — モデル形式： 以前のバージョンの langchain-aws では、クロスリージョンのプレフィックスを付けずにモデル ID を指定する必要がありました。最近のバージョンではクロスリージョン推論プロファイルに対応している場合があります。インストール済みのバージョンを確認してください。

pip show langchain-aws | grep Version

LangGraph でモデルエラーが発生する場合は、プレフィックスのない ID を試してください。

# If cross-region prefix errors in your langchain-aws version:
llm = init_chat_model("anthropic.claude-sonnet-4-5-20250929-v1:0", model_provider="bedrock_converse")

# If your version supports cross-region profiles (us. = US, eu. = Europe, apac. = Asia Pacific, global. = worldwide):
llm = init_chat_model("global.anthropic.claude-sonnet-4-5-20250929-v1:0", ...)

現在の langchain-aws のリリースノート（https://github.com/langchain-ai/langchain-aws/releases）で確認してください。クロスリージョン推論プロファイルへの対応は現在も進化しています。

Google ADK — Gemini のみ： ADK は Gemini モデルでのみ動作します。ADK でモデルエラーが発生する場合は、GEMINI_API_KEY が設定されていることと、gemini-* モデル ID を使用していることを確認してください。

A2A エージェント — ポートが違う： A2A サーバーはポート 9000 で実行する必要があります。A2A エージェントが応答しない場合は、誤って 8080 で実行されていないか確認してください。

---

トレースの読み方

トレースには、1 回のエージェント呼び出しの実行経路全体が表示されます。主なセクションは次のとおりです。

• モデル呼び出し — モデルへの指示と、その応答
• ツール呼び出し — 呼び出されたツール、入力、返された値
• メモリ操作 — メモリから読み取られた内容と、メモリに書き込まれた内容
• ポリシー判断 — 許可または拒否された操作（ポリシーエンジンがアタッチされている場合）
• レイテンシの内訳 — 各コンポーネントにかかった時間

# Download trace to a file for detailed inspection
agentcore traces get <traceId> --runtime <AgentName> --output trace.json
cat trace.json | jq '.trace.orchestrationTrace.modelInvocationOutput'

出力

• 特定の障害の診断と根本原因
• 具体的な修正コマンドまたはコード変更
• トレースを確認する場合は、トレースの内容の説明
• 修正が debug の対象外である場合は、適切なスキルへの引き継ぎ

診断後 — 引き継ぎ

根本原因を特定したら、修正を担当するスキルに引き継ぎます。

根本原因	引き継ぎ先	詳細
メモリの設定ミス（誤った戦略、名前空間、接続）	agents-build	references/memory.md を読み込みます
アプリからのエージェント呼び出しが機能しない（認証、URL、ストリーミング）	agents-build	references/integrate.md を読み込みます
VPC 接続（RDS に接続できない、インターネットに接続できない、AZ エラー）	agents-build	references/vpc.md を読み込みます
マルチエージェントの委任が機能しない	agents-build	references/multi-agent.md を読み込みます
カスタムリクエストヘッダーがエージェントのコードに届かない	agents-build	references/request-headers.md を読み込みます
別のアカウントのアプリからのクロスアカウント呼び出し	agents-build	references/integrate.md（クロスアカウントのセクション）を読み込みます
Gateway 認証の設定ミス（401、認証タイプの誤り）	agents-connect	Gateway 認証マトリックス
Gateway のターゲットタイプに関する質問（Lambda、OpenAPI、MCP、API Gateway のいずれか）	agents-connect	「Gateway とは何か、何ではないか」のセクション
ポリシーによる予期しない拒否（Cedar、ツールへのアクセス拒否）	agents-connect	references/policy.md を読み込みます
可観測性が未設定（ログがない、トレースが表示されない）	agents-optimize	references/observability.md を読み込みます
コールドスタート／初期化が遅すぎる	agents-harden	初期化時間のセクション
セッションのライフサイクル／maxVms／StopRuntimeSession	agents-harden	セッションのライフサイクル管理のセクション
長時間実行されるバックグラウンドタスクが再要求される	agents-harden	長時間実行されるバックグラウンドタスクのセクション
JWT インバウンド認証の失敗（403、allowedClients／allowedAudience、発行者の不一致）	agents-harden	インバウンド認証のセクション
スロットリング／クォータエラー／上限引き上げリクエスト	agents-harden	references/limits.md を読み込みます
デプロイ成果物が古い、またはバージョンが誤っている	agents-deploy	再デプロイのワークフロー
環境の不具合（CLI、認証情報、Node、uv）	references/doctor.md を読み込みます	このスキル内で完結します

診断結果を明確に伝え、次に使用するスキルを開発者に案内してください。同じセッション内でエージェントが参照先のスキルを読み込める場合は、読み込んでください。