환경 설정

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으로 설정

Google Cloud 프로젝트를 만들거나 Vertex AI(Express 모드)에 가입하여 Vertex AI Agent Engine용으로 Google Cloud 을 설정할 수 있습니다.

Google Cloud 프로젝트

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

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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, and Cloud Trace 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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, and Cloud Trace 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

참고: API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 이 권한이 없는 경우 관리자에게 서비스 사용량 관리자 (roles/serviceusage.serviceUsageAdmin) 역할을 부여해 달라고 요청하세요.

익스프레스 모드

익스프레스 모드의 Vertex AI의 안내에 따라 익스프레스 모드로 Vertex AI Agent Engine을 설정합니다.

익스프레스 모드로 Vertex AI Agent Engine을 설정한 후 Python용 Vertex AI SDK 설치 및 초기화 단계로 건너뛸 수 있습니다.

필요한 역할 가져오기

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

프리뷰

이 기능에는 서비스별 약관이 적용됩니다. 정식 버전(GA) 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

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

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

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

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

   • roles/aiplatform.expressUser: 추론, 세션, 메모리 실행에 대한 액세스 권한을 부여합니다.

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

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

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

기본 서비스 에이전트

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

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

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

   IAM으로 이동

2. [e-mail]와 일치하는 주 구성원을 찾습니다.

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

   참고: Google Cloud CLI 명령어에 대한 응답에는 Vertex AI 서비스 에이전트만 표시될 수 있습니다. 그러나 Reasoning Engine 서비스 에이전트도 생성됩니다.

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

   IAM으로 이동

3. 주 구성원 추가 섹션의 새 주 구성원 필드에 [e-mail]를 입력합니다.

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 서비스 에이전트([e-mail])에 서비스 계정 토큰 생성자(roles/iam.serviceAccountTokenCreator) 역할을 부여합니다.

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

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

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

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

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

소스 파일에서 배포

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

객체에서 배포

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

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

참고: 에이전트를 Vertex AI Agent Engine에 배포하는 동일한 프로젝트에 Cloud Storage 버킷을 만드는 것이 좋습니다. 다른 프로젝트의 버킷을 사용하는 경우 Vertex AI 서비스 에이전트([e-mail])에 Cloud Storage 버킷에 대한 읽기 권한을 수동으로 부여해야 합니다.

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

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

Go to Buckets

Click Create.

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 (), click 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 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.
      Note: You cannot enable hierarchical namespace in existing buckets.
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.
   Note: You cannot change the Prevent public access setting if this setting is enforced at an organization policy.
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 (), and select a Data encryption method.

Click Create.

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

익스프레스 모드

Vertex AI를 익스프레스 모드로 사용하는 경우 별도의 조치를 취할 필요가 없습니다.

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",
)

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

• PROJECT_ID는 에이전트를 개발하고 배포하는 데 사용되는 Google Cloud 프로젝트 ID입니다.
• LOCATION: 지원되는 리전 중 하나입니다.

익스프레스 모드

익스프레스 모드로 Vertex AI를 사용하는 경우 다음 코드를 실행합니다.

import vertexai
from vertexai import agent_engines # For the prebuilt ADK template

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY"
)

여기서 API_KEY는 에이전트를 인증하는 데 사용하는 API 키입니다.

다음 단계

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