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

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

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

시작하기 전에

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

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

필요한 역할

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

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

에이전트 및 도구 검색

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

에이전트 검색은 에이전트의 기본 메타데이터, 설명, 설명 A2A 스킬 에이전트 카드에 인라인으로 선언된 것과 일치합니다. MCP 서버 검색은 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 대소문자를 구분하지 않음 예 예 스킬의 논리적 URN (Uniform Resource Name)입니다. 이 필드를 사용하여 특정 게시자의 애셋을 찾습니다. 예를 들어 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 해당 없음 아니요 아니요 스킬이 마지막으로 업데이트된 타임스탬프입니다. 이 필드는 필터에서만 사용할 수 있습니다. <, >, 정확한 일치와 같은 범위 연산자를 지원합니다.

쿼리 문자열은 --query 플래그 또는 query 매개변수를 통해 명령어에 연결되며 논리적 인수를 허용합니다. 검색 요청에서 다음 요소를 사용할 수 있습니다.

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

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

다음 예에서는 특정 표시 이름 프리픽스 및 설명 키워드와 일치하는 스킬을 검색합니다.

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="displayName:db-* AND description:sql"

다음을 바꿉니다.

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

시맨틱 의미로 스킬 검색

다음 예에서는 시맨틱 검색을 실행하여 자연어 쿼리의 개념적 테마와 일치하는 데이터베이스 쿼리 처리와 관련된 스킬을 찾습니다.

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="find skills to handle database queries" \
  --search-type=semantic

다음을 바꿉니다.

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

공개 스킬

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

검색을 실행하면 Agent Registry는 통합을 간소화하기 위해 출력에서 공개 스킬의 논리적 리소스 이름을 로컬 프로젝트에서 호스팅되는 것처럼 표시되도록 동적으로 다시 작성합니다.