환경 설정

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 프로젝트 설정

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

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

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

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

필요한 역할 가져오기

Vertex AI Agent Engine을 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• Vertex AI 사용자(roles/aiplatform.user)
• 스토리지 관리자(roles/storage.admin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

서비스 에이전트 권한 설정

Vertex AI Agent Engine에 배포하는 에이전트는 AI Platform Reasoning Engine 서비스 에이전트 서비스 계정을 사용하여 실행됩니다. 이 계정에는 배포된 에이전트에 필요한 기본 권한을 부여하는 Vertex AI Reasoning Engine 서비스 에이전트 역할이 있습니다. IAM 문서에서 기본 권한의 전체 목록을 확인할 수 있습니다.

추가 권한이 필요한 경우 다음 단계에 따라 이 서비스 에이전트에 추가 역할을 부여할 수 있습니다.

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

   IAM으로 이동

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

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

서비스 에이전트 수동 생성

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

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. 저장 버튼을 클릭합니다.

Cloud Storage 버킷 만들기

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

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

Google Cloud 콘솔

1. In the Google Cloud console, go to the Cloud Storage Buckets page.

   Go to Buckets

2. Click add_box Create.
3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
   1. In the Get started section, do the following:
      • Enter a globally unique name that meets the bucket naming requirements.
      • To add a bucket label, expand the Labels section (expand_more), click add_box Add label, and specify a key and a value for your label.
   2. In the Choose where to store your data section, do the following:
      1. Select a Location type.
      2. Choose a location where your bucket's data is permanently stored from the Location type drop-down menu.
         • If you select the dual-region location type, you can also choose to enable turbo replication by using the relevant checkbox.
      3. To set up cross-bucket replication, select Add cross-bucket replication via Storage Transfer Service and follow these steps:

         Set up cross-bucket replication

         1. In the Bucket menu, select a bucket.

         2. In the Replication settings section, click Configure to configure settings for the replication job.

            The Configure cross-bucket replication pane appears.

            • To filter objects to replicate by object name prefix, enter a prefix that you want to include or exclude objects from, then click add Add a prefix.
            • To set a storage class for the replicated objects, select a storage class from the Storage class menu. If you skip this step, the replicated objects will use the destination bucket's storage class by default.
            • Click Done.
   3. In the Choose how to store your data section, do the following:
      1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.
      2. To enable hierarchical namespace, in the Optimize storage for data-intensive workloads section, select Enable hierarchical namespace on this bucket.
   4. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control method for your bucket's objects.
   5. In the Choose how to protect object data section, do the following:
      • Select any of the options under Data protection that you want to set for your bucket.
        • To enable soft delete, click the Soft delete policy (For data recovery) checkbox, and specify the number of days you want to retain objects after deletion.
        • To set Object Versioning, click the Object versioning (For version control) checkbox, and specify the maximum number of versions per object and the number of days after which the noncurrent versions expire.
        • To enable the retention policy on objects and buckets, click the Retention (For compliance) checkbox, and then do the following:
          • To enable Object Retention Lock, click the Enable object retention checkbox.
          • To enable Bucket Lock, click the Set bucket retention policy checkbox, and choose a unit of time and a length of time for your retention period.
      • To choose how your object data will be encrypted, expand the Data encryption section (expand_more), and select a Data encryption method.
4. Click Create.

명령줄

Create a Cloud Storage bucket and configure it as follows:
• STORAGE_CLASS를 원하는 스토리지 클래스로 바꿉니다.
• LOCATION을 원하는 위치(ASIA, EU, US)로 바꿉니다.
• BUCKET_NAME을 버킷 이름 요구사항을 충족하는 버킷 이름으로 바꿉니다.

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.88.0

인증

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를 가져오고 초기화합니다.

import vertexai
from vertexai import agent_engines

vertexai.init(
    project="PROJECT_ID",
    location="LOCATION",
    staging_bucket="gs://BUCKET_NAME",
)

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

• PROJECT_ID는 개발 및 배포할 에이전트의 Google Cloud 프로젝트 ID입니다.
• LOCATION은 지원되는 리전 중 하나이며
• BUCKET_NAME은 에이전트 배포 시 아티팩트를 스테이징하기 위한 Cloud Storage 버킷의 이름입니다.

다음 단계

• 에이전트 개발
• 환경 설정 문제 해결
• 지원 받기