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 콘솔의 에이전트 레지스트리 페이지가 새 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 리소스에 Agent Identity 사용자 (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을 읽고 auth_provider 필드를 FinalizeCredentials 요청 본문으로 설정합니다.

기존 API 사용 중지

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

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

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

다음 단계