에이전트 배포

패키지 요구사항 정의

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

1. 재현 가능한 빌드의 경우 패키지 버전을 고정합니다. 추적해야 하는 일반 패키지에는 google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai, pydantic이 있습니다.
2. 에이전트의 종속 항목 수를 최소화합니다. 이렇게 하면 종속 항목과 에이전트를 업데이트할 때 브레이킹 체인지 수가 줄어듭니다.

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

requirements = None

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

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

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

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

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

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

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

패키지 requirements를 사용하여 다음 작업을 할 수도 있습니다.

• 주어진 패키지 (예: google-cloud-aiplatform)의 버전을 고정하거나 상한값을 지정합니다.

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

• 패키지 및 제약 조건을 추가합니다.

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk]==1.112.0",
        "cloudpickle==3.0", # new
    ]
    

• GitHub 브랜치 또는 pull 요청의 패키지 버전을 가리킵니다.

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

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

    requirements = "path/to/requirements.txt"
    

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

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

추가 패키지 정의

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

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

extra_packages = None

extra_packages로 다음 작업을 수행할 수도 있습니다.

• 단일 파일(예: 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_engines,adk]",
        "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
    

환경 변수 정의

에이전트가 사용하는 환경 변수가 있는 경우 env_vars= 인수에 이를 지정할 수 있습니다. 에이전트가 환경 변수를 사용하지 않는 경우 이를 None으로 설정할 수 있습니다.

env_vars = None

에이전트 ID를 사용하도록 구성된 에이전트와 함께 보안 비밀을 환경 변수로 사용하는 경우 다음 형식의 에이전트 플랫폼 서비스 에이전트에 secretmanager.versions.access 권한 (roles/secretmanager.secretAccessor 역할에 포함됨)을 부여합니다.

service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com

구성된 에이전트 아이덴티티는 런타임에 사용되지만, Agent Platform 서비스 에이전트는 배포 중에 보안 비밀을 가져오는 데 사용됩니다. 추가된 권한을 통해 서비스 에이전트는 배포 프로세스 중에 Secret Manager에서 보안 비밀 값을 가져올 수 있습니다.

환경 변수를 지정하는 방법에는 몇 가지 옵션이 있습니다.

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Agent Platform
# through `os.environ`, e.g.
#
#   import os
#   os.environ["VARIABLE_1"] # will have the value "VALUE_1"
#
# and
#
#   os.environ["VARIABLE_2"] # will have the value "VALUE_2"
#

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": SECRET_ID, "version": SECRET_VERSION_ID},
}

secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET")
if secret:
  # Secrets are stored as strings, so use json.loads to parse JSON
  # payloads.
  return json.loads(secret)

env_vars = ["VARIABLE_1", "VARIABLE_2"]
# This corresponds to the following code snippet:
#
#   import os
#
#   env_vars = {
#     "VARIABLE_1": os.environ["VARIABLE_1"],
#     "VARIABLE_2": os.environ["VARIABLE_2"],
#   }

에이전트의 ID 및 권한 설정의 안내에 따라 에이전트에게 Secret Manager 보안 비밀 접근자(roles/secretmanager.secretAccessor) 권한을 부여해야 합니다.

맞춤설정된 리소스 제어 정의

최소 및 최대 애플리케이션 인스턴스 수, 각 컨테이너의 리소스 한도, 각 컨테이너의 동시 실행과 같은 에이전트의 런타임 리소스 제어를 지정할 수 있습니다.

• min_instances: 항상 실행 상태로 유지할 최소 애플리케이션 인스턴스 수입니다(범위는 [0, 10]). 기본값은 1입니다.

• max_instances: 트래픽 증가를 처리하기 위해 실행할 수 있는 최대 애플리케이션 인스턴스 수입니다(범위는 [1, 1000]). 기본값은 100입니다. VPC-SC 또는 PSC-I가 사용 설정된 경우 허용되는 범위는 Agent Platform 리소스당 [1, 100]입니다.

• resource_limits: 각 컨테이너의 리소스 한도입니다. cpu 및 memory 키만 지원됩니다. 기본값은 {"cpu": "4", "memory": "4Gi"}입니다.

  • cpu에 지원되는 값은 1, 2, 4, 6, 8뿐입니다. 자세한 내용은 CPU 할당 구성을 참고하세요.

  • memory에 지원되는 값은 1Gi, 2Gi, …, 32Gi뿐입니다.

  • 다양한 메모리 값에 필요한 CPU는 메모리 한도 구성을 참조하세요.

• container_concurrency: 각 컨테이너 및 에이전트 서버의 동시 실행입니다. 권장값은 2 * cpu + 1입니다. 기본값은 9입니다.

remote_agent = client.runtimes.create(
    agent=local_agent,
    config={
        "min_instances": 1,
        "max_instances": 10,
        "resource_limits": {"cpu": "4", "memory": "8Gi"},
        "container_concurrency": 9,
        # ... other configs
    }
)

런타임 리소스를 최적화하는 방법에 관한 권장사항은 Agent Runtime 최적화 및 확장을 참고하세요.

빌드 옵션 정의

에이전트의 컨테이너 이미지를 빌드할 때 실행할 설치 스크립트와 같은 에이전트의 빌드 옵션을 지정할 수 있습니다. 이는 시스템 종속 항목 (예: gcloud cli, npx) 또는 기타 맞춤 설정을 설치하는 데 유용합니다. 스크립트는 루트 권한으로 실행됩니다.

설치 스크립트를 사용하려면 installation_scripts이라는 디렉터리를 만들고 디렉터리 내에 셸 스크립트를 배치합니다.

.
├── ...
└── installation_scripts/
    └── install.sh

다음으로 extra_packages에 installation_scripts 디렉터리를 지정하고 build_options에 스크립트 경로를 지정합니다.

extra_packages = [..., "installation_scripts/install.sh"]
build_options = {"installation_scripts": ["installation_scripts/install.sh"]}

다음과 같은 일반적인 설치 스크립트 중 하나를 사용할 수 있습니다.

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "--- Installing System-Wide Node.js v20.x ---"

# 1. Install prerequisites
apt-get update
apt-get install -y ca-certificates curl gnupg

# 2. Add the NodeSource repository GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 3. Add the NodeSource repository for Node.js v20
NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

# 4. Update package lists again and install Node.js
apt-get update
apt-get install nodejs -y

echo "--- System-wide Node.js installation complete ---"
echo "Verifying versions:"

# These commands will now work for ANY user because node and npx
# are installed in /usr/bin/ which is in everyone's default PATH.
node -v
npm -v
npx -v

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "Starting setup..."

# Install uv
apt-get update
apt-get install -y curl
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh

# These commands will now work for ANY user because uv and uvx
# are installed in /usr/local/bin/ which is in everyone's default PATH.
uv --version
uvx --version

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

apt-get install -y curl gpg
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
apt-get update -y && apt-get install google-cloud-cli -y

gcloud --version

에이전트 프레임워크 정의

에이전트가 사용하는 에이전트 프레임워크를 지정할 수 있습니다.

agent_framework = "google-adk"

지원되는 값은 다음과 같습니다.

• google-adk
• langchain
• langgraph
• ag2
• llama-index
• custom

agent_framework를 지정하지 않으면 에이전트 객체에서 배포하는 경우 값이 자동 감지됩니다. 소스 파일에서 배포하는 경우 agent_framework의 기본값은 `custom`입니다.

Cloud Storage 폴더 정의

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

gcs_dir_name = None

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

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

충돌을 방지해야 할 경우에는 무작위 uuid를 생성하면 됩니다.

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

표시 이름 정의

ReasoningEngine 리소스의 표시 이름을 설정할 수 있습니다.

display_name = "Currency Exchange Rate Agent (Staging)"

설명 정의

ReasoningEngine 리소스의 설명을 설정할 수 있습니다.

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

라벨 정의

ReasoningEngine 리소스의 라벨을 키-값 문자열 쌍의 사전으로 설정할 수 있습니다. 다음은 그 예시입니다.

labels = {"author": "username", "version": "latest"}

기본 에이전트 ID 구성

에이전트를 만들 때 Agent Platform에 배포하는 에이전트에 고유한 ID를 프로비저닝할 수 있습니다. ID는 Agent Platform의 에이전트 리소스 ID에 연결되며 에이전트를 개발하는 데 사용한 에이전트 프레임워크와는 독립적입니다.

identity_type=AGENT_IDENTITY

자세한 내용은 에이전트 ID로 에이전트 만들기를 참고하세요.

커스텀 서비스 계정 구성

에이전트 ID 또는 기본 ID 대신 배포된 에이전트의 ID로 커스텀 서비스 계정을 구성할 수 있습니다.

이렇게 하려면 Agent Platform 인스턴스를 만들거나 업데이트할 때 커스텀 서비스 계정의 이메일을 service_account로 지정합니다. 예를 들면 다음과 같습니다.

# Create a new instance
client.runtimes.create(
    agent=local_agent,
    config={
        "service_account": "my-custom-service-account@my-project.iam.gserviceaccount.com",
        # ...
    },
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
client.runtimes.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "my-new-custom-service-account@my-project.iam.gserviceaccount.com",
        # ...
    },
)

Private Service Connect 인터페이스 구성

Private Service Connect 인터페이스 및 비공개 DNS 영역이 설정된 경우 에이전트를 배포하는 동안 네트워크 연결을 지정하고 비공개 DNS 피어링을 만들 수 있습니다.

remote_agent = client.runtimes.create(
    agent=local_agent,
    config={
        "psc_interface_config": {
            "network_attachment": "NETWORK_ATTACHMENT",
            "dns_peering_configs": [
                {
                    "domain": "DOMAIN_SUFFIX",
                    "target_project": "TARGET_PROJECT",
                    "target_network": "TARGET_NETWORK",
                },
            ],
        },