AgentCore 런타임 문제 해결

이 문제 해결 주제는 AgentCore 런타임 작업 시 일반적인 문제를 식별하고 해결하는 데 도움이 됩니다. 이러한 솔루션을 따르면 에이전트 런타임 문제를 신속하게 진단하고 수정할 수 있습니다.

에이전트 호출이 실패하고 "이 런타임은 MMDSv2-enabled 않습니다" ValidationException

이 경우: InvokeAgentRuntime, , ExecuteCommand, InvokeAgentRuntimeWithWebSocketStream InvokeAgentRuntimeCommandShell또는를 통해 에이전트 런타임을 호출하는 경우 GetAgentCard

이 문제가 발생하는 이유: 2026년 6월 30일부터 Amazon Bedrock AgentCore 런타임은 MMDSv2(MicroVM 메타데이터 서비스 버전 2)를 사용하려면 모든 에이전트 런타임이 필요합니다. 서비스는 metadataConfiguration 설정되지 않았거나 또는 false 로 requireMMDSV2 설정된 런타임을 대상으로 하는 호출을 거부합니다null.

해결 방법: true에서를 로 requireMMDSV2 설정하여 UpdateAgentRuntime을 호출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 또는 콘솔을 통한 에이전트 호출 중

이 문제가 발생하는 이유: 여러 요인으로 인해 에이전트가 제한 시간 내에 응답하지 못할 수 있습니다.

다음과 같은 몇 가지 요인이 이를 일으킬 수 있습니다.

Python 기본 이미지를 가져올 때 "403 Forbidden"으로 Docker 빌드가 실패함

이 경우: public.ecr.aws 기본 이미지를 사용하는 동안 docker build 또는 사용할 docker run 때

이 문제가 발생하는 이유: ECR 퍼블릭 인증 문제 - 만료되거나 누락된 인증이 일반적인 문제입니다.

해결 방법: ECR 퍼블릭에 로그인하거나 완전히 로그아웃합니다.

# 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를 사용할 때 "Unknown service: '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에 대해 실행 역할이 제대로 구성되지 않음

해결 방법: 몇 가지 요인으로 인해 다음과 같은 문제가 발생할 수 있습니다.

'exec /bin/sh: exec 형식 오류'와 함께 Docker 빌드가 실패함

이 경우: 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 필드 참조).

해결 방법: 백그라운드 작업이 진행되는 HealthyBusy 동안 /ping 엔드포인트가를 반환하는지 확인합니다.

{"status": "HealthyBusy"}

Bedrock AgentCore SDK를 사용하는 경우 ping 응답이 자동으로 처리됩니다. 사용자 지정 구현의 경우 처리 HealthyBusy 중에 ping 핸들러가를 반환하는지 확인합니다.

유휴 세션이 해제되지 않고 세션 할당량이 소진되었습니다.

이 경우: 각 세션이 유휴 상태이더라도 세션 수가 로드 상태에서 지속적으로 상승하고 유휴 제한 시간 이후에 세션이 해제되지 않습니다(예: 호출 버스트 중 ServiceQuotaExceededException / maxVms 오류).

이 경우의 이유: 세션Healthy이를 보고하면 플랫폼은 /ping 응답의 time_of_last_update 필드에서 유휴 상태가 된 시간을 측정하며, 이는가 status 마지막으로 변경된 시간을 반영해야 합니다. ping 핸들러가 모든 pingtime_of_last_update에서 현재 시간으로 설정된 경우 보고된 유휴 시간은 계속 재설정되므로 유휴 제한 시간이 실행되지 않습니다. 그런 다음 세션은 MaxLifetime 및가 세션 할당량을 소진할 수 있을 때까지 유지됩니다.

해결 방법:가 status 실제로 변경될 때time_of_last_update만 업데이트하거나 플랫폼이 상태 변경을 자체적으로 추적하도록 완전히 생략합니다.

{"status": "Healthy"}

Bedrock AgentCore SDK를 사용하는 경우 ping 응답이 올바르게 처리되는 최신 버전으로 업그레이드합니다. stopgap으로서를 호출하면 멈춘 세션이 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 myuser 대신USER 1000)을 사용하는 경우에 발생합니다.

이 문제가 발생하는 이유: 숫자가 아닌 USER 명령과 여러 계층이 결합된 컨테이너 이미지는 초기화 실패를 일으킬 수 있습니다.

해결 방법: 다음 해결 방법 중 하나를 사용합니다.

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

모범 사례

포괄적인 로깅 활성화

에이전트에서 철저한 로깅을 구현합니다.

구조화된 오류 처리 사용

명확한 오류 보고를 구현합니다.

증분 변경 테스트

체계적인 테스트 접근 방식을 따릅니다.

성능 모니터링

에이전트에 대한 모니터링을 설정합니다.