Agent Identity API로 이전

이 문서에서는 배포된 에이전트와 인증 제공자를 기존 IAM Connectors API (iamconnectors.googleapis.com)에서 새 Agent Identity API (agentidentity.googleapis.com)로 이전하는 방법을 보여줍니다.

두 API는 미리보기 마이그레이션 기간 동안 나란히 작동하므로 기존 에이전트 대화를 중단하지 않고 워크로드를 마이그레이션할 수 있습니다.

마이그레이션 워크플로에는 다음 작업이 포함됩니다.

  1. Agent Identity API 사용 설정
  2. IAM 허용 정책 업데이트
  3. 에이전트 코드 및 SDK 업데이트
  4. 기존 API 사용 중지

Agent Identity API 사용 설정

이전을 시작하려면 프로젝트에서 새 에이전트 ID API를 사용 설정하세요.

Agent Identity API를 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기

API 사용 설정하기

Agent Identity API를 사용 설정하면Google Cloud 콘솔의 Agent Registry 페이지가 새 API로 전환되어 리소스를 읽고 씁니다.

  • 인증 제공업체를 다시 만들 필요가 없습니다. 새 API는 각 기존 인증 제공자 (예: projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME)를 authProviders 리소스(projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME)로 미러링합니다.

  • Google Cloud 콘솔 또는 gcloud CLI를 사용하여 새로 만든 인증 제공업체는 authProviders/ 리소스로 표시되며 기존 API에는 표시되지 않습니다.

  • 기존 connectors/ 문자열을 사용하는 활성 에이전트는 이전 기간 동안 계속 작동합니다.

IAM 허용 정책 업데이트

에이전트가 새 API 엔드포인트에서 사용자 인증 정보를 가져올 수 있도록 미러링된 인증 제공업체 리소스에 새 IAM 역할을 부여합니다.

예를 들어 기존 connectors/AUTH_PROVIDER_NAME 리소스에서 에이전트의 SPIFFE ID에 커넥터 사용자(roles/iamconnectors.user) 역할을 부여한 경우 새 authProviders/AUTH_PROVIDER_NAME 리소스에서 에이전트 ID 사용자 (roles/agentidentity.user) 역할을 부여합니다.

gcloud alpha agent-identity authProviders add-iam-policy-binding \
    AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

adk web를 사용하여 에이전트를 로컬로 테스트하는 경우 개인 사용자 계정(user:USER_EMAIL)에 roles/agentidentity.user를 부여하세요.

에이전트 코드 및 SDK 업데이트

새 authProviders/ 리소스 계층 구조 및 엔드포인트를 참조하도록 에이전트 코드를 업데이트합니다.

  1. 에이전트 코드의 ADK 버전을 2.3.0 이상으로 업데이트합니다.

  2. 에이전트 코드 (예: agent.py)에서 GcpAuthProviderScheme 리소스 문자열의 connectors/를 authProviders/로 바꿉니다.

    레거시 구성: 

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
)

    새 구성: 

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

  3. 3-legged OAuth만 해당: 에이전트가 REST API를 직접 호출하는 경우 엔드포인트 호스트 이름을 iamconnectorcredentials.googleapis.com에서 agentidentitycredentials.googleapis.com로 업데이트하고 요청 경로에서 connectors/를 authProviders/로 바꿉니다.

  4. 3-legged OAuth만 해당: 프런트엔드 유효성 검사 서버(예: main.py)에서 FinalizeCredentials 엔드포인트 URL을 https://agentidentitycredentials.googleapis.com/v1alpha로 업데이트합니다. 또한 들어오는 요청에서 auth_provider_name를 읽고 FinalizeCredentials 요청 본문의 auth_provider 필드로 설정합니다.

기존 API 사용 중지

IAM 허용 정책을 업데이트하고 에이전트 코드를 배포한 후 에이전트가 새 API를 사용하여 인증하고 사용자 인증 정보를 가져오는지 확인합니다.

활성 워크플로를 모두 이전한 후 프로젝트에서 기존 서비스를 사용 중지합니다.

gcloud services disable iamconnectors.googleapis.com \
    --project="PROJECT_ID"

다음 단계