에이전트에 자동 등록 사용

에이전트 레지스트리를 사용하면 개발자와 조정자 에이전트가 레지스트리 리소스를 수동으로 만들지 않고도 에이전트를 검색할 수 있도록 지원되는 Google Cloud 런타임에서 에이전트의 자동 등록을 구성할 수 있습니다. 런타임에 따라 등록은 기본적으로 또는 선택적 배포 단계를 통해 수행되며 색인 생성된 메타데이터는 구현 프로토콜에 따라 달라집니다.

자동 등록은 Agent Registry가 사용 설정된 거버넌스 프로젝트 내에 배포된 지원되는 리소스만 검색합니다. 다른Google Cloud 프로젝트에 배포된 원격 에이전트를 등록하려면 다른 프로젝트에서 에이전트 등록을 참조하세요. 외부 또는 지원되지 않는 런타임에서 호스팅되는 원격 에이전트의 경우 에이전트에 수동 등록 사용을 참조하세요.

자동으로 색인이 생성된 메타데이터

자동 등록 중에 에이전트에 대해 색인이 생성되는 메타데이터와 기능은 에이전트가 Agent2Agent (A2A) 프로토콜을 구현하는지 여부에 따라 달라집니다.

• A2A 프로토콜을 구현하는 에이전트: 에이전트 레지스트리는 에이전트의 /.well-known/agent-card.json 에이전트 카드를 쿼리하여 에이전트 레지스트리에 공지된 A2A 기술 및 기능을 자동으로 추출합니다.
• A2A 프로토콜을 구현하지 않는 에이전트: Agent Registry는 에이전트를 등록하지만 에이전트가 호스팅되는 엔드포인트 URL, 에이전트 ID, A2A 기술과 같은 메타데이터를 자동으로 캡처할 수 없습니다. 예를 들어 표준 REST 또는 gRPC 엔드포인트를 노출하는 에이전트입니다. 기능을 비A2A 에이전트와 연결하려면 수동 등록 또는 스킬 등록을 사용합니다.

시작하기 전에

1. Agent Registry 설정

2. Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다.

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

Agent Runtime에서 에이전트 등록

Gemini Enterprise Agent Platform의 Agent Runtime을 사용하여 에이전트를 개발하고 배포하는 경우 Agent Registry에 자동으로 등록됩니다.

다음 예시에서는 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에서 에이전트 등록

Google Kubernetes Engine (GKE)에 배포된 에이전트를 등록하려면 배포 매니페스트에 필수 Kubernetes 라벨 및 주석을 추가합니다. 다음 예시에서는 자동 등록을 위해 구성된 Kubernetes Deployment 및 Kubernetes Service를 정의하는 GKE 매니페스트를 보여줍니다.

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:
      labels:
        app: my-agent
      annotations:
        # Agent Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
    spec:
      containers:
      - name: server
        image: gcr.io/PROJECT_ID/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
# Kubernetes Service for in-cluster network routing to the agent pod
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

PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

배포 매니페스트를 구성하고 적용하려면 다음을 수행합니다.

1. Deployment 매니페스트의 metadata.labels에 registry.gke.io/functional-type: "AGENT" 라벨을 추가합니다. 이 라벨은 배포를 AI 에이전트 워크로드로 식별하여 GKE 클러스터 런타임 컨트롤러가 워크로드를 검사하고 에이전트를 에이전트 레지스트리에 등록하도록 지시합니다.

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

2. Deployment 매니페스트의 metadata.annotations에서 a2a-protocol.org/agent-card 주석을 제공하여 에이전트의 A2A 기술 자동 검색을 사용 설정합니다. GKE 수집 컨트롤러는 이 주석을 사용하여 A2A 에이전트 카드를 쿼리합니다.

3. 포드 템플릿의 spec.template.metadata.annotations에서 iam.gke.io/spiffe-identity-type: agent-identity 주석으로 에이전트 ID를 구성하여 인증된 통신을 사용 설정합니다.

4. 배포 매니페스트를 클러스터에 적용합니다. 자세한 내용은 AI 에이전트 배포 및 조정을 참조하세요.

   배포를 적용하면 GKE 클러스터 런타임 컨트롤러가 워크로드 컨테이너를 자동으로 검사하고 주석에 선언된 에이전트 카드 엔드포인트를 쿼리합니다. 그런 다음 에이전트의 메타데이터와 A2A 기술을 Agent Registry의 읽기 전용 Agent 검색 리소스에 직접 동기화합니다.

Cloud Run에서 에이전트 등록

--functional-type=agent 및 --identity-type=agent-identity 플래그를 지정하여 에이전트를 Cloud Run 서비스 또는 작업으로 배포할 때 자동으로 등록할 수 있습니다. --functional-type=agent 플래그는 Cloud Run 서비스 또는 작업을 표준 컨테이너화된 워크로드가 아닌 AI 에이전트로 식별하여 Cloud Run이 에이전트를 에이전트 레지스트리에 등록하도록 지시합니다. 등록 중에 Cloud Run은 에이전트 이름과 AGENT 유형을 레지스트리에 자동으로 추가합니다.

--functional-type=agent로 구성된 워크로드는 --identity-type=agent-identity 플래그를 지정해야 합니다. 다른 ID 유형으로 배포하면 오류가 발생합니다.

새 Cloud Run 서비스 또는 작업이나 기존 Cloud Run 서비스 또는 작업에서 자동 등록을 구성하려면 Cloud Run용 Gemini Enterprise Agent Platform 기능 구성을 참조하세요. Cloud Run에서 A2A 호환 에이전트를 준비, 컨테이너화, 배포하려면 Cloud Run에 A2A 에이전트 배포를 참조하세요.

등록 확인

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

콘솔

1. Google Cloud 콘솔에서 에이전트 레지스트리로 이동합니다.

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

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

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

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

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

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

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

gcloud

에이전트의 메타데이터로 목록을 필터링할 수 있습니다. 에이전트 레지스트리에 대해 gcloud CLI 환경을 설정했는지 확인한 후 gcloud agent-registry agents list 명령어를 실행합니다.

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) 형식을 사용합니다. 예를 들어 --filter="agentId:'urn:agent:googleapis.com:*'"를 사용하여 googleapis.com 게시자에 대한 목록을 필터링하여 기본 제공 Google Workspace 에이전트를 검색할 수 있습니다.

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: 인간이 읽을 수 있는 에이전트의 표시 이름입니다.