에이전트 배포
컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Vertex AI Agent Engine에서 에이전트를 배포하려면 다음 안내를 따르세요.

(선택사항) 패키지 요구사항 정의
(선택사항) 소스 파일 정의
(선택사항) Cloud Storage 디렉터리 구성
(선택사항) 리소스 메타데이터 정의
AgentEngine 인스턴스 만들기

시작하기 전에

에이전트를 배포하기 전에 다음 태스크가 완료되었는지 확인합니다.

1단계: 패키지 요구사항 정의

에이전트를 배포하는 데 필요한 패키지 집합을 제공합니다. pip로 설치할 항목 목록이거나 요구사항 파일 형식을 따르는 파일의 경로일 수 있습니다.

에이전트에 종속 항목이 없으면 이를 None으로 설정할 수 있습니다.

requirements = None

에이전트에 프레임워크별 템플릿이 사용되는 경우 에이전트를 개발할 때 가져온 SDK 버전(예: 1.77.0)을 지정해야 합니다.

LangChain

requirements = [
    "google-cloud-aiplatform[agent_engines,langchain]",
    # any other dependencies
]

LangGraph

requirements = [
    "google-cloud-aiplatform[agent_engines,langgraph]",
    # any other dependencies
]

[선택사항] 버전 제약조건

주어진 패키지(예: google-cloud-aiplatform)의 버전을 고정하거나 상한값을 지정해야 하는 경우:

requirements = [
    # See https://pypi.org/project/google-cloud-aiplatform for the latest version.
    "google-cloud-aiplatform[agent_engines,langgraph]==1.77.0",
]

목록에 패키지 및 제약조건을 추가할 수 있습니다.

requirements = [
    "google-cloud-aiplatform[agent,langgraph]==1.75.0",
    "cloudpickle==3.0", # new
]

[선택사항] 개발 브랜치

예를 들어 다음과 같이 GitHub 브랜치 또는 pull 요청에 있는 패키지 버전을 연결할 수 있습니다.

requirements = [
    "google-cloud-aiplatform[agent_engines,langchain] @ git+https://github.com/googleapis/python-aiplatform.git@BRANCH_NAME", # new
    "cloudpickle==3.0",
]

[선택사항] 요구사항 파일 형식

파일(예: path/to/requirements.txt)에 요구사항 목록을 유지할 수 있습니다.

requirements = "path/to/requirements.txt"

여기에서 path/to/requirements.txt는 요구사항 파일 형식을 따르는 텍스트 파일입니다. 예를 들면 다음과 같습니다.

google-cloud-aiplatform[agent_engines,langchain]
cloudpickle==3.0

2단계: 추가 패키지

로컬 파일을 포함하거나 필요한 로컬 Python 소스 파일이 포함된 디렉터리를 포함할 수 있습니다. 패키지 요구사항과 달리 이렇게 하면 사용자가 개발했지만 PyPI 또는 GitHub에서 사용할 수 없는 비공개 유틸리티를 사용할 수 있습니다.

에이전트에 추가 패키지가 필요하지 않으면 이를 None으로 설정할 수 있습니다.

extra_packages = None

[선택사항] 파일 및 디렉터리

단일 파일(예: agents/agent.py)을 포함하려면 목록에 추가하면 됩니다.

extra_packages = ["agents/agent.py"]

전체 디렉터리(예: agents/)의 파일 집합을 포함하려면 해당 디렉터리를 지정하면 됩니다.

extra_packages = ["agents"] # directory that includes agents/agent.py

[선택사항] 휠 바이너리

Python 휠 바이너리(예: path/to/python_package.whl)를 포함하고 이를 패키지 요구사항에 지정할 수 있습니다.

requirements = [
    "google-cloud-aiplatform[agent,langgraph]",
    "cloudpickle==3.0",
    "python_package.whl",  # install from the whl file that was uploaded
]
extra_packages = ["path/to/python_package.whl"]  # bundle the whl file for uploading

3단계: Cloud Storage 디렉터리

기존 하위 버킷(Cloud Storage 버킷의 폴더)에 해당할 경우 스테이징 아티팩트를 덮어씁니다. 필요한 경우 스테이징 아티팩트의 하위 버킷을 지정할 수 있습니다. 이 단계는 선택사항이며 기본 하위 버킷에서 파일을 덮어써도 괜찮다면 이를 None으로 설정할 수 있습니다.

gcs_dir_name = None

개발, 스테이징, 프로덕션과 같은 여러 환경에서 파일을 덮어쓰지 않도록 하려면 해당 하위 버킷을 설정하고 다음과 같이 아티팩트를 스테이징할 하위 버킷을 지정하면 됩니다.

gcs_dir_name = "dev" # or "staging" or "prod"

충돌을 방지해야 할 경우에는 무작위 UUID를 생성하면 됩니다. 예를 들면 다음과 같습니다.

import uuid
gcs_dir_name = str(uuid.uuid4())

4단계: 리소스 메타데이터

Vertex AI에서 생성되는 ReasoningEngine 리소스에 대해 메타데이터를 설정할 수 있습니다. 예를 들면 다음과 같습니다.

display_name = "Currency Exchange Rate Agent (Staging)"

description = """
An agent that has access to tools for looking up the exchange rate.

If you run into any issues, please contact the dev team.
"""

전체 파라미터 집합은 API 참조를 확인하세요.

5단계: `AgentEngine` 인스턴스 만들기

Vertex AI에 에이전트를 배포하려면 agent_engines.create를 사용하고 객체를 파라미터로 전달합니다.

remote_agent = agent_engines.create(
    local_agent,                    # Required.
    requirements=requirements,      # Optional.
    extra_packages=extra_packages,  # Optional.
    gcs_dir_name=gcs_dir_name,      # Optional.
    display_name=display_name,      # Optional.
    description=description,        # Optional.
)

배포를 실행하는 데 몇 분 정도 걸립니다. 에이전트를 배포할 때

다음과 같이 구성된 아티팩트 번들이 로컬로 생성됩니다.
- *.pkl: local_agent에 해당하는 피클 파일입니다.
- requirements.txt: 패키지 요구사항이 포함된 텍스트 파일입니다.
- dependencies.tar.gz: 추가 패키지가 포함된 tar 파일입니다.
아티팩트를 스테이징하기 위해 번들이 Cloud Storage에 업로드됩니다(해당 하위 버킷 아래).
해당 아티팩트의 Cloud Storage URI는 PackageSpec에 지정됩니다.
Vertex AI Agent Engine 서비스가 요청을 수신하고 컨테이너를 빌드하며 백엔드에서 HTTP 서버를 가동합니다.

배포 지연 시간은 필요한 패키지를 설치하는 데 걸리는 총 시간에 따라 달라집니다. 배포된 후 remote_agent은 Vertex AI에서 실행되는 local_agent 인스턴스에 해당하며 이를 쿼리 또는 삭제할 수 있습니다. 이는 에이전트의 로컬 인스턴스와 별개입니다.

리소스 식별자

배포된 각 에이전트에는 고유한 식별자가 포함됩니다. 다음 명령어를 실행하여 배포된 에이전트에 대해 resource_name 식별자를 가져올 수 있습니다.

remote_agent.resource_name

문자열 형식은 다음과 같습니다.

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

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

PROJECT_ID는 배포된 에이전트를 실행하는 데 사용되는 Google Cloud 프로젝트 ID입니다.
LOCATION은 배포된 에이전트가 실행되는 리전입니다.
RESOURCE_ID는 배포된 에이전트의 ID이며 reasoningEngine 리소스로 등록되어 있습니다.

권장사항

패키지 버전 고정(재현 가능한 빌드의 경우) 추적해야 하는 일반 패키지에는 google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai, pydantic이 있습니다.
에이전트의 종속 항목 수를 최소화합니다. 이렇게 하면 종속 항목을 업데이트할 때 브레이킹 체인지 수가 줄어들고 시간이 지남에 따라 최신 기능 적용을 위해 에이전트를 더 쉽게 업데이트할 수 있습니다.

에이전트 스타터 팩을 사용하여 프로덕션에 배포

에이전트 스타터 팩은 Vertex AI Agent Engine을 위해 빌드된 프로덕션에 즉시 사용 가능한 생성형 AI 에이전트 템플릿 모음입니다. 다음을 제공하여 배포 속도를 높입니다.

사전 빌드된 에이전트 템플릿: ReAct, RAG, 멀티 에이전트 등
대화형 플레이그라운드: 에이전트를 테스트하고 상호작용합니다.
자동화된 인프라: 효율적인 리소스 관리를 위해 Terraform을 사용합니다.
CI/CD 파이프라인: Cloud Build를 활용하는 자동화된 배포 워크플로입니다.
모니터링 가능성: Cloud Trace 및 Cloud Logging을 위한 기본 제공되는 지원을 포함합니다.

시작하기: 빠른 시작