자동 등록 사용

Agent Registry는 지원되는 Google Cloud 런타임에서 호스팅되는 에이전트를 등록할 수 있으며, 사용자가 Agent Registry API를 수동으로 호출하지 않아도 됩니다. 런타임에 따라 이 등록 프로세스는 자동으로 실행되거나 배포 중에 선택 구성 단계가 필요합니다.

이 문서에서는 지원되는 런타임에서 에이전트의 검색을 사용 설정하는 방법을 설명합니다. 에이전트를 외부 또는 지원되지 않는 런타임에서 호스팅하는 경우 수동 등록 사용을 참고하세요.

등록 중에 에이전트에서 추출된 메타데이터와 기술은 에이전트의 프로토콜에 따라 다릅니다. 자세한 내용은 에이전트 등록을 참고하세요.

시작하기 전에

상담사를 등록하기 전에 상담사 등록처를 설정하세요. 등록을 확인하려면 프로젝트 ID가 필요합니다.

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

Agent Runtime에서 에이전트 등록

Gemini Enterprise Agent Platform의 에이전트 런타임으로 에이전트를 개발하고 배포하는 경우 Agent Registry에 자동으로 등록됩니다.

Agent2Agent (A2A) 프로토콜은 에이전트가 기능과 신원을 선언할 수 있는 개방형 표준입니다. 다음 예에서는 A2A 프로토콜을 구현하는 에이전트를 Agent Runtime에 배포하는 방법을 보여줍니다. 자세한 내용은 에이전트 배포를 참고하세요.

# Create and deploy the agent
# This action automatically registers the agent in Agent Registry
remote_agent = client.agent_engines.create(
    agent=my_a2a_agent, # Your defined A2A object
    config={
        "display_name": "my-support-agent",
        "description": "An agent that handles support tickets.",
        "requirements": ["google-cloud-aiplatform[agent_engines,langchain]"],
    },
)

Agent Runtime에서 에이전트를 업데이트하거나 삭제하면 Agent Registry에서 이러한 변경사항을 자동으로 동기화합니다.

기본 제공 Google 에이전트 등록

Google Workspace 및 Gemini Enterprise 에이전트와 같은 내장 Google 에이전트는 에이전트 레지스트리에 자동으로 등록됩니다. 구성 또는 배포 단계를 수행할 필요가 없습니다. 이러한 에이전트는 등록기관 내에서 검색할 수 있도록 수집됩니다.

GKE에서 에이전트 등록

배포에 registry.gke.io/functional-type: "AGENT" 라벨을 추가하여 Google Kubernetes Engine (GKE)에 배포된 에이전트를 등록할 수 있습니다. 이 라벨은 배포를 AI 에이전트로 식별하여 에이전트 레지스트리가 인트로스펙션 스캔을 실행할 수 있도록 합니다.

참고: GKE는 하위 호환성을 위해 apphub.cloud.google.com/functional-type: "AGENT" 주석도 지원합니다. 하지만 GKE 배포에는 registry.gke.io/functional-type: "AGENT" 라벨을 사용하는 것이 좋습니다.

에이전트의 기술 자동 검색을 사용 설정하려면 a2a-protocol.org/agent-card 주석도 제공해야 합니다. 수집 컨트롤러는 이 주석을 사용하여 A2A 에이전트 카드를 쿼리합니다. 또한 iam.gke.io/spiffe-identity-type: agent-identity 주석을 사용하여 워크로드 아이덴티티를 구성하여 안전한 인증된 통신을 지원합니다.

다음 예시에서는 이러한 구성을 사용하는 GKE 에이전트 배포 매니페스트를 보여줍니다. 자세한 내용은 AI 에이전트 배포 및 오케스트레이션을 참고하세요.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
  labels:
    # GKE takes this label and registers the agent to Agent Registry
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  selector:
    matchLabels:
      app: my-agent
  template:
    metadata:
      annotations:
        # Workload Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
      labels:
        app: my-agent
    spec:
      containers:
      - name: server
        image: gcr.io/my-project/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
apiVersion: v1
kind: Service
metadata:
  name: my-agent-service
  labels:
    app: my-agent
spec:
  type: ClusterIP
  ports:
  - port: 8080
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: my-agent

배포가 적용되면 GKE 클러스터가 에이전트에서 메타데이터를 가져오고 에이전트 레지스트리 데이터 모델에 직접 동기화하려고 자동으로 시도합니다.

등록 확인

에이전트를 나열하여 에이전트 레지스트리가 에이전트를 성공적으로 등록했는지 확인할 수 있습니다.

콘솔

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

   Agent Registry로 이동

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

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

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

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

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

   페이지에 선택한 조건에 따라 필터링된 등록된 상담사 목록이 표시됩니다.

gcloud

상담사의 메타데이터를 기준으로 목록을 필터링할 수 있습니다. Agent Registry용 Google Cloud CLI 환경을 설정했는지 확인한 후 다음을 실행합니다.

gcloud 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'를 사용하면 됩니다.

기본 제공 Google 에이전트는 에이전트가 배포된 위치에 따라 달라지는 URN 형식을 사용합니다. 예를 들어 googleapis.com를 사용하여 목록을 필터링하여 기본 제공 Google Workspace 에이전트를 찾을 수 있습니다. --filter="agentId:'urn:agent:googleapis.com:*'"

Terraform

google_agent_registry_agent 데이터 소스를 사용하여 다른 Terraform 구성에서 등록된 에이전트를 참조합니다.

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}

다음을 바꿉니다.

• REGION: 레지스트리 리전입니다.
• DISPLAY_NAME: 에이전트의 사람이 읽을 수 있는 표시 이름입니다.