에이전트, 도구, 스킬 검색

에이전트 생태계가 성장함에 따라 적합한 에이전트나 도구를 찾는 것이 중요해집니다. Agent Registry는 에이전트, 에이전트의 기술, 모델 컨텍스트 프로토콜 (MCP) 서버 전반에서 고급 키워드, 접두사, 시맨틱 검색을 실행할 수 있는 검색 기능을 제공합니다.

이 문서에서는 환경 내 기능을 검색하기 위한 검색 쿼리를 구성하는 방법을 설명합니다.

시작하기 전에

Agent Registry에서 에이전트, 도구 또는 스킬을 검색하기 전에 에이전트 또는 MCP 서버를 등록하세요. 이러한 작업을 실행하려면 프로젝트 ID도 필요합니다.

이 문서에서 gcloud CLI 명령어를 사용하려면 Google Cloud CLI 환경을 설정해야 합니다.

필요한 역할

에이전트 등록부에서 에이전트, 도구, 기술을 검색하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 에이전트 등록부 API 뷰어 (roles/agentregistry.viewer) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

에이전트 및 도구 검색

레지스트리 내 기능을 검색하려면 등록된 에이전트와 MCP 서버를 검색하면 됩니다.

에이전트 검색은 기본 메타데이터, 설명, 에이전트 카드에 인라인으로 선언된 설명 A2A 기술과 일치합니다. MCP 서버를 검색하면 설명과 결정적인 도구가 일치합니다.

키워드 검색을 실행하여 에이전트의 A2A 스킬이나 MCP 서버의 도구와 같이 기능 전반에서 특정 용어와 일치하는 리소스를 찾을 수 있습니다. 레지스트리에서 이러한 기능이 구조화되는 방식을 알아보려면 JSON 스키마를 참고하세요. 검색 가능한 필드의 전체 목록은 API 참조를 확인하세요.

키워드로 검색하려면 --search-string 플래그를 제공하세요. 이 매개변수는 자유 형식 텍스트 쿼리를 허용하며 논리 연산자(AND, OR, NOT)를 지원합니다.

예를 들어 항공편 예약을 처리할 수 있는 에이전트를 검색합니다.

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="flight OR booking"

제공하는 특정 도구나 설명에 따라 MCP 서버를 검색할 수도 있습니다. 예를 들어 데이터베이스 도구를 제공하는 MCP 서버를 검색합니다.

gcloud agent-registry mcp-servers search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="database"

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다.
  • REGION: 레지스트리 리전입니다.

접두사 검색은 지연 시간에 맞게 고도로 최적화되어 있으므로 사용자가 입력할 때 애플리케이션이 관련 에이전트와 도구를 동적으로 가져올 수 있습니다.

오케스트레이터 인터페이스나 자동 완성 기능을 빌드하는 경우 Agent Registry에서 접두사 검색을 실행하여 쿼리 문자열의 시작 부분과 일치하는 결과를 가져올 수 있습니다. 접두사 검색은 접미사 와일드 카드 기호(*)를 사용하여 단어의 시작 부분을 일치시킵니다.

예를 들어 표시 이름이 특정 접두사(예: Best_A2A_*)로 시작하는 상담사를 검색합니다.

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="displayName:Best_A2A_*"

마찬가지로 표시 이름이 특정 접두사(예: Prod_Server_*)로 시작하는 MCP 서버를 검색할 수 있습니다.

gcloud agent-registry mcp-servers search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="displayName:Prod_Server_*"

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다.
  • REGION: 레지스트리 리전입니다.

독립형 스킬 검색

Agent Registry에 등록된 독립형 기술을 검색할 수 있습니다. 이 기능을 사용하면 에이전트에 연결할 수 있는 재사용 가능한 기능을 검색할 수 있습니다.

기술을 검색하면 기본 기술 버전이 검색됩니다. 스킬의 기본 버전을 업데이트하려면 스킬 메타데이터 또는 기본 버전 업데이트를 참고하세요.

검색 모드

요구사항에 따라 스킬에 대해 두 가지 검색 모드를 사용할 수 있습니다.

  • 키워드 검색: 표시 이름, 설명, 이름 (URN), 스킬 ID와 같은 기본 메타데이터 속성만 스캔합니다. 이 모드는 지연 시간이 짧은 검색, 일치, 이름 자동 완성에 최적화되어 있습니다. 예를 들어 키워드 또는 표현으로 스킬 검색하기를 참고하세요.
  • 시맨틱 검색: 자연어 안내, 코드 구조, 애셋을 비롯한 SKILL.md 페이로드의 전체 콘텐츠를 자동으로 색인합니다. 이 모드는 개념적 테마를 일치시키며, 사용자의 의도에 따라 관련 기능 번들을 동적으로 검색하는 오케스트레이터 에이전트에 최적화되어 있습니다. 예를 보려면 의미론적 의미로 기술 검색을 참고하세요.

검색 필드 및 구문

메타데이터 또는 키워드 문자열로 검색할 때는 다음 필드에 색인이 생성됩니다.

필드 이름 케이스 동작 접두사 검색 전체 필드 검색 설명
displayName 대소문자를 구분하지 않음 예 예 스킬의 사용자 대상 이름입니다. 이 필드를 사용하여 일반 이름을 검색합니다.
description 대소문자를 구분하지 않음 아니요 예 스킬의 목적과 기능에 대한 자세한 설명입니다. 이 필드를 사용하여 키워드를 일치시킵니다.
name 대소문자를 구분하지 않음 예 예 스킬의 프로그래매틱 식별자입니다. 식별자 문자열의 일치 항목에 이 필드를 사용합니다.
skillId 대소문자를 구분하지 않음 예 예 스킬의 논리적 Uniform Resource Name (URN)입니다. 이 필드를 사용하여 특정 게시자의 애셋을 찾습니다. 예를 들어 Google에서 만든 스킬의 형식은 urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID입니다.
publisher 대소문자를 구분하지 않음 예 아니요 스킬과 연결된 게시자입니다. 이 필드를 사용하여 게시 조직별로 필터링합니다.
frontmatter.name 대소문자를 구분하지 않음 아니요 아니요 SKILL.md 파일의 프런트매터에 정의된 스킬의 이름입니다.
frontmatter.description 대소문자를 구분하지 않음 아니요 아니요 SKILL.md 파일의 프런트매터에 정의된 스킬 설명입니다.
frontmatter.compatibility 대소문자를 구분하지 않음 아니요 아니요 SKILL.md 파일의 프런트매터에 정의된 스킬의 호환성입니다.
frontmatter.license 대소문자를 구분하지 않음 아니요 아니요 SKILL.md 파일의 프런트매터에 정의된 스킬의 라이선스입니다.
createTime 해당 없음 아니요 아니요 스킬이 생성된 타임스탬프입니다. 이 필드는 필터에서만 사용할 수 있습니다. <, >, 정확한 일치와 같은 범위 연산자를 지원합니다.
updateTime 해당 없음 아니요 아니요 스킬이 마지막으로 업데이트된 타임스탬프입니다. 이 필드는 필터에서만 사용할 수 있습니다. <, >, 정확한 일치와 같은 범위 연산자를 지원합니다.

기술을 검색하려면 gcloud CLI의 --query 플래그 또는 REST API의 searchString 매개변수를 사용하여 쿼리 문자열을 제공합니다. 검색 요청에서 다음 구문 요소를 사용할 수 있습니다.

  • 불리언 연산자: AND, OR 또는 NOT 연산자를 포함하여 요구사항을 연결합니다.
  • 필드별 필터: : 연산자를 사용하여 필드를 타겟팅합니다(예: displayName:database).
  • 프리픽스 일치: 서픽스 와일드 카드 기호(*)를 사용하여 특정 프리픽스(예: displayName:cloud-*)로 시작하는 일치 항목을 찾습니다.

키워드 또는 표현식으로 스킬 검색

예를 들어 표시 이름 접두사와 설명 키워드와 일치하는 스킬을 검색합니다.

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="displayName:cloud-* AND description:database" \
  --search-type=keyword

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다.
  • REGION: 레지스트리 리전

의미로 기술 검색

예를 들어 시맨틱 검색을 사용하여 관계형 데이터베이스 관리에 관한 기술을 찾습니다.

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="manage and configure relational databases" \
  --search-type=semantic

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다.
  • REGION: 레지스트리 리전

공개 스킬

Google에서 제공하는 공개 스킬은 전역이며 모든 프로젝트에서 검색할 수 있습니다. 사용 가능한 공개 스킬 목록은 GitHub의 google/skills 저장소를 참고하세요.

검색하면 Agent Registry가 출력에서 공개 스킬의 리소스 이름을 동적으로 다시 작성하여 로컬 프로젝트에서 호스팅되는 것처럼 표시합니다. 이 프로세스를 통해 통합이 간소화됩니다.