Agent Identity API로 이전

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

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

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

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

에이전트 아이덴티티 API 사용 설정

마이그레이션을 시작하려면 프로젝트에서 새 에이전트 아이덴티티 API를 사용 설정하세요.

아직 사용 설정되지 않은 경우 에이전트 아이덴티티 API를 사용 설정합니다.

API 사용 설정에 필요한 역할

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

API 사용 설정하기

Agent Identity API를 사용 설정하면Google Cloud 콘솔의 에이전트 레지스트리 페이지가 새 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 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"

다음 단계