Agent Registry에서 바인딩을 사용하면 코드에 연결 또는 인증 세부정보를 하드코딩하지 않고도 조정자 에이전트를 다운스트림 에이전트, MCP 서버, 엔드포인트에 연결할 수 있습니다. Agent Registry에서 바인딩을 만들고, 보고, 업데이트하고, 삭제하여 리소스 연결과 위임된 권한을 관리할 수 있습니다.
시작하기 전에
- Agent Registry 설정
단일 프로젝트 설정의 경우 Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다. 여러 프로젝트에 관리 경계를 구성한 경우 경계 전체 검색 및 등록에 관리 프로젝트 ID를 사용하거나 단일 프로젝트 작업에 구성원 프로젝트 ID를 지정합니다.
소스 및 타겟 구성요소를 등록합니다. 자세한 내용은 등록 모델을 참조하세요.
위임된 권한의 바인딩을 구성하려면 에이전트 아이덴티티 인증 관리자를 사용하여 인증 제공업체를 만듭니다. 자세한 내용은 도구 및 리소스에 인증을 참조하세요.
이 문서의 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정합니다.
필요한 역할
에이전트 레지스트리에서 바인딩을 관리하는 데 필요한 권한을 얻으려면 관리자에게 에이전트 레지스트리가 사용 설정된 거버넌스 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
바인딩 만들기, 업데이트, 삭제:
Agent Registry API 관리자 (
roles/agentregistry.admin) -
바인딩 보기:
Agent Registry API 뷰어 (
roles/agentregistry.viewer)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
바인딩 시나리오
바인딩을 사용하여 리소스를 연결하고 권한을 위임할 수 있습니다. 예를 들어 다음과 같은 시나리오에서 바인딩을 사용할 수 있습니다.
- 리소스 연결: 소스 에이전트를 다른 에이전트, MCP 서버, 엔드포인트와 같은 대상 리소스에 연결합니다. 이 시나리오를 사용하면 기본 조정자가 전문 하위 에이전트 또는 도구에 작업을 위임하는 멀티 에이전트 워크플로를 매핑할 수 있습니다.
- 위임된 권한: 에이전트를 인증 제공업체와 연결하여 에이전트가 자체 사용자 인증 정보를 사용하거나 개별 사용자를 대신하여 외부 대상 또는 커스텀 도구에 연결할 수 있도록 합니다. 에이전트가 OAuth 토큰 또는 API 키를 사용하여 원격 MCP 서버 또는 도구에 인증해야 하는 경우 이 바인딩이 필요합니다. 바인딩을 사용하면 코드에서 인증 제공업체를 수동으로 정의할 필요가 없습니다. 자세한 내용은 이 문서의 인증 제공업체 바인딩 만들기를 참조하세요.
바인딩 만들기
바인딩을 만들어 소스 에이전트를 대상 리소스에 연결합니다.
gcloud
gcloud agent-registry bindings create 명령어를 실행합니다.
gcloud agent-registry bindings create BINDING_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--source-identifier="SOURCE_ID" \
--target-identifier="TARGET_ID"
다음을 바꿉니다.
BINDING_NAME: 바인딩에 지정할 이름(예:my-custom-binding)PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.DISPLAY_NAME: 바인딩에 지정할 인간이 읽을 수 있는 이름(예:My Custom Binding)SOURCE_ID: Uniform Resource Name (URN) 형식의 소스 에이전트 에이전트 식별자입니다.TARGET_ID: URN 형식의 대상 리소스의 레지스트리 식별자(예: 에이전트 식별자, MCP 서버 식별자 또는 엔드포인트 식별자)
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 = "SOURCE_ID"
}
target {
identifier = "TARGET_ID"
}
}
다음을 바꿉니다.
인증 제공업체 바인딩 만들기
위임된 권한을 위해 에이전트를 인증 제공업체와 연결할 수 있습니다. 이 바인딩을 만들기 전에 먼저 인증 관리자를 사용하여 인증 제공업체를 만들어야 합니다. 자세한 내용은 도구 및 리소스에 인증을 참조하세요.
--auth-provider-binding 리소스 이름을 지정할 때는 프로젝트 ID를 사용해야 합니다.
gcloud
--auth-provider-binding 플래그와 함께 gcloud agent-registry bindings create 명령어를 실행합니다.
gcloud agent-registry bindings create BINDING_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--source-identifier="SOURCE_ID" \
--target-identifier="TARGET_ID" \
--auth-provider-binding="projects/PROJECT_ID/locations/REGION/authProviders/AUTH_PROVIDER_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 = "SOURCE_ID"
}
target {
identifier = "TARGET_ID"
}
auth_provider_binding {
auth_provider = "projects/PROJECT_ID/locations/REGION/authProviders/AUTH_PROVIDER_ID"
scopes = [SCOPES]
continue_uri = "CONTINUE_URI"
}
}
다음을 바꿉니다.
REGION: 레지스트리 리전입니다.BINDING_NAME: 바인딩에 지정할 고유 이름입니다.DISPLAY_NAME: 인간이 읽을 수 있는 바인딩 이름입니다.SOURCE_ID: URN 형식의 소스 에이전트의 에이전트 식별자입니다.TARGET_ID: URN 형식의 대상 리소스에 대한 레지스트리 식별자입니다.PROJECT_ID: 프로젝트 ID입니다.AUTH_PROVIDER_ID: 인증 제공업체의 ID입니다.SCOPES: 쉼표로 구분된 OAuth 2.0 범위 목록(예:"https://www.googleapis.com/auth/cloud-platform")CONTINUE_URI: 인증 제공업체의 계속 URI(예:https://example.com/continue)
에이전트 코드에서 이러한 바인딩을 사용하는 방법의 예시는 에이전트 개발 키트 (ADK) 코드에서 바인딩 해결을 참조하세요.
결합 나열
gcloud agent-registry bindings list 명령어를 실행하여 특정 위치의 모든 바인딩을 나열합니다.
gcloud agent-registry bindings list \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.
바인딩 세부정보 보기
gcloud agent-registry bindings describe 명령어를 실행하여 단일 바인딩의 세부정보를 검색합니다.
gcloud agent-registry bindings describe BINDING_NAME \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
BINDING_NAME: 바인딩의 이름입니다.PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.
바인딩 업데이트
표시 이름 또는 설명과 같은 기존 바인딩의 매개변수를 업데이트합니다.
gcloud
gcloud agent-registry bindings update 명령어를 실행합니다.
gcloud agent-registry bindings update BINDING_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="NEW_DISPLAY_NAME"
다음을 바꿉니다.
BINDING_NAME: 업데이트하려는 바인딩의 이름입니다.PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.NEW_DISPLAY_NAME: 바인딩의 인간이 읽을 수 있는 새 이름입니다.
Terraform
Terraform을 사용하여 바인딩의 표시 이름 또는 설명을 업데이트하려면 구성에서 기존 google_agent_registry_binding 리소스를 수정하고 terraform apply를 실행합니다.
바인딩 삭제
리소스 간의 연결을 삭제하려면 바인딩을 삭제합니다.
gcloud
gcloud agent-registry bindings delete 명령어를 실행합니다.
gcloud agent-registry bindings delete BINDING_NAME \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
BINDING_NAME: 삭제할 바인딩의 이름입니다.PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.
Terraform
Terraform 구성에서 바인딩을 나타내는 google_agent_registry_binding 리소스를 삭제한 후 terraform apply를 실행합니다.
다음 단계
- 인증 제공업체 바인딩을 사용하여 도구 및 리소스에 인증하는 방법을 알아보세요.
- ADK를 사용하여 엔드포인트를 확인하고 조정자를 빌드하는 방법을 알아봅니다.