이 페이지에서는 에이전트 레지스트리 관련 문제를 해결하는 방법을 설명합니다.
API 비율 할당량을 초과했습니다.
에이전트 레지스트리 API와 상호작용하거나 콘솔에서 에이전트 레지스트리를 빠르게 탐색하는 경우 이 문제가 발생할 수 있습니다. Google Cloud
429 Too Many Requests
이 문제를 해결하려면 API 클라이언트에 지수 백오프를 구현하여 요청 비율을 관리하세요. 에이전트 레지스트리 API의 기본 비율 할당량은 전역 및 리전별로 분당 1,200개의 요청입니다.
콘솔에서 탭을 전환할 때 제한이 발생하면 잠시 기다렸다가 다시 시도하세요. 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 리소스에 대한 올바른 IAM 권한이 있는지 확인하세요. API는 엄격한 IAM 검사를 적용하고 호출자가 액세스할 수 없는 인증 제공업체를 참조하는 Binding 객체를 삭제합니다. 보안 주체에 인증 제공업체에 대한 필수 액세스 권한과 프로젝트의 roles/agentregistry.viewer 역할이 있는지 확인하세요.