이 페이지에서는 에이전트 레지스트리 관련 문제를 해결하는 방법을 보여줍니다.
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 리소스에 대한 올바른 Identity and Access Management (IAM) 권한이 있는지 확인하세요. API는 엄격한 IAM 검사를 적용하고 호출자가 액세스할 수 없는 인증 제공자를 참조하는 Binding 객체를 삭제합니다. 주 구성원에게 인증 제공업체에 대한 필수 액세스 권한과 프로젝트에 대한 roles/agentregistry.viewer 역할이 있는지 확인합니다.