View a markdown version of this page

문제 해결 - Amazon Bedrock AgentCore
스키마 유효성 검사 오류동기화 오류 기록

문제 해결

예정된 네임스페이스 마이그레이션

AWS 에이전트 레지스트리는 현재 bedrock-agentcore 네임스페이스에서 공개 미리 보기 중입니다. 2026년 8월 6일부터 서비스는 에이전트 레지스트리 네임스페이스로 이동합니다. AWS 에이전트 레지스트리를 사용하는 경우 엔드포인트, IAM 정책, SDK 클라이언트, CLI 스크립트 및 레지스트리 데이터를 업데이트해야 합니다. 공개 미리 보기에서 마이그레이션하는 방법에 대한 자세한 내용은 포괄적인 레지스트리 마이그레이션 가이드를 참조하세요.

스키마 유효성 검사 오류

다른 유형의 레코드를 생성할 때 설명자에 대한 검증 예외가 표시될 수 있습니다. 유효한 스키마는 지원되는 레코드 유형 섹션을 참조하세요.

일반적인 오류:

  • “기술자 유형 'a2a'에는 스키마 버전 '0.3.0'이 지원되지 않습니다.” - schemaVersion 필드 값은 0.3 대신 0.3.0 여야 합니다. 이는 공식 A2A 프로토콜 버전 설명 : "메이저 버전당 지원되는 최신 마이너 버전 사용"과 일치합니다.

  • “스키마 검증 실패: 콘텐츠가 설명자 유형 'a2a'에 대한 스키마 버전 '0.3'을 준수하지 않습니다.” - 지원되는 레코드 유형에서 스키마를 찾을 수 있습니다. 콘텐츠는 json 스키마의 #/definitions/AgentCard에 대해 검증됩니다.

동기화 오류 기록

동기화 기능을 사용하여 레코드를 생성하거나 업데이트하면 레코드가 CREATE_FAILED 또는 UPDATE_FAILED 상태로 전환되어 발생한 일을 statusReason 설명할 수 있습니다.

상위 수준에서 오류는 권한 오류, 연결 오류, 검증 오류, 서버 측 오류로 분류할 수 있습니다.

권한 오류

동기화 구성이 잘못되었거나 만료되었습니다.

  • “발신자 자격 증명이 만료되어 MCP 서버에 연결할 수 없습니다.” - 생성 또는 업데이트 API의 호출자가 자격 증명이 만료되었습니다. UpdateRegistryRecord API로 다시 시도할 수 있습니다.

  • "GetWorkloadAccessToken API에서 예외 수신: <detailed message>" - 레지스트리는 호출on-behalf-of GetWorkloadAccessToken API를 호출합니다. 오류에 대해 알아보려면 자세한 메시지를 참조하세요. 액세스 거부 예외가 표시되면 외부 소스의 레코드 동기화를 참조하세요.

  • "자격 증명 공급자 ARN을 구문 분석할 수 없음: <arn>" — 잘못된 자격 증명 공급자 ARN. 이는 AgentCore 자격 증명에서 생성된 유효한 자격 증명 공급자 ARN이어야 합니다.

  • "GetResourceOauth2Token API에서 예외 수신: <detailed message>" - 레지스트리는 호출on-behalf-of GetResourceOauth2Token API를 호출합니다. 오류에 대해 알아보려면 자세한 메시지를 참조하세요. 액세스 거부 예외가 표시되면 외부 소스의 레코드 동기화를 참조하세요.

  • “MCP 서버 권한 부여를 위해 제공된 IAM 역할을 수임할 수 없습니다.” - 레지스트리는 호출on-behalf-of AssumeRole API를 호출합니다. 예상 IAM 권한은 외부 소스의 레코드 동기화를 참조하세요. 예를 들어 호출자에게 iam:PassRole 권한이 있어야 합니다.

연결 오류

서버에 연결할 수 없습니다.

  • "URL: %s에서 에이전트 카드를 가져오지 못함" — A2A IOException

  • "MCP 서버가 HTTP <code>" - MCP 서버의 200/202가 아닌 HTTP 응답을 반환했습니다. URL이 올바르고 MCP 서버를 연결할 수 있는지 확인하세요.

  • "제공된 URL은 비공개 IP 주소로 확인됩니다" - 레지스트리는 퍼블릭 IP 주소 서버에 대한 연결만 지원합니다.

  • "MCP 서버에 연결하지 못함" — IOException/연결 실패

  • “잘못된 MCP 서버 URL” — 잘못된 형식의 URL

  • "MCP 연결을 초기화하지 못했습니다" - 요청 예외를 초기화합니다.

  • "초기화된 알림을 보내지 못함" - 알림 예외

  • "MCP 서버에서 도구를 나열하지 못함" - 도구/목록 예외

  • "MCP 서버 도구/목록 페이지 매김 시간 초과" - 레지스트리는 MCP 서버에서 도구를 페이지 매김할 때 최대 30초만 지원합니다. MCP 서버 동기화에 더 많은 시간이 필요한 경우 AWS 지원팀에 문의하세요.

유효성 검사 오류

서버가 응답했지만 콘텐츠는 지원되지 않습니다.

  • "에이전트 카드 JSON을 구문 분석하지 못함" - A2A 콘텐츠가 비어 있거나 형식이 잘못된 JSON

  • "에이전트 카드가 최대 크기 제한을 초과함" — A2A 응답이 너무 큼

  • "MCP 서버 응답 JSON을 구문 분석하지 못함" — MCP 콘텐츠가 비어 있거나 형식이 잘못되었습니다.

  • "MCP 서버가 잘못된 응답을 반환함: 결과 누락" — MCP JSON-RPC 결과 누락

  • "MCP 서버 응답이 최대 허용 크기를 초과합니다" - MCP 응답이 너무 큽니다.

  • “설명자 유형 %s는 URL 동기화를 지원하지 않습니다.” — 지원되지 않는 설명자 유형

서버 측 오류

  • “알 수 없는 오류” - 서버 측 오류입니다. 나중에 다시 시도하거나 AWS 지원팀에 도움을 요청하십시오.