빠른 시작: 에이전트 검색

검색은 에이전트형 워크로드로 개발을 가속화하는 핵심 메커니즘입니다. Agent Registry 내에서 검색하면 중복 통합을 처음부터 빌드하는 대신 기존 '기업 정책 에이전트' 또는 '항공편 예약 에이전트'와 같이 필요한 기술이 있는 기존 에이전트를 찾을 수 있습니다.

이 빠른 시작에서는 Agent Registry에 등록된 에이전트를 검색하는 방법을 보여줍니다.

시작하기 전에

이 빠른 시작을 시작하기 전에 Agent Registry에 에이전트를 등록하세요. 이러한 작업을 수행하려면 프로젝트 ID 도 필요합니다.

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

필요한 역할

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

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

사용 가능한 에이전트 나열

레지스트리 내에 등록되고 색인이 생성된 모든 에이전트의 전체 목록을 봅니다.

콘솔

  1. 콘솔에서 Agent Registry로 이동합니다. Google Cloud

    Agent Registry로 이동

  2. 프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다 .

  3. 에이전트 탭을 선택합니다.

    이 페이지에는 등록된 모든 에이전트와 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.

  4. 에이전트의 전체 세부정보를 보려면 에이전트 이름을 클릭합니다.

gcloud

특정 위치의 모든 에이전트를 나열하려면 agents list 명령어를 사용합니다.

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

다음을 바꿉니다.

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

출력은 다음 예시와 같이 표시됩니다.

- name: projects/1234567890/locations/us-central1/agents/my-travel-agent
  displayName: Travel Orchestrator Agent
  description: 'Decomposes natural language travel requests into sub-tasks.'
  version: 1.0.0
  protocols:
    - type: A2A_AGENT
      protocolVersion: "0.3"
      interfaces:
        - url: https://api.example.com/.well-known/agent-card.json
          protocolBinding: HTTP_JSON
  attributes:
    agentregistry.googleapis.com/system/Framework:
      framework: "google-adk"
    agentregistry.googleapis.com/system/RuntimeIdentity:
      identity: "principal://..."
  card:
    type: A2A_AGENT_CARD
    content: {...}

card 필드에는 사용 가능한 경우 전체 A2A 에이전트 카드 콘텐츠가 포함됩니다.

등록된 에이전트 필터링

에이전트가 여러 개 있거나 특정 에이전트의 등록을 확인하려면 에이전트의 메타데이터를 기준으로 목록을 필터링할 수 있습니다.

콘솔

  1. 콘솔에서 Agent Registry로 이동합니다. Google Cloud

    Agent Registry로 이동

  2. 프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다 .

  3. 에이전트 탭을 선택합니다.

    이 페이지에는 등록된 모든 에이전트와 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.

  4. 에이전트의 위치 또는 런타임 리소스를 기준으로 목록을 필터링합니다.

    • 위치를 기준으로 필터링하려면 위치 메뉴를 클릭하고 필터링할 위치를 선택한 후 적용 을 클릭합니다.
    • 런타임을 기준으로 필터링하려면 런타임 메뉴를 클릭하고 필터링할 런타임을 선택한 후 적용 을 클릭합니다.

    이 페이지에는 선택한 조건에 따라 등록된 에이전트의 필터링된 목록이 표시됩니다.

gcloud

--filter 플래그를 사용하여 특정 키-값 쌍과 일치하는 리소스만 반환하도록 에이전트 목록을 필터링합니다.

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다.
  • REGION: 레지스트리 리전입니다.
  • FILTER_EXPRESSION: 필터링할 에이전트의 필터 표현식입니다. 예를 들어 표시 이름을 기준으로 필터링하려면 을 사용할 수 있습니다displayName='DISPLAY_NAME'. 전역적으로 고유한 식별자 (URN)를 기준으로 필터링하려면 agentId='urn:agent:AGENT_URN'을 사용할 수 있습니다.

에이전트 세부정보 보기

사용할 에이전트를 식별한 경우 런타임 엔드포인트 및 전체 기술 목록을 포함한 전체 메타데이터를 검색할 수 있습니다.

콘솔

  1. 콘솔에서 Agent Registry로 이동합니다. Google Cloud

    Agent Registry로 이동

  2. 프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다 .

  3. 에이전트 탭을 선택합니다.

    이 페이지에는 등록된 모든 에이전트와 이름, 식별자, 설명, 런타임, 위치와 같은 세부정보가 표시됩니다.

  4. 보려는 에이전트의 이름을 클릭합니다.

    세부정보 페이지에는 에이전트 세부정보를 위한 탭이 포함되어 있습니다.

  5. 해당 탭을 클릭하여 특정 에이전트 세부정보를 봅니다.

    사용할 수 있는 기능은 런타임에 따라 다릅니다. **세션** , **플레이그라운드** , **메모리** , **평가** 와 같은 탭은 Vertex AI Agent Engine과 같은 관리형 런타임에서 빌드된 에이전트에 표시되는 특정 기능입니다.

    • 개요: 에이전트의 이름, 식별자, 위치, 설명, 런타임을 포함한 에이전트의 핵심 세부정보입니다. 개요에는 토폴로지 그래프에서 쿼리를 빌드하는 데 필요한 기술과 리소스 URI도 표시됩니다.
    • 모니터링 가능성: 지연 시간, 트래픽, 오류, 토큰 사용량과 같은 애플리케이션 중심의 통계입니다. 이 탭은 Google Cloud Observability 도구와 통합되어 실시간 성능 측정항목과 시스템 수준 사용률을 표시하므로 비용과 사용자 환경을 관리하는 데 도움이 됩니다. 자세한 내용은 모니터링 가능성 개요를 참조하세요.
    • 추적: 복잡한 멀티 에이전트 추론 루프 또는 도구 호출 오류를 실시간으로 디버그하기 위해 입력 및 어시스턴트 메시지의 세부 형식 지정을 포함하여 대화 단계를 단계별로 정확하게 추적합니다. 자세한 내용은 에이전트 추적 보기를 참조하세요.
    • 보안: 콘텐츠 정책 위반, 데이터 유출 위험, 규정 준수 평가를 포함한 Model Armor 및 Security Command Center의 발견 항목입니다. 보안에 대한 자세한 내용은 보안 발견 항목 보기를 참조하세요.
    • 토폴로지: 에이전트, 할당된 에이전트 게이트웨이, 상호작용하는 MCP 서버 간의 관계 및 트래픽 흐름을 시각적으로 보여주는 지도입니다. 에이전트 게이트웨이에 대한 자세한 내용은 에이전트 게이트웨이 개요를 참조하세요. 토폴로지에 대한 자세한 내용은 등록된 에이전트의 그래프 보기를 참조하세요.
    • ID: 정책 적용에 사용되는 에이전트 주 구성원 입니다. 예를 들어 이 ID를 사용하여 도구 및 리소스에 대한 인증을 위한 인증 제공업체 바인딩 을 구성합니다.
    • 세션: 지속적인 대화 기록 및 에이전트와의 활성 상호작용 추적입니다.
    • 플레이그라운드: 에이전트의 동작을 테스트하는 직접 채팅 인터페이스입니다.
    • 메모리: 에이전트와의 이전 대화에서 세부정보를 생성하거나 불러와 상호작용 전반에서 컨텍스트를 유지하는 장기 맞춤설정 기능입니다.
    • 평가: 모든 에이전트 평가 작업의 세부정보입니다. 이 탭을 사용하면 새 평가 작업을 만들고, 측정항목을 업로드하고, 실시간 트래픽 또는 합성 시뮬레이션을 기준으로 에이전트의 인지 성능과 모델 안정성을 평가할 수 있습니다.

gcloud

특정 에이전트의 세부 메타데이터를 보려면 agents describe 명령어를 사용합니다.

gcloud alpha agent-registry agents describe AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

다음을 바꿉니다.

  • AGENT_NAME: 에이전트의 이름입니다(예: my-travel-agent).
  • PROJECT_ID: 프로젝트 ID입니다.
  • REGION: 레지스트리 리전입니다.

에이전트의 엔드포인트, 기술 정의, 기본 프레임워크, 런타임 ID, 전체 A2A 에이전트 카드 페이로드와 같은 출력 전용 메타데이터를 사용하면 에이전트 개발 키트 (ADK) 또는 표준 API 요청을 사용하여 에이전트를 오케스트레이터 워크플로에 안전하게 바인딩할 수 있습니다.

다음 단계