에이전트 레지스트리 문제 해결

Agent Registry에서 구성요소를 등록, 검색 또는 연결할 때 할당량 한도, 페이로드 및 기술 검증 오류, 위치 불일치, 동기화 지연, 권한 오류와 같은 일반적인 문제를 진단하고 해결할 수 있습니다.

API 비율 할당량 초과

Agent Registry API와 상호작용하거나Google Cloud 콘솔에서 Agent Registry를 빠르게 탐색할 때 요청 비율 한도를 초과하면 다음 오류가 발생합니다.

429 Too Many Requests

이 문제를 해결하려면 API 클라이언트에서 지수 백오프를 구현하여 요청 비율을 관리하세요. Agent Registry API에는 Agent Registry 리소스에 적용되는 위치당 분당 요청의 기본 비율 할당량이 있습니다.

Google Cloud 콘솔에서 탭을 전환할 때 제한이 발생하면 잠시 기다린 후 다시 시도하세요. 프로그래매틱 사용 사례에 더 높은 한도가 필요한 경우 RequestsPerMinute 측정항목에 대해 할당량 증가를 요청하세요.

수동 등록 중 페이로드 크기 오류

크기 한도를 초과하는 사양 파일로 에이전트 또는 MCP 서버를 수동으로 등록하면 다음 오류가 발생합니다.

API는 페이로드가 너무 크다는 오류와 함께 요청을 거부합니다.

이 문제를 해결하려면 agent-card.json 또는 toolspec.json 파일이 10KB 미만인지 확인합니다. AgentSpec 및 McpServerSpec 콘텐츠 크기는 10KB로 제한됩니다. 이 한도를 준수하려면 JSON 파일을 축소하거나, 불필요한 공백을 삭제하거나, 도구 설명을 압축하세요. 자세한 내용은 JSON 스키마를 참조하세요.

생성 후 에이전트 또는 MCP 서버가 누락됨

Google Workspace 또는 Gemini Enterprise와 같은 지원되는 Google Cloud 제품에서 에이전트 또는 MCP 서버를 만든 후 다음 오류가 발생합니다.

ListAgents 또는 ListMcpServers API를 호출할 때 리소스가 출력에 표시되지 않습니다.

이 문제를 해결하려면 백그라운드 동기화가 완료될 때까지 기다립니다. 리소스는 실시간으로 업데이트되지만 주기적인 오프라인 일괄 작업은 다른 통합을 채웁니다. 몇 시간 후에도 리소스가 표시되지 않으면 프로젝트의 서비스 사용량 설정을 확인하고 관련 API가 사용 설정되어 있는지 확인합니다.

장기 실행 작업이 중단된 것으로 표시됨

에이전트를 배포하거나 복잡한 바인딩을 구성할 때 다음 오류가 발생합니다.

작업에 상당한 시간이 걸리고 중단된 것처럼 보입니다.

이 문제를 해결하려면 get_operation MCP 도구 또는 google.longrunning.Operations.GetOperation API 엔드포인트를 사용하여 작업 상태를 폴링합니다. 일부 에이전트 및 MCP 백엔드 생성에는 상당한 인프라 프로비저닝이 필요하므로 장기 실행 작업(LRO) 시간이 최대 30분까지 걸릴 수 있습니다. 이에 따라 클라이언트 제한 시간 설정을 구성하고 done 불리언 플래그를 폴링하여 완료를 확인합니다.

사용 가능한 바인딩을 가져올 때 결과가 비어 있음

대상 AuthProvider 리소스에 대한 권한이 충분하지 않은 상태에서 인증 제공업체에 사용 가능한 바인딩을 가져오면 다음 오류가 발생합니다.

바인딩이 있더라도 API는 빈 배열 또는 액세스 오류를 반환합니다.

이 문제를 해결하려면 주 구성원에게 대상 AuthProvider 리소스에 대한 올바른 Identity and Access Management(IAM) 권한이 있는지 확인합니다. API는 엄격한 IAM 검사를 적용하고 호출자가 액세스할 수 없는 인증 제공업체를 참조하는 Binding 객체를 삭제합니다. 주 구성원에게 인증 제공업체에 대한 필수 액세스 권한과 프로젝트에 대한 roles/agentregistry.viewer 역할이 있는지 확인합니다.

302 오류가 표시되면서 스킬 버전 다운로드 실패

?alt=media 쿼리 매개변수와 함께 GetSkillRevision API를 사용하여 기술 버전 페이로드를 다운로드하려고 시도하고 HTTP 클라이언트가 리디렉션을 따르지 않으면 다음 오류가 발생합니다.

{
  "error": {
    "code": 302,
    "message": "Unknown Error.",
    "status": "UNKNOWN"
  }
}

이 문제를 해결하려면 HTTP 클라이언트가 리디렉션을 자동으로 따르도록 구성되어 있는지 확인합니다. ?alt=media 엔드포인트는 기술 보관 파일을 다운로드하려면 302 리디렉션이 필요합니다. 예를 들어 curl를 사용하는 경우 명령어에 -L 또는 --location 플래그를 추가합니다.

스킬 버전 검증이 실패하거나 FAILED 상태가 표시됨

잘못된 ZIP 파일로 새 기술 버전을 만들면 다음 오류가 발생합니다.

버전이 FAILED 상태로 전환되며 에이전트가 로드할 수 없습니다.

이 문제를 해결하려면 검증 로그를 확인하거나 ZIP 페이로드 콘텐츠를 검사합니다.

• ZIP 파일의 루트에 SKILL.md 파일이 포함되어 있는지 확인합니다.
• SKILL.md 파일에 name 및 description가 모두 정의된 유효한 YAML 프런트 매터 블록이 있는지 확인합니다.
• ZIP 페이로드가 크기 제한을 초과하지 않는지 확인합니다. 압축 크기는 1MB 미만, 압축되지 않은 총 크기는 10MB 미만, 개별 파일 크기는 1MB 미만이어야 합니다.
• 보관 파일에 심볼릭 링크, 디렉터리 순회 요소(예: ..) 또는 절대 경로가 포함되어 있지 않은지 확인합니다.

독립형 기술은 서비스 또는 에이전트 리소스 목록에 표시되지 않음

gcloud agent-registry services list 또는 gcloud agent-registry agents list를 실행하는 등 독립형 기술의 에이전트 또는 서비스 목록을 쿼리하면 다음 오류가 발생합니다.

독립형 기술은 출력에 표시되지 않습니다.

이 문제를 해결하려면 대신 skills 컬렉션을 쿼리하세요.

• 수동으로 등록된 에이전트, MCP 서버, 엔드포인트와 달리 독립형 기술은 쓰기 가능한 Service 리소스나 Agent, McpServer 또는 Endpoint 탐색 리소스를 사용하지 않습니다. 대신 에이전트 레지스트리는 독립형 기술을 최상위 Skill 리소스 및 버전이 지정된 SkillRevision 리소스로 직접 표현합니다.
• 독립형 기술을 나열, 검색 또는 검사하려면Google Cloud 콘솔에서 기술 탭을 사용하거나, gcloud agent-registry skills list 또는 gcloud agent-registry skills search를 실행하거나, skills REST API 메서드를 호출합니다. 자세한 내용은 기술 관리 및 독립형 기술 검색을 참조하세요.
• 에이전트의 에이전트 카드에 선언된 인라인 A2A 기술을 찾고 있다면 gcloud agent-registry agents describe 또는 gcloud agent-registry agents search를 사용하여 Agent 검색 리소스에서 skills 필드를 검사하세요.

IAP 정책을 관리할 때 리소스 항목을 찾을 수 없음 오류 발생

gcloud iap web 명령어를 사용하여 Agent Registry 리소스에서 IAP(Identity-Aware Proxy) 이그레스 정책을 관리할 때 다음 오류가 발생합니다.

NOT_FOUND: Requested entity was not found

이 문제를 해결하려면 다음을 확인하세요.

• 등록 상태: 대상 구성요소가 Agent Registry의 예상 위치에 등록되어 있는지 확인합니다.
• 식별자 형식: 명령어 또는 정책 바인딩이 레지스트리 식별자 URN이 아닌 표준 리소스 이름을 지정하는지 확인합니다.
• 리소스 플래그: gcloud iap web에 전달하는 리소스 플래그가 기본 에이전트 레지스트리 하위 리소스 유형과 일치하는지 확인합니다.
  • 외부 API 또는 Google API 이그레스 지점과 같은 엔드포인트의 경우 --endpoint 플래그를 사용합니다.
  • 모델 컨텍스트 프로토콜 서버의 경우 --mcp-server 플래그를 사용합니다.
  • 등록된 에이전트의 경우 --agent 플래그를 사용합니다.

gcloud agent-registry endpoints list, gcloud agent-registry mcp-servers list 또는 gcloud agent-registry agents list에서 반환된 리소스 이름을 확인하여 리소스 이름에 /endpoints/, /mcpServers/ 또는 /agents/가 포함되어 있는지 확인합니다. 잘못된 리소스 플래그를 전달하면(예: MCP 서버 ID에 --endpoint 전달) NOT_FOUND 오류가 발생합니다.

IAP 웹 IAM 정책을 적용할 때 권한이 거부되었습니다.

필수 관리 역할 없이 Agent Registry 리소스에 대한 IAP 웹 IAM 정책을 적용하거나 수정하면 다음 오류가 발생합니다.

ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED

이 문제를 해결하려면 활성 사용자 또는 서비스 계정에 레지스트리 및 게이트웨이를 호스팅하는 프로젝트에 필요한 권한이 있는지 확인합니다.

• 호출자에게 중앙 거버넌스 프로젝트에 대한 IAP 정책 관리자(roles/iap.admin) 또는 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin) 역할이 있는지 확인합니다.
• 호출자에게 iap.web.setIamPolicy 및 resourcemanager.projects.setIamPolicy 권한이 있는지 확인합니다.

리전 위치에서 원격 MCP 서버를 찾을 수 없음

us-central1와 같은 리전 위치에서 자동으로 등록된 Google 또는 Google Cloud 원격 MCP 서버를 쿼리하거나 IAP 이그레스 정책을 적용하면 다음 오류가 발생합니다.

서비스에서 리전 엔드포인트(REP)를 제공하거나 트래픽이 리전 Agent Gateway를 통해 라우팅되는 경우에도 요청에서 NOT_FOUND 오류 또는 빈 목록을 반환합니다.

에이전트 레지스트리가 사용 설정된 API에 대해 Google 또는Google Cloud 원격 MCP 서버를 자동으로 등록하면 us-central1와 같은 개별 리전이 아닌 global 위치에만 McpServer 리소스를 만듭니다. 서비스가 https://SERVICE.REGION.rep.googleapis.com/mcp와 같은 리전 엔드포인트를 제공하는 경우 Agent Registry는 해당 단일 global McpServer 리소스의 interfaces 필드에 해당 리전 URL을 나열합니다.

이 문제를 해결하려면 다음 중 한 가지를 따르세요.

• 자동으로 등록된 서버에 global 사용: 호출 에이전트가 리전 게이트웨이를 통해 트래픽을 라우팅하는 경우에도 --location=global를 사용하여 에이전트 레지스트리에서 서버를 쿼리하거나 --region=global를 사용하여 IAP 이그레스 정책을 적용할 때 global 위치를 지정합니다.
• 데이터 레지던시를 위해 리전에 등록: 특정 리전에 레지스트리 메타데이터를 보관해야 하는 경우 커스텀 MCP 서버를 리전 Cloud Run 또는 Google Kubernetes Engine(GKE) 런타임에 배포하거나 해당 리전에 MCP 서버와 리전 엔드포인트 URL을 수동으로 등록한 후 동일한 리전에 IAP 정책을 적용합니다. Agent Gateway가 대상 URL을 확인할 때 리전 레지스트리 항목이 global 항목보다 우선 적용됩니다.

Agent Gateway에서 Model Armor를 구성할 때 리전 불일치 오류

일치하지 않는 리전에서 Agent Gateway에 Model Armor 정책 필터를 구성하면 다음 오류가 발생합니다.

승인 정책을 만들 때 리전 불일치 오류가 발생하거나 게이트웨이를 통해 MCP 서버로 라우팅되는 트래픽이 정책 평가에 실패합니다.

이 문제를 해결하려면 게이트웨이 리소스와 대상 정책 바인딩의 리전 정렬을 확인합니다.

• 게이트웨이 및 Model Armor 리전 일치: Agent Gateway, Model Armor 템플릿, 승인 확장 프로그램 및 정책이 모두 동일한 리전(예: us-central1)에 있는지 확인합니다.
• global 또는 리전 MCP 서버로 라우팅: Model Armor를 사용하기 위해 리전에서 global MCP 서버를 다시 등록할 필요가 없습니다. Model Armor는 리전 게이트웨이에서 요청 및 응답 페이로드를 검사하므로 리전 게이트웨이는 리전 대상뿐만 아니라 global 위치에 등록된 MCP 서버로 라우팅되는 트래픽을 검사하고 제어할 수 있습니다.
• IAP 이그레스 바인딩을 대상의 등록 위치에 일치: 대상 McpServer 리소스가 등록된 위치에 IAP 이그레스 승인 바인딩을 적용합니다. 자동으로 등록된 원격 MCP 서버에는 global를 사용하고, 리전별로 등록된 MCP 서버에는 특정 리전을 사용합니다.

직원 ID 제휴로 에이전트 레지스트리에 액세스할 때 발생하는 오류

직원 ID 제휴로 인증된 경우Google Cloud 콘솔에서 Agent Registry에 액세스하거나 Google Cloud CLI를 사용하면 다음 오류가 발생합니다.

Google Cloud 콘솔에 다음과 같은 일반적인 로드 오류가 표시됩니다.

• '로드 중에 오류가 발생했습니다…'
• '서버에서 요청을 처리할 수 없습니다.'
• '로드할 수 없음'

또한 gcloud 명령어는 error 13: an internal error has occurred과 같은 내부 오류를 반환할 수 있습니다.

이 문제를 해결하려면 Cloud ID 또는 Google Workspace를 통해 관리되는 표준 Google 계정으로 인증하세요. 계정에 roles/agentregistry.admin 또는 roles/agentregistry.viewer과 같은 필수 권한이 있는지 확인합니다.

Gemini Enterprise Agent Platform 거버넌스 서비스는 제휴 ID에 대한 지원이 제한적입니다. 제휴 주 구성원에게 더 광범위한 IAM 역할을 부여해도 문제가 해결되지 않습니다.

보안 발견 사항으로 인해 스킬 버전 다운로드가 차단됨

스킬의 스캔 정책이 ENABLED_BLOCKING로 설정되어 있고 버전에 보안 발견 사항이 있는 경우 스킬 버전 페이로드를 다운로드하려고 하면 다음 오류가 발생합니다.

FAILED_PRECONDITION: cannot download skill revision with scan findings when scanning policy is ENABLED_BLOCKING

이 문제를 해결하려면 다음 중 한 가지를 따르세요.

1. gcloud agent-registry findings list 명령어를 실행하여 버전에서 감지된 보안 발견 항목을 검사합니다. 이 명령어를 사용하려면 roles/agentregistry.admin 역할이 필요합니다.
2. 승인되지 않은 네트워크 이그레스 코드 삭제, 노출된 사용자 인증 정보 삭제, 프롬프트 인젝션 패턴 삭제 등 로컬 소스 파일에서 발견 항목을 해결합니다.
3. 새 스킬 버전을 업로드하고 등록합니다.
4. 또는 승인된 테스트 또는 스테이징 환경에서 작업하는 경우 --scanning-policy=enabled-nonblocking를 사용하여 기술의 스캔 정책을 ENABLED_NONBLOCKING로 업데이트합니다. 자세한 내용은 보안 문제에 대한 기술 스캔을 참조하세요.

기본 버전 설정 또는 차단 정책 사용 설정 실패

버전에 발견 항목 또는 대기 중인 스캔 결과가 있을 때 기술의 기본 버전 포인터(--default-revision)를 업데이트하거나 기술의 스캔 정책을 ENABLED_BLOCKING로 변경하면 다음 오류가 발생합니다.

API는 다음 메시지 중 하나와 함께 FAILED_PRECONDITION 오류를 반환합니다.

• cannot set default revision to a revision with scan findings when scanning policy is ENABLED_BLOCKING
• cannot set default revision to a revision with pending scan results when scanning policy is ENABLED_BLOCKING
• cannot set scanning policy to ENABLED_BLOCKING when default revision has scan findings
• cannot set scanning policy to ENABLED_BLOCKING when default revision has pending scan results

이 문제를 해결하려면 다음 단계를 따르세요.

• 스캔이 아직 대기 중(RUNNING)이면 백그라운드 스캔이 완료될 때까지 기다린 후 버전을 기본값으로 설정하거나 ENABLED_BLOCKING를 사용 설정하기 전에 scanResult.scanState가 findings 없이 SUCCEEDED로 확인되는지 확인합니다.
• 대상 또는 현재 기본 버전에 보안 발견 사항이 있는 경우 보안 문제가 해결된 새 버전을 게시하고, scanResult.scanState가 findings가 나열되지 않은 SUCCEEDED로 확인되는지 확인하고, 해당 클린 버전을 기술의 defaultRevision로 설정합니다.

압축되지 않은 크기 제한으로 인해 스킬 버전이 거부됨

압축되지 않은 최대 스캔 크기 한도를 초과하는 기술 버전을 업로드하면 다음 오류가 발생합니다.

장기 실행 작업이 INVALID_ARGUMENT 오류와 함께 실패하거나 버전의 scanResult.scanState가 UNSUPPORTED_FORMAT로 전환됩니다.

이 문제를 해결하려면 다음 중 한 가지를 따르세요.

• ZIP 패키지 내의 압축되지 않은 파일을 검사합니다. 대규모 데이터 세트, 모델 바이너리 또는 불필요한 애셋을 삭제하여 각 파일을 1MB 미만으로, 추출된 총 패키지를 10MB 미만으로 유지합니다.
• 개발 워크플로에서 프로젝트의 빠른 프로토타입 제작을 위해 대용량 파일을 업로드해야 하는 경우 조직 정책에서 허용하는 경우 --scanning-policy=disabled를 사용하여 스킬의 스캔 정책을 DISABLED로 업데이트합니다.

조직 정책으로 인해 기술 스캔을 사용 중지할 수 없음

스캔 정책이 DISABLED로 설정된 스킬을 만들거나 업데이트하거나 이전에 scanningConfig.policy가 DISABLED로 설정된 기존 스킬의 필드를 업데이트하면 다음 오류가 발생합니다.

커스텀 조직 정책 제약 조건 위반 오류와 함께 요청이 실패합니다.

이 문제를 해결하려면 다음 단계를 따르세요.

• 조직에서 resource.scanningConfig.policy == "DISABLED"를 거부하는 agentregistry.googleapis.com/Skill에 custom.skillsScanningEnforcement와 같은 커스텀 조직 정책 제약조건을 적용했습니다.
• 조직 정책이 시행되기 전에 scanningConfig.policy가 DISABLED로 설정된 기존 기술을 업데이트하는 경우 UpdateSkill 요청에 scanningConfig.policy 업데이트를 포함하여 ENABLED_BLOCKING 또는 허용된 값으로 설정합니다.
• 테스트 또는 샌드박스 환경에서 사용 중지된 스캔을 허용하려면 조직 정책 관리자에게 프로젝트에 조건부 예외 태그(예: exempt-scanning-enforcement: true)를 추가해 달라고 요청하세요.

자세한 내용은 조직 정책 서비스를 사용하여 스캔 시행을 참조하세요.

스캔을 사용 설정한 후 스킬 버전이 스캔되지 않음

이전에 업로드된 버전이 있는 기존 스킬에서 스캔을 사용 설정하면 다음 오류가 발생합니다.

기존 버전의 스캔 상태(scanResult.scanState)는 DISABLED로 유지되고 버전이 스캔되지 않으며 보안 발견 사항이 생성되지 않습니다.

스킬에 대한 스캔을 사용 설정하면 스캔이 사용 설정된 후에 생성된 스킬 버전에만 적용됩니다. Agent Registry는 스캔이 사용 설정되기 전에 생성된 버전을 소급하여 스캔하지 않습니다.

이 문제를 해결하려면 스킬의 새 스킬 버전을 업로드하고 등록하세요. 새 버전을 업로드하면 에이전트 레지스트리는 스킬의 업데이트된 스캔 구성에 따라 페이로드를 스캔합니다. 자세한 내용은 스킬 버전 만들기 및 보안 문제 스킬 스캔을 참조하세요.

스킬이 이미 있으므로 CMEK를 구성할 수 없음

기술이 이미 있는 위치에 SkillEncryptionSpec를 설정하거나 업데이트하려고 하면 다음 오류가 발생합니다.

FAILED_PRECONDITION: crypto_key_name can only be set or updated when no Skills exist in this location

해당 위치에 기술이 없는 경우에만 프로젝트 및 위치에서 고객 관리 암호화 키(CMEK)를 구성하거나 업데이트할 수 있습니다.

이 문제를 해결하려면 첫 번째 기술을 등록하기 전에 타겟 위치에서 SkillEncryptionSpec를 구성하거나 Cloud Key Management Service 키를 설정하거나 업데이트하기 전에 해당 위치의 기존 기술을 삭제하세요. 자세한 내용은 기술에 CMEK 구성을 참조하세요.

기술에 대한 Cloud KMS 키 위치가 잘못되었습니다.

필수 Cloud KMS 위치에 없거나 지원되지 않는 기술 위치에 있는 Cloud KMS 키로 SkillEncryptionSpec를 구성하면 다음 오류가 발생합니다.

다음 중 하나를 나타내는 INVALID_ARGUMENT 오류가 표시되면서 요청이 실패합니다.

• crypto_key_name "..." is in location "...", but Skills in location "..." can only be encrypted with a Cloud KMS key in location "..."
• customer-managed encryption keys aren't supported for Skills in location "..."

이 문제를 해결하려면 지원되는 기술 위치(us 또는 eu)에서 CMEK를 구성하고 Cloud KMS 키가 필요한 Cloud KMS 멀티 리전 위치에 있는지 확인합니다.

스킬 위치	필수 Cloud KMS 키 위치
us	us
eu	europe

Cloud KMS는 europe를 유럽 연합 멀티 리전의 위치 식별자로 사용합니다. global를 포함한 다른 위치에서는 CMEK가 지원되지 않습니다. 자세한 내용은 기술에 CMEK 구성을 참조하세요.

CMEK 조직 정책에 의해 스킬 생성이 차단됨

CMEK 조직 정책 제약조건이 적용되는 프로젝트에서 기술 또는 기술 버전을 만들면 다음 오류가 발생합니다.

다음 중 하나를 나타내는 FAILED_PRECONDITION 오류와 함께 요청이 실패합니다.

• constraint "constraints/gcp.restrictNonCmekServices" violated for value "agentregistry.googleapis.com". See https://cloud.google.com/kms/docs/cmek-org-policy#require-cmek for more information.
• constraint "constraints/gcp.restrictCmekCryptoKeyProjects" violated for value "projects/KMS_PROJECT_ID". See https://cloud.google.com/kms/docs/cmek-org-policy#restrict-cmek-projects for more information.

이 문제를 해결하려면 다음 단계를 따르세요.

• constraints/gcp.restrictNonCmekServices를 위반하면 조직에서 Agent Registry에 CMEK 보호를 요구합니다. CMEK 지원 위치(us 또는 eu)에 기술을 만들고 해당 위치에 기술을 만들기 전에 해당 위치에 SkillEncryptionSpec를 구성합니다.
• constraints/gcp.restrictCmekCryptoKeyProjects를 위반하면 위치의 SkillEncryptionSpec에 구성된 Cloud KMS 키가 조직의 constraints/gcp.restrictCmekCryptoKeyProjects 정책에서 허용하지 않는 프로젝트에 속합니다. 해당 위치에 기술이 없는 경우 허용된 프로젝트의 Cloud KMS 키를 참조하도록 SkillEncryptionSpec를 업데이트하거나 조직 정책 관리자에게 키 프로젝트를 허용하도록 요청하세요.

자세한 내용은 조직 정책 서비스를 사용하여 CMEK 적용을 참조하세요.