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 사용 설정

마이그레이션을 시작하려면 프로젝트에서 새 Agent Identity 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 또는 REST API를 사용하여 만드는 인증 제공업체는 authProviders/ 리소스로 표시되며 기존 API에는 표시되지 않습니다.

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

IAM 허용 정책 업데이트

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

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

gcloud agent-identity auth-providers 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/v1로 업데이트합니다. 또한 수신 요청에서 auth_provider_name를 읽고 FinalizeCredentials 요청 본문에서 auth_provider 필드로 설정합니다.

기존 API 사용 중지

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

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

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

다음 단계