빠른 시작: 에이전트 검색

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

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

시작하기 전에

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

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

필요한 역할

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

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

사용 가능한 에이전트 나열

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

콘솔

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

    에이전트 레지스트리로 이동

  2. 프로젝트 선택 도구에서 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. Google Cloud 콘솔에서 Agent Registry로 이동합니다.

    에이전트 레지스트리로 이동

  2. 프로젝트 선택 도구에서 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. Google Cloud 콘솔에서 Agent Registry로 이동합니다.

    에이전트 레지스트리로 이동

  2. 프로젝트 선택 도구에서 Google Cloud 에이전트 레지스트리를 설정한 프로젝트를 선택합니다.

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

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

  4. 보려는 상담사의 이름을 클릭합니다.

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

  5. 해당 탭을 클릭하여 특정 상담사 세부정보를 확인합니다.

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

    • 개요: 에이전트의 이름, 식별자, 위치, 설명, 런타임을 비롯한 에이전트의 핵심 세부정보입니다. 개요에는 토폴로지 그래프에서 쿼리를 빌드하는 데 필요한 기술과 리소스 URI도 표시됩니다.
    • 모니터링 가능성: 지연 시간, 트래픽, 오류, 토큰 사용량과 같은 애플리케이션 중심 통계입니다. 이 탭은 Google Cloud Observability 도구와 통합되어 실시간 성능 측정항목과 시스템 수준 사용률을 표시하므로 비용과 사용자 환경을 관리하는 데 도움이 됩니다. 자세한 내용은 관측 가능성 개요를 참고하세요.
    • 트레이스: 복잡한 멀티 에이전트 추론 루프 또는 도구 호출 오류를 실시간으로 디버그하기 위해 입력 및 어시스턴트 메시지의 세부 형식 지정을 포함하여 대화의 정확한 경로를 단계별로 보여줍니다. 자세한 내용은 에이전트 trace 보기를 참고하세요.
    • 보안: 콘텐츠 정책 위반, 데이터 유출 위험, 규정 준수 평가를 비롯한 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 요청을 사용하여 에이전트를 오케스트레이터 워크플로에 안전하게 바인딩할 수 있습니다.

다음 단계