Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

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

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

API 비율 할당량 초과

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

429 Too Many Requests

이 문제를 해결하려면 API 클라이언트에서 지수 백오프를 구현하여 요청 비율을 관리하세요. Agent Registry API의 기본 비율 할당량은 전역 및 리전별로 분당 요청 1,200개 또는 초당 쿼리 수 20개입니다.

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 페이로드가 크기 제한을 초과하지 않는지 확인합니다. 압축 크기는 500KB 미만, 압축되지 않은 총 크기는 10MB 미만, 개별 파일 크기는 1MB 미만이어야 합니다.
보관 파일에 심볼릭 링크, 디렉터리 순회 요소(예: ..) 또는 절대 경로가 포함되어 있지 않은지 확인합니다.

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

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

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

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

수동으로 등록된 에이전트, MCP 서버, 엔드포인트와 달리 독립형 기술은 쓰기 가능한 Service 리소스나 Agent, McpServer 또는 Endpoint 탐색 리소스를 사용하지 않습니다. 대신 에이전트 레지스트리는 독립형 기술을 최상위 Skill 리소스 및 버전이 지정된 SkillRevision 리소스로 직접 나타냅니다.
독립형 기술을 나열, 검색 또는 검사하려면Google Cloud 콘솔에서 기술 탭을 사용하거나, gcloud alpha agent-registry skills list 또는 gcloud alpha 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

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

등록 상태: 대상 구성요소가 에이전트 레지스트리의 예상 위치에 등록되어 있는지 확인합니다.
식별자 형식: 명령어 또는 정책 바인딩이 레지스트리 식별자 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 또는 원격 MCP 서버를 자동으로 등록하면 us-central1와 같은 개별 리전이 아닌 global 위치에만 McpServer 리소스를 만듭니다.Google Cloud 서비스가 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 서버에는 특정 리전을 사용합니다.

멀티 리전 위치에서 수동 등록 또는 바인딩 생성 실패

us 또는 eu과 같은 멀티 리전 위치에서 에이전트, MCP 서버 또는 엔드포인트를 수동으로 등록하거나 바인딩을 만들려고 하면 다음 오류가 발생합니다.

API는 지원되지 않는 위치 또는 잘못된 인수 오류와 함께 요청을 거부합니다.

이 문제를 해결하려면 us-central1 또는 europe-west1과 같은 지원되는 지역 위치 또는 global 위치를 대신 지정합니다. us 및 eu 멀티 리전 위치는 자동으로 등록된 구성요소 검색과 독립형 기술 등록 또는 검색만 지원합니다. 지원되는 위치 목록은 Agent Registry 위치를 참조하세요.

직원 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 역할을 부여해도 문제가 해결되지 않습니다.

에이전트 레지스트리 문제 해결 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.