故障診斷 AgentCore 執行期

此疑難排解主題可協助您識別和解決使用 AgentCore 執行期時的常見問題。透過遵循這些解決方案，您可以快速診斷和修正代理程式執行時間的問題。

我的代理程式呼叫失敗，出現「此執行時間未MMDSv2-enabled」的 ValidationException

發生這種情況時：透過 InvokeAgentRuntime、ExecuteCommand、InvokeAgentRuntimeCommandShell、 InvokeAgentRuntimeWithWebSocketStream或 叫用代理程式執行時間時 GetAgentCard

發生這種情況的原因：自 2026 年 6 月 30 日起，Amazon Bedrock AgentCore 執行期要求所有代理程式執行期使用 MMDSv2 (MicroVM Metadata Service 第 2 版）。此服務會拒絕以未metadataConfiguration設定或requireMMDSV2設定為 或 false 的執行時間為目標的呼叫null。

解決方案：在 true中呼叫 UpdateAgentRuntime，並將 requireMMDSV2設定為 metadataConfiguration：

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

try:
    client.update_agent_runtime(
        agentRuntimeId='your-agent-runtime-id',
        metadataConfiguration={
            'requireMMDSV2': True
        }
    )
    print("MMDSv2 enabled successfully.")
except client.exceptions.ResourceNotFoundException as e:
    print(f"Runtime not found: {e}")
except Exception as e:
    print(f"Error enabling MMDSv2: {e}")

更新後，新的調用將會成功。現有的工作階段不受影響。

我的代理程式調用失敗，並出現 504 個閘道逾時錯誤

發生這種情況時：透過 SDK 或主控台叫用代理程式期間

發生這種情況的原因：多個因素可能會導致您的代理程式無法在逾時期間內回應

有幾個因素可能會導致這種情況：

我的 Docker 組建在提取 Python 基礎映像時失敗，並顯示「403 禁止」

發生這種情況時：使用public.ecr.aws基礎映像時docker build或期間 docker run

發生這種情況的原因：ECR 公開身分驗證問題 — 過期或缺少身分驗證是常見問題。

解決方案：登入 ECR Public 或完全登出：

# Option 1: Login to ECR Public
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws

# Option 2: Logout (recommended for avoiding token expiration)
docker logout public.ecr.aws

# Option 3: Use Docker Hub directly in Dockerfile
FROM python:3.10-slim
# instead of public.ecr.aws/docker/library/python:3.10-slim

我在使用 boto3 時收到「不明服務：「bedrock-agent-core-runtime」錯誤

發生這種情況時：使用 boto3 SDK 叫用 Amazon Bedrock AgentCore APIs 時

發生這種情況的原因：過期的 boto3 程式庫 — 由於大多數安裝沒有最新的 SDK，因此常見問題

解決方案：更新至最新的 boto3 和 botocore 版本：

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

我在嘗試建立 Amazon Bedrock AgentCore 執行期時收到「AccessDeniedException」

發生這種情況時：透過主控台、 SDK 或 CLI 建立代理程式期間

發生這種情況的原因：您的使用者缺少許可，或執行角色未針對 Amazon Bedrock AgentCore 正確設定

解決方案：有幾個因素可能會導致這種情況：

我的 Docker 建置失敗，並出現「exec /bin/sh： exec 格式錯誤」

發生這種情況時：為 Amazon Bedrock AgentCore 部署建置容器時

發生這種情況的原因：在沒有適當跨平台設定的情況下，在 x86 系統上建置 ARM64 容器

解決方案：建置 ARM64 相容容器。您可以考慮使用 buildx 進行跨平台建置。或者，您可以使用 CodeBuild。如需範例程式碼，請參閱 Amazon Bedrock AgentCore 範例。

搭配 Amazon Bedrock AgentCore 執行期使用的 Docker 容器有哪些需求？

如需完整詳細資訊，請參閱 Amazon Bedrock AgentCore 執行期需求。

總而言之，您的 Docker 容器必須符合下列要求：

我的長時間執行的工具會在 15 分鐘後中斷

如需詳細資訊，請參閱使用 Amazon Bedrock Amazon Bedrock AgentCore 執行期處理非同步和長時間執行的代理程式以取得完整詳細資訊。

發生這種情況時：在長時間執行的代理程式操作或複雜工作流程期間

發生這種情況的原因：Amazon Bedrock AgentCore 會在閒置 15 分鐘後自動終止工作階段。平台會決定/ping回應中的活動：工作階段報告HealthyBusy會保持活動狀態，而工作階段報告Healthy會被視為符合閒置資格，且其閒置時間會從status上次變更時開始測量 （請參閱下列time_of_last_update欄位）。

解決方案：確保您的/ping端點在背景工作進行HealthyBusy時傳回：

{"status": "HealthyBusy"}

如果您使用的是 Bedrock AgentCore SDK，則會自動處理 ping 回應。對於自訂實作，請確保您的 ping 處理常式在處理HealthyBusy時傳回 。

我的閒置工作階段未釋出，而且我耗盡了工作階段配額

發生這種情況時：即使每個工作階段都處於閒置狀態，工作階段計數仍會在負載下持續攀升，並且不會在閒置逾時後釋放工作階段 （例如， / ServiceQuotaExceededException 叫用爆量期間的maxVms錯誤）。

發生這種情況的原因：當工作階段報告 時Healthy，平台會測量/ping回應中 time_of_last_update 欄位閒置的時間，這必須反映status上次變更的時間。如果您的 ping 處理常式在每個 ping 上time_of_last_update設定為目前時間，報告的閒置時間會繼續重設，以防止閒置逾時觸發。然後，工作階段會一直有效，直到 MaxLifetime且 可以耗盡您的工作階段配額為止。

解決方案：time_of_last_update只有在status實際變更時更新，或完全省略它，以便平台自行追蹤狀態變更：

{"status": "Healthy"}

如果您使用的是 Bedrock AgentCore 開發套件，請升級至正確處理 ping 回應的最新版本。作為停止差距，呼叫 會StopRuntimeSession釋出停滯的工作階段。

如何在我的代理程式程式碼中存取 runtimeSessionId，以標記或分組資源？

適用時：您想要依目前的代理程式執行期工作階段來分組、標記或追蹤資源 （例如 S3 物件、日誌）。

解決方案：

解決方案 1：對於使用 Bedrock Amazon Bedrock AgentCore SDK 的代理程式，context.session_id請從您的代理程式進入點使用

@app.entrypoint
def my_agent(payload, context):
    session_id = context.session_id

    # Use session_id for S3 object tagging/organization
    s3_client = boto3.client('s3')
    s3_client.put_object(
        Bucket='my-bucket',
        Key=f'agent-outputs/{session_id}/output.json',
        Body=json.dumps(result),
        Tagging=f'SessionId={session_id}'
    )
    return result

解決方案 2：適用於自訂執行期 HTTP 伺服器

執行階段工作階段 ID 會在此 HTTP 標頭中傳遞。從傳入請求中剖析它，並將其用於標記、相互關聯或下游傳播。

X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <value>

我有 RuntimeClientError (403) 問題

問題

嘗試叫用代理程式執行時間時，您會收到 403 "RuntimeClientError"。

原因

此錯誤通常是因為下列原因發生：

解決方案

請依照下列步驟來解決問題：

我有遺失或空白的 CloudWatch Logs

問題

您遇到錯誤，但未在 CloudWatch 中看到任何相關日誌。

解決方案

嘗試這些方法來診斷問題：

我有承載格式問題

問題

即使容器成功啟動，您的代理程式執行期調用也會失敗。

解決方案

請依照下列步驟來解決承載格式問題：

我需要了解 HTTP 錯誤代碼的協助

問題

您的代理程式會傳回難以解譯的 HTTP 錯誤代碼。

錯誤訊息範例

您可能會看到如下錯誤：

An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime operation: Received error (<HTTP Status Code>) from runtime. Please check your CloudWatch logs for more information

解決方案

以下是最常見的錯誤代碼及其意義：

我需要測試代理程式的建議

若要系統地偵錯代理程式執行期問題：

先在本機測試

部署至 AgentCore 執行期之前：

比較承載

確保環境之間的一致性：

我需要偵錯容器問題的協助

如果您懷疑容器相關問題：

在本機提取和執行

在本機電腦上測試容器映像：

docker pull <your-ecr-repo-uri>
docker run -p 8080:8080 <your-ecr-repo-uri>

使用 curl 進行測試

將測試請求傳送至您的本機容器：

curl -X POST http://localhost:8080/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": {"prompt": "Hello world!"}}'

檢查容器日誌

檢查容器的輸出是否有錯誤：

docker logs <container-id>

我需要對 MCP 通訊協定代理程式進行故障診斷的協助

對於 MCP 通訊協定代理程式，請遵循下列特定疑難排解步驟：

驗證端點路徑

MCP 伺服器應接聽 0.0.0.0:8000/mcp/

使用 MCP Inspector

使用 MCP Inspector 工具進行測試：

驗證問題

檢查身分驗證組態：

我需要使用 WebSocket 疑難排解雙向串流的說明

對於使用 WebSocket 代理程式的雙向串流，請遵循下列特定疑難排解步驟：

驗證端點組態

WebSocket 代理程式必須在連接埠 8080 上執行，並在/ws路徑提供 WebSocket 連線

以增量複雜性在本機測試

部署之前，請先進行簡單的本機測試：

驗證問題

檢查已部署代理程式的身分驗證組態：

常見的連線問題

解決常見的 WebSocket 連線問題：

我的程式碼變更不會反映在現有的工作階段中

問題

您已使用新程式碼更新代理程式執行時間，但現有的工作階段會繼續使用舊版本。

為什麼會發生這種情況

每個 microVM agentRuntimeArtifact 工作階段都會使用在工作階段建立時部署的程式碼資產 () 建立。建立工作階段後，它會繼續使用該版本的程式碼，直到工作階段終止為止，即使程式碼資產更新為執行 UpdateAgentRuntime 操作的一部分。

解決方案

若要存取更新後的程式碼，請使用新的工作階段 ID。

從 Lambda 函數叫用我的執行時間時，缺少跨度

發生這種情況時：從 Lambda 函數叫用 AgentCore 執行期時

發生這種情況的原因：Lambda 會產生自己的X-Amzn-Trace-Id標頭。如果 Lambda 追蹤具有 Sampled=0 ，則此未取樣內容會傳播至 AgentCore 執行期，且執行期會略過該調用的範圍產生。

解決方案：

我的 S3 檔案或 EFS 掛載失敗，並顯示「拒絕存取」

發生這種情況時：在呼叫已設定 S3 檔案或 EFS 儲存體的代理程式期間

發生這種情況的原因：執行角色缺少必要的檔案系統許可。如需設定持久性儲存的詳細資訊，請參閱 AgentCore 執行期的檔案系統組態。

解決方案：

對於 S3 檔案，請確定您的執行角色具有：

{
  "Effect": "Allow",
  "Action": [
    "s3files:ClientMount",
    "s3files:ClientWrite"
  ],
  "Resource": "arn:aws:s3files:<region>:<account>:file-system/*",
  "Condition": {
    "StringEquals": {
      "s3files:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

對於 EFS，請確保您的執行角色具有：

{
  "Effect": "Allow",
  "Action": [
    "elasticfilesystem:ClientMount",
    "elasticfilesystem:ClientWrite"
  ],
  "Resource": "arn:aws:elasticfilesystem:<region>:<account>:file-system/<fs-id>",
  "Condition": {
    "StringEquals": {
      "elasticfilesystem:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

如果您的代理程式只需要讀取存取權elasticfilesystem:ClientWrite，請省略 s3files:ClientWrite或 。

我的 S3 檔案或 EFS 掛載失敗，並顯示 "ResourceNotFound"

發生這種情況時：在呼叫已設定 S3 檔案或 EFS 儲存體的代理程式期間

發生這種情況的原因：建立代理程式後，檔案系統或存取點遭到刪除，或 IDs不正確。

解決方案：

我的 S3 檔案或 EFS 掛載逾時

發生這種情況時：在呼叫已設定 S3 檔案或 EFS 儲存體的代理程式期間。調用可能需要比平常更長的時間才會失敗。

發生這種情況的原因：VPC 網路組態會封鎖代理程式運算和檔案系統掛載目標之間的 NFS 流量 （連接埠 2049)。

解決方案：

寫入掛載的檔案系統時，我會收到「拒絕許可」

發生這種情況時：代理程式調用成功，且代理程式可以從掛載讀取檔案，但寫入失敗並顯示「拒絕許可」

發生這種情況的原因：IAM 角色缺少寫入許可，或在存取點建立期間對目錄設定的 POSIX 許可不允許對代理程式的使用者進行寫入。

解決方案：

我的容器無法在高階映像上從 HTTP 424 錯誤開始

發生這種情況時：您的InvokeAgentRuntime呼叫會傳回 HTTP 424 （失敗相依性），而您的客服人員日誌會顯示 Failed to mount overlay: No such file or directory。當您的容器映像具有超過 53 個層，且使用非數字 USER 指令 （例如，USER myuser而非 USER 1000) 時，就會發生這種情況。

發生這種情況的原因：具有多個層的容器映像結合非數值 USER 指令可能會導致初始化失敗。

解決方案：使用以下其中一個解決方法：

docker inspect <image> | jq '.[0].RootFS.Layers | length'

最佳實務

啟用完整記錄

在您的代理程式中實作徹底記錄：

使用結構化錯誤處理

實作明確的錯誤報告：

測試增量變更

遵循系統化測試方法：

監控效能

為您的代理程式設定監控：