View a markdown version of this page

직접 코드 배포 문제 해결 - Amazon Bedrock AgentCore
AccessDenied: S3 권한 부족AccessDenied: CMK 암호화 S3 객체 액세스CREATE_FAILED: 코드 패키지 호환성ARM64 바이너리 비호환성진입점 누락Node.js 호환되지 않는 엔진.node 선언Node.js OTEL 패키지 누락

직접 코드 배포 문제 해결

Amazon Bedrock AgentCore 다이렉트 코드 배포를 시작할 때 발생하는 일반적인 문제 및 해결 방법. 자세한 문제 해결 정보는 Amazon Bedrock AgentCore 런타임 문제 해결을 참조하세요.

AccessDenied: S3 권한 부족

이 경우: 콘솔, SDK 또는 CLI를 통해 에이전트를 생성하거나 S3에서 압축된 아티팩트로 업데이트하는 동안

이 문제가 발생하는 이유: Create/UpdateAgentRuntime을 호출하는 데 사용되는 역할에는 API 입력에 전달된 S3 uri에 대한 s3:GetObject 권한이 없습니다.

해결 방법: Agentcore 런타임 생성/업데이트 API를 호출하는 데 사용되는 역할에 s3:GetObject 권한을 추가합니다.

{
"Version": "2012-10-17",
  "Statement": [
    {
        "Effect": "Allow",
        "Action": "s3:GetObject",
        "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

AccessDenied: CMK 암호화 S3 객체 액세스

이 경우: 실행 역할에 KMS 복호화 권한이 없는 경우 CMK로 암호화된 S3 객체를 사용하여 에이전트를 생성하는 동안.

이 경우의 이유: Create/UpdateAgentRuntime을 호출하는 데 사용되는 역할에는 에이전트 코드가 포함된 S3 객체를 암호화하는 데 사용되는 CMK에 대한 kms:Decrypt 권한이 없습니다.

해결 방법: 특정 CMK의 역할에 kms:Decrypt 권한을 추가합니다.

{
"Version": "2012-10-17",
  "Statement": [
    {
        "Effect": "Allow",
        "Action": [
            "s3:GetObject",
            "kms:Decrypt"
        ],
        "Resource": [
            "arn:aws:s3:::your-bucket-name/*",
            "arn:aws:kms:us-west-2:your-account:key/your-cmk-key-id"
        ]
    }
  ]
}

CREATE_FAILED: 코드 패키지 호환성

이 경우: 에이전트를 생성하거나 호환되지 않는 코드 패키지(잘못된 아키텍처, 언어 버전 또는 패키지 형식)로 업데이트하는 동안.

이 문제가 발생하는 이유: 업로드된 ZIP 파일에는 잘못된 아키텍처(ARM64 대 x86_64), 호환되지 않는 언어 버전 또는 AgentCore 런타임 요구 사항과 일치하지 않는 잘못된 패키지 구조에 대해 컴파일된 바이너리가 포함되어 있습니다.

해결 방법:

이 문제를 해결하는 방법:

  1. arm64에 대해 코드가 컴파일되었는지 확인합니다.

  2. 호환되는 언어 버전을 사용합니다( AgentCore 런타임 지원 버전 확인).

  3. ZIP 구조에 적절한 진입점과 종속성이 포함되어 있는지 확인합니다.

  4. 호환되는 런타임 환경에서 패키지를 다시 빌드합니다.

오류 표시기:

  • 에이전트 상태: CREATE_FAILED 또는 런타임 오류

  • Cloudwatch 로그에서 오류 또는 "이진 파일을 실행할 수 없음" 메시지 가져오기

  • getAgentRuntimeEndpoint를 수행할 때 아키텍처 불일치 오류가 발생합니다.

ARM64 바이너리 비호환성

이 경우: 에이전트 생성 중 ZIP에 non-ARM64 아키텍처용으로 컴파일된 네이티브 바이너리가 포함된 경우.

이 경우의 이유: AgentCore 런타임은 arm64 명령 세트 아키텍처만 지원합니다. 이 서비스는 Python용 파일과 Node.js용 .so 파일 등 배포 패키지의 모든 기본 바이너리 .so .node 파일을 스캔하고 ELF 헤더의 ARM64 호환성을 검증합니다. x86_64, macOS(Mach-O) 또는 다른 아키텍처에 대해 컴파일된 바이너리가 있는 경우 검증이 실패합니다.

해결 방법:

  • Python: arm64 호환 휠을 다운로드uv pip install --python-platform aarch64-manylinux2014 --only-binary=:all:하는 데 사용합니다.

  • Node.js: arm64 시스템에 네이티브 모듈을 설치하거나 npm install --arch=arm64 --platform=linux를 사용합니다.

  • 또는 AWS Graviton 기반 Amazon EC2 인스턴스에 종속성을 구축하여 arm64 호환성을 보장합니다.

오류 표시기: "Your artifact contains binary files that are incompatible with Linux ARM64."

진입점 누락

이 경우: 지정된 진입점 파일이 ZIP에 존재하지 않는 에이전트 생성 중.

이 경우의 이유: entryPoint 구성에서 지정한 진입점 파일 경로가 배포 패키지의 파일과 일치하지 않습니다. 이는 파일이 ZIP에 포함되지 않았거나, 경로의 철자가 잘못되었거나, ZIP 구조가 예상과 다른 경우에 발생할 수 있습니다.

해결 방법:

  • 진입점 파일이 ZIP에 있는지 확인합니다. unzip -l deployment_package.zip | grep app.js

  • 의 경로가 ZIP 내의 파일 경로와 entryPoint 일치하는지 확인합니다( src/app.js 또는 dist/index.js와 같은 하위 디렉터리 포함).

  • Python 에이전트의 경우 진입점은 .py 로 끝나야 하며, Node.js 에이전트의 경우 로 끝나야 합니다. .js

오류 표시기: "The specified entrypoint could not be found or accessed in your artifact."

Node.js 호환되지 않는 엔진.node 선언

이 경우: package.json 또는 공통 종속성이 대상 Node.js 버전을 제외하는 engines.node 범위를 선언하는 Node.js 에이전트 생성 중.

이 문제가 발생하는 이유: AgentCore 런타임은 루트의 engines.node 필드package.json와 공통 종속성을 확인합니다. 버전 범위가 대상 Node.js 버전을 제외하면(예: <18 Node.js 22에 배포할 >=14 <18 때) 에이전트 생성이 실패합니다.

해결 방법:

  • 대상 Node.js 버전을 package.json 포함하도록의 engines.node 필드를 업데이트합니다(예: ">=18" ).

  • 호환되지 않는 종속성을 대상 Node.js 버전을 지원하는 버전으로 업데이트

  • 필요하지 않은 경우 engines 필드 제거

오류 표시기: "Your artifact contains dependencies with engines.node declarations incompatible with the target Node.js version."

Node.js OTEL 패키지 누락

이 경우: 진입점opentelemetry-instrument에를 지정하지만 ADOT 패키지가 ZIP에 포함되지 않은 Node.js 에이전트 생성 중.

이 경우의 이유: "entryPoint": ["opentelemetry-instrument", "app.js"]를 사용하는 경우 AgentCore 런타임은 배포 패키지 node_modules/ 내에 @aws/aws-distro-opentelemetry-node-autoinstrumentation npm 패키지가 있을 것으로 예상합니다.

해결 방법:

ZIP을 패키징하기 전에 ADOT 패키지를 설치합니다.

npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
zip -r deployment_package.zip app.js node_modules/ package.json

또는 자동 계측이 필요하지 않은 경우 진입점에서 opentelemetry-instrument 접두사를 제거합니다.

오류 표시기: "OpenTelemetry instrumentation executable not found. The ZIP file requires open-telemetry dependencies, but none are present."