환경 설정

Vertex AI Agent Engine으로 작업하기 전에 환경이 설정되어 있는지 확인해야 합니다. 결제가 사용 설정된 Google Cloud 프로젝트가 있고 필요한 권한이 있어야 하며 Cloud Storage 버킷을 설정하고 Vertex AI SDK for Python을 설치해야 합니다. 다음 주제를 사용하여 Vertex AI Agent Engine으로 작업할 준비를 하세요.

Vertex AI Agent Engine 환경 설정 및 배포를 간소화하는 참조 Terraform 예시를 보려면 agent-starter-pack을 살펴보세요.

로 설정 Google Cloud

Vertex AI Agent Engine을 사용하려면 Google Cloud 프로젝트를 만들면 Google Cloud 됩니다.

Google Cloud 프로젝트

모든 프로젝트는 프로젝트 번호 또는 프로젝트 ID의 두 가지 방법으로 식별될 수 있습니다. PROJECT_NUMBER는 프로젝트를 만들 때 자동으로 생성되며, PROJECT_ID는 사용자가 직접, 또는 프로젝트를 만든 사람이 지정합니다. 프로젝트를 설정하려면 다음 안내를 따르세요.

  1. 계정에 로그인합니다. Google Cloud 를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. Google Cloud신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    8.

필요한 역할 가져오기

Vertex AI Agent Engine을 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Vertex AI 사용자(roles/aiplatform.user) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

에이전트의 ID 및 권한 설정

ID 및 권한을 설정할 때 다음 옵션 중에서 선택하세요.

  • 에이전트 ID (권장) (미리보기): Vertex AI Agent Engine 런타임에서 에이전트를 사용할 때 보안 및 액세스 관리 기능을 제공하려면 Identity Access Management (IAM) 에이전트 ID를 사용합니다. 에이전트 ID는 각 개별 에이전트에 연결됩니다.

  • 서비스 계정: 서비스 계정은 Vertex AI Agent Engine에 배포하는 에이전트 간에 공유됩니다. 서비스 계정에는 두 가지 옵션이 있습니다.

    • 기본 서비스 에이전트: 기본적으로 에이전트는 AI Platform Reasoning Engine 서비스 에이전트를 사용합니다. 이 Google 관리형 서비스 계정에는 배포된 에이전트에 필요한 기본 권한이 포함된 Vertex AI Reasoning Engine 서비스 에이전트 역할(roles/aiplatform.reasoningEngineServiceAgent)이 있습니다.
    • 커스텀 서비스 계정: 에이전트가 사용할 자체 서비스 계정을 지정할 수 있습니다. 이렇게 하면 에이전트에게 부여된 권한을 더 세부적으로 관리할 수 있습니다.

에이전트 ID

에이전트를 배포하기 전에 IAM 정책을 설정하려면 에이전트 코드를 배포하지 않고 에이전트 ID를 만들면 됩니다. 이렇게 하려면 identity_type 필드만 사용하여 Agent Engine 인스턴스를 만듭니다.

remote_app = client.agent_engines.create(
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
      },
)

에이전트 ID로 Agent Engine 인스턴스를 만든 후 다음 작업을 할 수 있습니다.

  1. 다음 권장 역할로 에이전트 ID를 프로비저닝합니다.

    • roles/serviceusage.serviceUsageConsumer: 에이전트에게 프로젝트의 할당량 및 Vertex AI SDK를 사용할 수 있는 권한을 부여합니다.

  2. 사용 사례에 필요한 경우 에이전트 ID에 추가 역할을 부여합니다.

  3. agent_engine.update(...)를 사용하여 에이전트 코드를 추가합니다.

기본 서비스 에이전트

기본적으로 AI Platform Reasoning Engine 서비스 에이전트 가 사용됩니다. IAM 문서에서 기본 권한의 전체 목록을 확인할 수 있습니다.

에이전트에 기본 권한 외의 권한이 필요한 경우 이 서비스 에이전트에 추가 역할을 부여할 수 있습니다.

  1. IAM 페이지로 이동하여 'Google 제공 역할 부여 포함' 체크박스를 선택합니다.

    IAM으로 이동

  2. service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com와 일치하는 주 구성원을 찾습니다.

  3. 수정 버튼을 클릭한 다음 저장 버튼을 클릭하여 주 구성원에 필요한 역할을 추가합니다.

기본 서비스 에이전트 수동 생성

Reasoning Engine 서비스 에이전트는 Vertex AI Agent Engine 배포 중에 자동으로 프로비저닝되지만, 사전에 수동으로 생성해야 하는 시나리오가 있을 수 있습니다. 이는 배포 프로세스에 필요한 권한이 있고 잠재적인 배포 실패를 방지할 수 있도록 서비스 에이전트에 특정 역할을 부여해야 하는 경우에 특히 중요합니다.

Reasoning Engine 서비스 에이전트를 수동으로 생성하는 단계는 다음과 같습니다.

  1. Google Cloud CLI를 사용하여 Reasoning Engine 서비스 에이전트를 생성합니다.

    gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

  2. IAM 페이지로 이동하여 액세스 권한 부여를 클릭합니다.

    IAM으로 이동

  3. 주 구성원 추가 섹션의 새 주 구성원 필드에 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com를 입력합니다.

  4. 역할 할당 섹션에서 필요한 역할을 찾아 선택합니다.

  5. 저장 버튼을 클릭합니다.

커스텀 서비스 계정

자체 서비스 계정을 사용하려면 에이전트를 실행하는 데 필요한 권한을 부여해야 합니다. 커스텀 서비스 계정에 Vertex AI 사용자 역할(roles/aiplatform.user)이 필요할 수 있습니다.

  1. 서비스 계정이 없으면 만듭니다. 서비스 계정 만들기를 참조하세요.

  2. 서비스 계정에 Vertex AI 사용자(roles/aiplatform.user) 역할을 부여합니다.

  3. 에이전트 코드에 필요한 다른 역할을 서비스 계정에 부여합니다.

  4. 이 서비스 계정으로 에이전트를 배포하려면 이 커스텀 서비스 계정에 서비스 계정 사용자 역할(roles/iam.serviceAccountUser)을 직접 부여합니다.

  5. 에이전트를 배포할 때 커스텀 서비스 계정의 이메일 주소를 지정합니다. 자세한 내용은 커스텀 서비스 계정 구성을 참조하세요.

프로젝트 간 커스텀 서비스 계정

커스텀 서비스 계정이 다른 프로젝트에 있는 경우 서비스 계정이 있는 프로젝트와 에이전트를 배포하는 프로젝트 모두에서 추가 구성이 필요합니다.

  1. 프로젝트 간 서비스 계정 사용 중지 조직 정책: 서비스 계정이 있는 프로젝트에서 iam.disableCrossProjectServiceAccountUsage 조직 정책이 적용되지 않는지 확인합니다. 자세한 내용은 프로젝트 간 서비스 계정 사용 시행 중지 를 참조하세요.

  2. Vertex AI 서비스 에이전트에 권한 부여: 서비스 계정이 있는 프로젝트에서 에이전트를 배포할 프로젝트의 Vertex AI 서비스 에이전트 (service-RESOURCE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) 에 서비스 계정 토큰 생성자 (roles/iam.serviceAccountTokenCreator) 역할을 부여합니다.

  3. 커스텀 서비스 계정에 권한 부여: 에이전트를 배포할 프로젝트에서 커스텀 서비스 계정에 필요한 역할을 부여합니다. 여기에는 일반적으로 Vertex AI 사용자 역할(roles/aiplatform.user)과 에이전트 코드에 필요한 기타 역할이 포함됩니다.

(선택사항) Cloud Storage 버킷 만들기

Cloud Storage 버킷의 필요성은 Vertex AI SDK for Python이 배포 전에 에이전트 코드를 스테이징할 위치가 필요한지 여부에 따라 달라집니다.

  • 소스 파일에서 배포: 에이전트가 파일로 존재합니다. Vertex AI SDK for Python은 이러한 파일을 배포 서비스에 직접 번들링하고 업로드할 수 있으므로 Cloud Storage 스테이징 버킷이 필요하지 않습니다.

  • 에이전트 객체에서 배포: 에이전트가 메모리에 있습니다. Vertex AI SDK for Python은 이 객체를 패키징하고 배포 서비스의 스테이징 영역 역할을 하는 Cloud Storage 버킷에 업로드합니다.

소스 파일에서 배포

소스 파일에서 에이전트를 배포하는 경우 Cloud Storage 버킷이 필요하지 않습니다.

객체에서 배포

에이전트 객체에서 배포하면 Vertex AI Agent Engine은 배포 프로세스의 일부로 배포된 에이전트의 아티팩트를 Cloud Storage 버킷에서 스테이징합니다. Vertex AI를 사용하도록 인증된 주 구성원 (사용자 또는 서비스 계정)에게 이 버킷에 대한 Storage Admin 액세스 권한이 있는지 확인합니다. Vertex AI SDK for Python이 이 버킷에 코드를 작성하기 때문에 이 작업이 필요합니다.

버킷이 이미 설정되어 있으면 이 단계를 건너뛸 수 있습니다. 또는 표준 버킷 만들기 안내를 따르세요.

관리자에게 프로젝트의 스토리지 관리자 (roles/storage.admin) IAM 역할을 부여해 달라고 요청하세요.

Google Cloud 콘솔

  1. 콘솔에서 Cloud Storage **버킷** 페이지로 이동합니다. Google Cloud

    버킷으로 이동

  2. 만들기를 클릭합니다.
  3. 버킷 만들기 페이지에서 버킷 정보를 입력합니다. 다음 단계로 이동하려면 계속 을 클릭합니다.
    1. 시작하기 섹션에서 다음을 수행합니다.
    2. 데이터 저장 위치 선택 섹션에서 다음을 수행합니다.
      1. 위치 유형을 선택합니다.
      2. 위치 유형 드롭다운 메뉴에서 버킷의 데이터가 영구적으로 저장되는 위치를 선택합니다.
      3. 버킷 간 복제를 설정하려면 버킷 간 복제를 선택하고 Storage Transfer Service를 통해 버킷 간 복제 추가를 선택하고 다음 단계를 따르세요.

        버킷 간 복제 설정

        1. 버킷 메뉴에서 버킷을 선택합니다.

        2. 복제 설정 섹션에서 구성 을 클릭하여 복제 작업의 설정을 구성합니다.

          버킷 간 복제 구성 창 이 표시됩니다.

          • 객체 이름 프리픽스를 기준으로 복제할 객체를 필터링하려면 객체를 포함하거나 제외할 프리픽스를 입력한 다음 프리픽스 추가를 클릭합니다.
          • 복제된 객체의 스토리지 클래스를 설정하려면 스토리지 클래스 메뉴에서 스토리지 클래스를 선택합니다. 이 단계를 건너뛰면 복제된 객체가 기본적으로 목적지 버킷의 스토리지 클래스를 사용합니다.
          • 완료 를 클릭합니다.
    3. 데이터 저장 방법 선택 섹션에서 다음을 수행합니다.
      1. 버킷의 기본 스토리지 클래스를 선택하거나 버킷 데이터의 자동 스토리지 클래스 관리에서 자동 클래스를 선택합니다.
      2. 계층적 네임스페이스를 사용 설정하려면 데이터 집약적인 워크로드에 맞게 스토리지 최적화 섹션에서 이 버킷에서 계층적 네임스페이스 사용 설정을 선택합니다.
    4. 객체 액세스를 제어하는 방식 선택 섹션에서 버킷이 공개 액세스 방지를 적용할지 여부를 선택하고 버킷의 객체에 대한 액세스 제어 방법을 선택합니다.
    5. 객체 데이터 보호 방법 선택 섹션에서 다음을 수행합니다.
  4. 만들기 를 클릭합니다.

명령줄

    Cloud Storage 버킷을 만들고 다음과 같이 구성합니다. 
    gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

Python용 Vertex AI SDK 설치 및 초기화

이 섹션에서는 Python 개발 환경을 설정했거나 Colab(또는 이를 설정한 다른 적합한 런타임)을 사용하고 있다고 가정합니다.

(선택사항) 가상 환경을 설정합니다.

또한 종속 항목을 격리하기 위해 가상 환경을 설정하는 것이 좋습니다.

설치

설치해야 하는 종속 항목 집합을 최소화하기 위해 종속 항목을 다음과 같이 분리했습니다.

  • agent_engines: Vertex AI Agent Engine에 배포하는 데 필요한 패키지 집합입니다.
  • adk: 호환되는 에이전트 개발 키트 패키지 집합입니다.
  • langchain: 호환되는 LangChain 및 LangGraph 패키지 집합입니다.
  • ag2: 호환되는 AG2 패키지 집합입니다.
  • llama_index: 호환되는 LlamaIndex 패키지 집합입니다.

Vertex AI SDK for Python을 설치할 때 필요한 종속 항목을 지정할 수 있습니다(쉼표로 구분). 모두 설치하려면 다음 단계를 따르세요.

pip install google-cloud-aiplatform[agent_engines,adk,langchain,ag2,llama_index]>=1.112.0

Agent Engine에서 Agent2Agent(A2A)를 사용하려면 a2a-sdk 패키지도 설치해야 합니다.

pip install a2a-sdk>=0.3.4

인증

Colab

다음 코드를 실행합니다.

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

어떤 조치도 필요하지 않습니다.

로컬 셸

다음 명령어를 실행합니다.

gcloud auth application-default login

SDK 가져오기 및 초기화

다음 코드를 실행하여 Vertex AI Agent Engine용 SDK를 가져오고 초기화합니다.

Google Cloud 프로젝트

import vertexai
from vertexai import agent_engines # For the prebuilt templates

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

각 항목의 의미는 다음과 같습니다.

다음 단계