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

이 페이지에서는 Agent Registry의 문제를 해결하는 방법을 설명합니다.

API 비율 할당량 초과

Agent Registry API와 상호작용하거나 콘솔에서 Agent Registry를 빠르게 탐색하는 경우 이 문제가 발생할 수 있습니다 Google Cloud :

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 백엔드 생성에는 상당한 인프라 프로비저닝이 필요하므로 최대 30분이 걸릴 수 있는 장기 실행 작업 (LRO) 시간이 발생할 수 있습니다. 결과적으로 클라이언트 제한 시간 설정을 구성하고 done 불리언 플래그를 폴링하여 완료를 확인합니다.

사용 가능한 결합을 가져올 때 결과가 비어 있음

인증 제공업체의 사용 가능한 바인딩을 가져오는 경우 이 문제가 발생할 수 있습니다. 바인딩이 존재하는지 확인한 경우에도 API가 empty array 또는 액세스 오류를 반환합니다.

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

302 오류로 인해 스킬 버전 다운로드 실패

?alt=media 쿼리 매개변수와 함께 GetSkillRevision API를 사용하여 스킬 버전 페이로드를 다운로드하려고 하면 이 문제가 발생할 수 있습니다. 요청이 실패하고 다음과 유사한 오류가 반환됩니다.

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

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

스킬 버전 유효성 검사에 실패하거나 FAILED 상태가 표시됨

새 스킬 버전을 만든 후 이 문제가 발생할 수 있습니다. 버전이 FAILED 상태로 전환되고 에이전트에서 로드할 수 없습니다.

이 문제를 해결하려면 유효성 검사 로그를 확인하거나 ZIP 페이로드 콘텐츠를 검사하세요.

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

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

gcloud iap web 명령어를 사용하여 Agent Registry 리소스의 이그레스 정책을 관리하는 경우 이 문제가 발생할 수 있습니다.

NOT_FOUND: Requested entity was not found

이 문제를 해결하려면 gcloud iap web에 전달하는 리소스 플래그가 기본 Agent Registry 하위 리소스 유형과 일치하는지 확인하세요.

  • 외부 API 또는 Google API 이그레스 지점과 같은 엔드포인트의 경우 --endpoint 플래그를 사용합니다.
  • 모델 컨텍스트 프로토콜 서버의 경우 --mcp-server 플래그를 사용합니다.
  • 등록된 에이전트의 경우 --agent 플래그를 사용합니다.

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

IAP 웹 IAM 정책을 적용할 때 권한 거부됨

Agent Registry 리소스에 Identity-Aware Proxy 웹 IAM 정책을 적용하거나 수정하는 경우 이 문제가 발생할 수 있습니다.

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

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

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