바인딩 관리

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

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

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

이 문서에서는 에이전트 레지스트리에서 바인딩을 생성, 보기, 업데이트, 삭제하는 방법을 설명합니다.

시작하기 전에

바인딩을 관리하려면 다음을 완료해야 합니다.

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

필요한 역할

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

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

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

바인딩 만들기

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

gcloud alpha 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: MCP 서버 식별자와 같은 URN 형식의 타겟 리소스 식별자입니다.

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

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

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

gcloud alpha 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로 바꿉니다.

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

결합 나열

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

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

바인딩 세부정보 보기

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

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

바인딩 업데이트

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

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

바인딩 삭제

리소스 간 연결을 삭제하려면 바인딩 레코드를 삭제하세요.

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

다음 단계