바인딩 관리

Agent Registry에서 바인딩은 소스 에이전트와 대상 리소스(예: 다른 에이전트, MCP 서버 또는 엔드포인트) 간의 연결을 나타냅니다. 바인딩을 만들면 오케스트레이터 에이전트가 다운스트림 기능과 상호작용할 수 있는 명시적 관계를 설정할 수 있습니다.

바인딩을 사용하여 두 가지 시나리오를 처리합니다.

  • 리소스 연결: 소스 에이전트를 대상 리소스(예: 다른 에이전트, MCP 서버 또는 엔드포인트)에 연결할 수 있습니다. 이 시나리오를 사용하면 기본 오케스트레이터가 전문 하위 에이전트 또는 도구에 작업을 위임하는 다중 에이전트 워크플로를 매핑할 수 있습니다.
  • 위임된 권한: 에이전트를 인증 제공업체와 연결하여 에이전트가 자체 사용자 인증 정보를 사용하거나 개별 사용자를 대신하여 외부 대상 또는 커스텀 도구에 연결할 수 있습니다. 에이전트가 OAuth 토큰 또는 API 키를 사용하여 원격 MCP 서버 또는 도구를 인증해야 하는 경우 이 바인딩이 필요합니다. 바인딩을 사용하면 코드에서 인증 제공업체를 수동으로 정의할 필요가 없습니다. 자세한 내용은 이 문서의 인증 제공업체 바인딩 만들기를 참조하세요.

이 문서에서는 Agent Registry에서 바인딩을 만들고, 보고, 업데이트하고, 삭제하는 방법을 설명합니다.

시작하기 전에

바인딩을 관리하려면 다음 단계를 완료하세요.

  1. Agent Registry를 설정합니다.
  2. 소스 및 대상 구성요소를 등록합니다. 자세한 내용은 에이전트 구성요소 등록을 참고하세요.
  3. 위임된 권한에 대한 바인딩을 구성하려면 에이전트 ID 인증 관리자를 사용하여 인증 제공업체를 만듭니다. 자세한 내용은 도구 및 리소스 인증을 참고하세요.
  4. 이 문서의 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정해야 합니다.

필요한 역할

Agent Registry에서 바인딩을 관리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

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

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

바인딩 만들기

소스 에이전트를 대상 리소스에 연결하는 바인딩을 만듭니다.

gcloud 

gcloud agent-registry bindings create BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --source-identifier="SOURCE_ID" \
  --target-identifier="TARGET_ID"

다음을 바꿉니다.

Terraform

소스 에이전트와 대상 리소스 간에 바인딩을 만들려면 google_agent_registry_binding 리소스를 구성합니다. 바인딩에는 target 블록이 필요합니다.

resource "google_agent_registry_binding" "agent_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Connects a source agent to a target resource."

  source {
    identifier = "urn:agent:my-publisher:my-namespace:SOURCE_AGENT_NAME"
  }

  target {
    identifier = "urn:mcp:my-publisher:my-namespace:TARGET_RESOURCE_NAME"
  }
}

다음을 바꿉니다.

  • REGION: 레지스트리 리전
  • BINDING_NAME: 바인딩에 지정할 고유한 이름
  • DISPLAY_NAME: 바인딩의 인간이 읽을 수 있는 이름
  • SOURCE_AGENT_NAME: 소스 에이전트의 이름
  • TARGET_RESOURCE_NAME: 대상 리소스의 이름(예: MCP 서버 또는 엔드포인트)

인증 제공업체 바인딩 만들기

위임된 권한을 위해 에이전트를 인증 제공업체와 연결할 수 있습니다. 이 바인딩을 만들기 전에 먼저 인증 제공업체를 에이전트 ID 인증 관리자를 사용하여 만들어야 합니다. 자세한 내용은 도구 및 리소스 인증을 참고하세요.

--auth-provider 리소스 이름을 지정할 때는 프로젝트 ID를 사용해야 합니다.

gcloud 

gcloud agent-registry bindings create BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --source-identifier="SOURCE_ID" \
  --auth-provider="projects/PROJECT_ID/locations/REGION/connectors/AUTH_PROVIDER_ID"

AUTH_PROVIDER_ID를 인증 제공업체의 ID로 바꿉니다.

Terraform

Terraform에서 인증 제공업체 바인딩을 구성하려면 커넥터 인증 제공업체의 전체 리소스 경로와 범위 및 계속 URI를 사용하여 auth_provider_binding 블록을 지정합니다.

resource "google_agent_registry_binding" "auth_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"

  source {
    identifier = "urn:agent:my-publisher:my-namespace:SOURCE_AGENT_NAME"
  }

  target {
    identifier = "urn:mcp:my-publisher:my-namespace:TARGET_RESOURCE_NAME"
  }

  auth_provider_binding {
    auth_provider = "projects/PROJECT_ID/locations/REGION/connectors/AUTH_PROVIDER_ID"
    scopes        = [SCOPES]
    continue_uri  = "CONTINUE_URI"
  }
}

다음을 바꿉니다.

  • REGION: 레지스트리 리전
  • BINDING_NAME: 바인딩에 지정할 고유한 이름
  • DISPLAY_NAME: 바인딩의 인간이 읽을 수 있는 이름
  • SOURCE_AGENT_NAME: 소스 에이전트의 이름
  • TARGET_RESOURCE_NAME: 대상 리소스의 이름(예: MCP 서버 또는 엔드포인트)
  • PROJECT_ID: 프로젝트 ID
  • AUTH_PROVIDER_ID: 커넥터 인증 제공업체의 ID
  • SCOPES: 쉼표로 구분된 OAuth2 범위 목록 예: "https://www.googleapis.com/auth/cloud-platform"
  • CONTINUE_URI: 인증 제공업체의 계속 URI(예: https://example.com/continue)

에이전트 코드에서 이러한 바인딩을 사용하는 방법의 예시는 에이전트 개발 키트 (ADK) 코드에서 바인딩 해결을 참고하세요.

바인딩 나열

특정 위치의 모든 바인딩을 나열합니다.

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

바인딩 세부정보 보기

단일 바인딩의 세부정보를 가져옵니다.

gcloud agent-registry bindings describe BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION

바인딩 업데이트

gcloud CLI 플래그를 사용하여 기존 바인딩의 매개변수(예: 표시 이름 또는 설명)를 업데이트합니다.

gcloud 

gcloud agent-registry bindings update BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="NEW_DISPLAY_NAME"

Terraform

Terraform을 사용하여 바인딩의 표시 이름 또는 설명을 업데이트하려면 구성에서 기존 google_agent_registry_binding 리소스를 수정하고 terraform apply를 실행합니다.

바인딩 삭제

리소스 간의 연결을 삭제하려면 바인딩 레코드를 삭제합니다.

gcloud 

gcloud agent-registry bindings delete BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION

Terraform

Terraform 구성에서 바인딩을 나타내는 google_agent_registry_binding 리소스를 삭제한 후 terraform apply를 실행합니다.

다음 단계