Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

에이전트에 수동 등록 사용

에이전트 레지스트리를 사용하면 Google Cloud외부에 호스팅되거나, 지원되지 않는 런타임에서 실행되거나, 여러 Google Cloud 프로젝트에 배포된 A2A 호환 및 표준 REST 에이전트를 수동으로 등록할 수 있습니다. 이러한 에이전트에 대해 Service 리소스를 만들면 AI 생태계 전반에서 엔드포인트와 기능을 검색할 수 있습니다.

에이전트 레지스트리는 중앙 Google Cloud 거버넌스 프로젝트를 사용합니다. 이 문서에서 원격이라는 용어는 별도의 Google Cloud 프로젝트, 온프레미스 환경, 외부 클라우드와 같이 거버넌스 프로젝트 외부에서 호스팅되거나 지원되지 않는 런타임에서 실행되는 에이전트를 의미합니다. 자동 등록은 Agent Registry가 사용 설정된 거버넌스 프로젝트에 배포된 지원되는 리소스만 검색하므로 원격 에이전트를 거버넌스 프로젝트의 레지스트리에 수동으로 등록해야 합니다.

에이전트 유형 및 제한사항

다음 두 가지 유형의 에이전트를 수동으로 등록할 수 있습니다.

A2A 호환 에이전트: A2A_AGENT_CARD 유형으로 Agent2Agent (A2A) 사양을 구현하는 에이전트입니다. 레지스트리는 agent-card.json 에이전트 카드 엔드포인트를 스캔하여 A2A 스킬을 색인 생성합니다.
표준 REST 에이전트: A2A 사양을 구현하지 않고 NO_SPEC 유형을 사용하는 원격 에이전트입니다(예: REST API 엔드포인트를 노출하는 에이전트).

us 및 eu 멀티 리전 위치에서는 수동 등록이 지원되지 않습니다. 지원되는 리전 또는 global 위치를 사용해야 합니다. 자세한 내용은 Agent Registry 위치를 참조하세요.

시작하기 전에

Agent Registry 설정
Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다.
이 문서의 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정합니다.

필요한 역할

Agent Registry에서 에이전트를 수동으로 등록하는 데 필요한 권한을 얻으려면 관리자에게 Agent Registry가 사용 설정된 거버넌스 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

Agent Registry에 에이전트를 등록하려면 Agent Registry API 편집자 (roles/agentregistry.editor) 역할이 필요합니다.
교차 프로젝트 등록의 경우 다른 Google Cloud 프로젝트의 에이전트 메타데이터에 액세스하려면 Agent Registry API 뷰어 (roles/agentregistry.viewer)가 필요합니다.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

표준 공개 URL을 사용하여 에이전트의 엔드포인트 또는 에이전트 카드에 액세스할 수 있거나 사전 구성된 사용자 인증 정보를 통해 인증된 경우 추가 권한이 필요하지 않습니다.

A2A 호환 에이전트 등록

원격 에이전트가 A2A 사양을 구현하는 경우 에이전트 레지스트리를 에이전트의 agent-card.json 페이로드로 전달합니다. 레지스트리는 에이전트 카드를 자동으로 동기화하고 검색을 위해 에이전트의 사용 가능한 A2A 스킬을 색인화합니다.

에이전트를 등록하려면 다음 단계를 따르세요.

콘솔

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

에이전트 레지스트리로 이동
프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
에이전트 추가를 클릭합니다.
에이전트 세부정보 패널에서 다음 세부정보를 입력합니다.
- 유형: A2A를 선택합니다.
- 리전: 에이전트를 등록할 지리적 위치를 선택합니다.
다음 옵션 중 하나를 선택합니다.
- 에이전트 카드 URL을 사용하여 에이전트를 등록하려면 URI에서 탭을 선택하고 URI 필드에 유효한 URL을 입력합니다. 그런 다음 가져오기를 클릭하여 URL에서 에이전트 카드를 가져옵니다.
- 에이전트 카드 콘텐츠를 복사하여 붙여넣으려면 JSON 붙여넣기 탭을 선택하고 agent-card.json 파일의 전체 콘텐츠를 붙여넣습니다.
저장을 클릭합니다.

gcloud

사용하는 사양 플래그에 따라 구성요소가 속하는 리소스 컬렉션이 결정됩니다. 플래그와 리소스 컬렉션의 전체 매핑은 [서비스 리소스 및 검색 리소스](/agent-registry/data-model#service-resources)를 참고하세요.

A2A 에이전트를 등록하려면 에이전트의 에이전트 카드를 로컬 JSON 파일(예: agent-card.json)로 저장한 후 gcloud agent-registry services create 명령어를 실행합니다.

gcloud agent-registry services create AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=a2a-agent-card \
    --agent-spec-content=agent-card.json

사양 파일의 최대 파일 크기는 10KB입니다.

다음을 바꿉니다.

AGENT_NAME: 에이전트에 부여할 ID입니다(예: my-support-agent). ID는 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
PROJECT_ID: 프로젝트 ID입니다.
REGION: 에이전트를 등록할 리전입니다. 특정 리전을 사용하지 않으려면 global 값을 사용하세요.
DISPLAY_NAME: 에이전트에 지정할 인간이 읽을 수 있는 이름(예: Support Agent)

Terraform

구성하는 사양 블록에 따라 구성요소가 속하는 리소스 컬렉션이 결정됩니다. 사양과 리소스 컬렉션의 전체 매핑은 [서비스 리소스 및 검색 리소스](/agent-registry/data-model#service-resources)를 참고하세요.

A2A 호환 에이전트를 등록하려면 google_agent_registry_service 리소스를 구성합니다. A2A_AGENT_CARD 유형과 에이전트 카드 JSON 페이로드를 나타내는 content를 사용하여 agent_spec 블록을 지정합니다.

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type = "A2A_AGENT_CARD"
    content = jsonencode({
      name               = "AGENT_NAME"
      description        = "A custom support agent registered using Terraform."
      version            = "1.0.0"
      capabilities       = {}
      defaultInputModes  = ["text/plain"]
      defaultOutputModes = ["text/plain"]
      supportedInterfaces = [
        {
          url             = "https://api.example.com/v1/agents/support"
          protocolBinding = "JSONRPC"
          protocolVersion = "1.0"
        }
      ]
      skills = [
        {
          id          = "customer_lookup"
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
          tags        = ["support", "customer"]
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

다음을 바꿉니다.

REGION: 에이전트를 등록하는 리전입니다.
AGENT_NAME: 에이전트에 부여할 고유 ID입니다(예: my-support-agent). ID는 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
DISPLAY_NAME: 에이전트에 지정할 인간이 읽을 수 있는 이름(예: Support Agent)

표준 REST 에이전트 등록

표준 REST 에이전트는 이름과 설명으로 검색 가능하지만 A2A 프로토콜을 채택하지 않는 한 검색 가능한 A2A 기술이 없습니다.

A2A 사양을 구현하지 않는 원격 에이전트를 등록하려면 A2A가 아닌 Service 리소스를 만듭니다. Agent Registry는 조정자, 다른 에이전트, Agent Gateway가 에이전트를 검색하고 연결할 수 있도록 엔드포인트 URL을 포함하여 agents 컬렉션의 비A2A 에이전트에 대한 읽기 전용 Agent 리소스를 생성합니다.

Google Cloud 콘솔에서 에이전트 유형을 Non-A2A로 설정하거나 gcloud CLI 명령어에서 --agent-spec-type=no-spec 플래그를 사용하면 AI 에이전트가 등록됩니다. 해당 에이전트를 Endpoint 리소스로 별도로 등록하지 마세요. 데이터베이스 API, 서드 파티 SaaS API, Google API와 같은 비에이전트 REST API 또는 웹 서비스에 대한 에이전트 이그레스 연결을 제어하려는 경우에만 Endpoint 리소스를 등록하세요. 에이전트가 아닌 API 대상을 등록하는 방법은 엔드포인트 등록을 참조하세요.

에이전트를 등록하려면 다음 단계를 따르세요.

콘솔

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

에이전트 레지스트리로 이동
프로젝트 선택 도구에서 Agent Registry를 설정한 Google Cloud 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
에이전트 추가를 클릭합니다.
에이전트 세부정보 패널에서 다음 세부정보를 입력합니다.
- 유형: Non-A2A를 선택합니다.
- 이름: 에이전트의 인간이 읽을 수 있는 표시 이름을 입력합니다(예: Travel Agent).
- 설명: 에이전트의 기능에 대한 설명을 입력합니다(예: A test agent that plans travel itineraries.).
- 리전: 에이전트를 등록할 지리적 위치를 선택합니다.
- 엔드포인트: 에이전트가 호스팅되는 엔드포인트를 입력합니다.
저장을 클릭합니다.

gcloud

표준 REST 에이전트를 등록하고 에이전트가 호스팅되는 엔드포인트 URL을 지정하려면 --agent-spec-type=no-spec 및 --interfaces 플래그와 함께 gcloud agent-registry services create 명령어를 실행합니다.

gcloud agent-registry services create AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=no-spec \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

다음을 바꿉니다.

AGENT_NAME: 에이전트에 부여할 ID입니다(예: my-remote-rest-agent). ID는 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
PROJECT_ID: 프로젝트 ID입니다.
REGION: 레지스트리 리전입니다.
DISPLAY_NAME: 에이전트에 지정할 인간이 읽을 수 있는 이름(예: Remote REST Agent)
ENDPOINT_URL: 에이전트의 API 엔드포인트 URL입니다(예: https://api.example.com/v1/agents/1234).
PROTOCOL: 엔드포인트의 프로토콜 바인딩입니다. 유효한 값은 http-json, grpc 또는 jsonrpc입니다.

Terraform

표준 REST 에이전트를 등록하려면 agent_spec를 NO_SPEC 유형으로 설정하여 google_agent_registry_service 리소스를 구성하고 엔드포인트 인터페이스 연결을 정의합니다.

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

다음을 바꿉니다.

REGION: 에이전트를 등록하는 리전입니다.
AGENT_NAME: 에이전트에 부여할 고유 ID입니다(예: my-remote-rest-agent). ID는 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
DISPLAY_NAME: 에이전트에 지정할 인간이 읽을 수 있는 이름(예: Remote REST Agent)
ENDPOINT_URL: 에이전트의 API 엔드포인트 URL입니다(예: https://api.example.com/v1/agents/1234).
PROTOCOL: 엔드포인트의 프로토콜 바인딩입니다. 유효한 값은 HTTP_JSON, GRPC 또는 JSONRPC입니다.

다른 프로젝트의 에이전트 등록

조직에서 여러 Google Cloud 프로젝트에 에이전트를 배포하고 Agent-to-Anywhere 이그레스 모드에서 중앙 Agent Gateway를 사용하여 트래픽을 제어하는 경우 다른 Google Cloud 프로젝트의 각 원격 에이전트를 중앙 거버넌스 프로젝트 레지스트리에 수동으로 등록해야 합니다. 이 아키텍처에 대한 자세한 내용은 샘플 배포 패턴을 참조하세요.

프로젝트 간 등록 시 고려사항

여러 프로젝트에 에이전트를 등록하기 전에 다음 사항을 검토하세요.

호환되는 위치: Agent Registry 인스턴스, Agent Gateway, Agent Endpoint는 동일한 지리적 리전 또는 global 위치에 있어야 합니다.
자동 검색 제한사항: 자동 교차 프로젝트 검색은 지원되지 않습니다. 각 원격 에이전트를 수동으로 등록해야 합니다.
수명 주기 관리: 에이전트가 실행되는 다른Google Cloud 프로젝트에서 변경사항이 발생해도 에이전트 레지스트리의 수동 항목은 자동으로 업데이트되거나 삭제되지 않습니다. 원격 에이전트가 수정되거나 삭제되면 중앙 레지스트리에서 이러한 항목의 수명 주기를 관리해야 합니다.
이그레스 모드만 해당: Agent Gateway를 사용한 프로젝트 간 거버넌스는 Agent-to-Anywhere 이그레스 게이트웨이에만 지원됩니다. 클라이언트-에이전트 인그레스 게이트웨이를 사용하려면 에이전트와 게이트웨이가 동일한 프로젝트에 있어야 합니다.

원격 에이전트 등록

다른 프로젝트에서 에이전트를 수동으로 등록하려면 다음 단계를 따르세요.

콘솔

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

에이전트 레지스트리로 이동
프로젝트 선택 도구에서 에이전트를 등록할 중앙 거버넌스 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
에이전트 추가를 클릭합니다.
에이전트 세부정보 패널에서 다음 세부정보를 입력합니다.
- 유형: 원격 에이전트가 A2A 프로토콜을 구현하는 경우 A2A를 선택하고 표준 REST 엔드포인트의 경우 A2A가 아님을 선택합니다.
- 리전: 중앙 게이트웨이 및 원격 에이전트 배포와 일치하는 리전을 선택합니다.
에이전트 엔드포인트를 제공합니다.
- A2A 에이전트의 경우 URI에서를 선택하고 원격 에이전트의 에이전트 카드 URL을 입력하거나 JSON 붙여넣기를 선택하고 agent-card.json 콘텐츠를 붙여넣습니다.
- A2A가 아닌 에이전트의 경우 원격 에이전트의 엔드포인트 URL을 입력합니다.
저장을 클릭합니다.

gcloud

A2A 에이전트: 다른 프로젝트에서 A2A 에이전트를 등록하려면 gcloud agent-registry services create 명령어를 실행합니다.

gcloud agent-registry services create AGENT_NAME \
    --project=CENTRAL_PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=a2a-agent-card \
    --agent-spec-content=agent-card.json

REST 에이전트: 다른 프로젝트에서 표준 REST 에이전트를 등록하려면 gcloud agent-registry services create 명령어를 실행합니다.

gcloud agent-registry services create AGENT_NAME \
    --project=CENTRAL_PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=no-spec \
    --interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL

다음을 바꿉니다.

AGENT_NAME: 중앙 레지스트리에 있는 에이전트의 ID입니다(예: remote-support-agent). ID는 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
CENTRAL_PROJECT_ID: 중앙 거버넌스 프로젝트의 프로젝트 ID입니다.
REGION: 에이전트를 등록하고 중앙 게이트웨이와 원격 에이전트가 있는 리전입니다(예: us-central1).
DISPLAY_NAME: 인간이 읽을 수 있는 에이전트 이름입니다(예: Remote Support Agent).
REMOTE_ENDPOINT_URL: 다른 Google Cloud 프로젝트에서 실행되는 원격 에이전트의 엔드포인트 URL입니다(예: https://remote-support-agent-abc123.us-central1.run.app 또는 https://api.example.com/v1/agents/support).
PROTOCOL: 엔드포인트의 프로토콜 바인딩입니다. 유효한 값은 http-json, grpc 또는 jsonrpc입니다.

Terraform

Terraform을 사용하여 중앙 거버넌스 프로젝트에 원격 에이전트를 등록하려면 google_agent_registry_service 리소스를 구성하고 중앙 프로젝트를 지정합니다.

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project AGENT_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "REMOTE_ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.remote_agent.registry_resource
}

다음을 바꿉니다.

CENTRAL_PROJECT_ID: 중앙 거버넌스 프로젝트의 프로젝트 ID입니다.
REGION: 에이전트를 등록하고 중앙 게이트웨이와 원격 에이전트가 있는 리전입니다(예: us-central1).
AGENT_NAME: 레지스트리에 있는 에이전트의 고유 ID입니다(예: remote-support-agent). ID는 4~63자(영문 기준)여야 하며 소문자, 숫자, 하이픈만 포함할 수 있습니다.
DISPLAY_NAME: 인간이 읽을 수 있는 에이전트 이름입니다(예: Remote Support Agent).
AGENT_PROJECT_ID: 원격 에이전트가 호스팅되는 별도의 Google Cloud 프로젝트의 프로젝트 ID입니다.
REMOTE_ENDPOINT_URL: 다른 Google Cloud 프로젝트에서 실행되는 원격 에이전트의 엔드포인트 URL입니다(예: https://remote-support-agent-abc123.us-central1.run.app 또는 https://api.example.com/v1/agents/support).
PROTOCOL: 엔드포인트의 프로토콜 바인딩입니다. 유효한 값은 HTTP_JSON, GRPC 또는 JSONRPC입니다.

등록 확인

에이전트를 등록한 후 Agent Registry가 Service 리소스를 성공적으로 처리하고 해당 읽기 전용 Agent 리소스를 만들었는지 확인합니다.

콘솔

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

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

페이지에 등록된 모든 에이전트 목록과 세부정보가 표시됩니다.

gcloud

gcloud agent-registry agents list 명령어를 사용하여 레지스트리에 등록된 에이전트를 나열합니다.

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

에이전트가 여러 개 있거나 단일 에이전트의 등록을 확인하려면 에이전트의 메타데이터로 목록을 필터링하면 됩니다.

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

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
REGION: 에이전트를 등록할 리전입니다. 특정 리전을 사용하지 않으려면 global 값을 사용하세요.
FILTER_EXPRESSION: 필터링할 에이전트의 필터 표현식입니다. 예를 들어 표시 이름으로 필터링하려면 displayName='DISPLAY_NAME'를 사용하면 됩니다. 전역적으로 고유한 에이전트 식별자(URN)로 필터링하려면 agentId='urn:agent:AGENT_URN'를 사용하면 됩니다.

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

다음 단계

등록된 에이전트를 관리하는 방법 알아보기
관리형 런타임에 배포된 에이전트를 등록하는 권장 방법인 자동 등록에 대해 알아봅니다.

에이전트에 수동 등록 사용 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

에이전트 유형 및 제한사항

시작하기 전에

필요한 역할

A2A 호환 에이전트 등록

콘솔

gcloud

Terraform

표준 REST 에이전트 등록

콘솔

gcloud

Terraform

다른 프로젝트의 에이전트 등록

프로젝트 간 등록 시 고려사항

원격 에이전트 등록

콘솔

gcloud

Terraform

등록 확인

콘솔

gcloud

Terraform

다음 단계

에이전트에 수동 등록 사용