에이전트 배포

Vertex AI Agent Engine에 에이전트를 배포하려면 다음 두 가지 기본 방법 중에서 선택하세요.

  • 에이전트 객체에서 배포: Colab과 같은 환경에서 대화형 개발에 적합하며 메모리 내 local_agent 객체를 배포할 수 있습니다. 이 방법은 복잡하고 직렬화할 수 없는 구성요소가 포함되지 않은 구조의 에이전트에 가장 적합합니다.
  • 소스 파일에서 배포: 이 방법은 CI/CD 파이프라인, Terraform과 같은 코드형 인프라 도구와 같은 자동화된 워크플로에 적합하며 완전한 선언적 자동 배포를 지원합니다. 로컬 소스 코드에서 직접 에이전트를 배포하며 Cloud Storage 버킷이 필요하지 않습니다.

시작하려면 다음 단계를 따르세요.

  1. 기본 요건 완료
  2. (선택사항) 배포를 위해 에이전트 구성
  3. AgentEngine 인스턴스 만들기
  4. (선택사항) 에이전트 리소스 ID 가져오기
  5. (선택사항) 지원되는 작업을 나열합니다.
  6. (선택사항) 배포된 에이전트에 권한 부여

배포를 위해 Agent Starter Pack 템플릿을 사용할 수도 있습니다.

기본 요건

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

  1. 환경을 설정합니다.
  2. 에이전트 개발

(선택사항) 배포를 위해 에이전트 구성

에이전트에 대해 다음과 같은 선택적 구성을 할 수 있습니다.

AgentEngine 인스턴스 만들기

이 섹션에서는 에이전트를 배포하기 위한 AgentEngine 인스턴스를 만드는 방법을 설명합니다.

Vertex AI Agent Engine에 에이전트를 배포하려면 다음 방법 중에서 선택하세요.

  • 양방향 개발을 위해 에이전트 객체에서 배포

  • 자동화된 파일 기반 워크플로를 위해 소스 파일에서 배포합니다.

에이전트 객체에서

Vertex AI에 에이전트를 배포하려면 client.agent_engines.create를 사용하여 local_agent 객체를 선택적 구성과 함께 전달합니다.

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

배포에는 몇 분이 걸리며, 이 시간 동안 백그라운드에서 다음 단계가 진행됩니다.

  1. 다음 아티팩트 번들이 로컬로 생성됩니다.

    • *.pkl: local_agent에 해당하는 피클 파일입니다.
    • requirements.txt: 패키지 요구사항이 포함된 텍스트 파일입니다.
    • dependencies.tar.gz: 추가 패키지가 포함된 tar 파일입니다.

  2. 아티팩트를 스테이징하기 위해 번들이 Cloud Storage(해당 폴더 아래)에 업로드됩니다.

  3. 해당 아티팩트의 Cloud Storage URI는 PackageSpec에 지정됩니다.

  4. Vertex AI Agent Engine 서비스가 요청을 수신하고 컨테이너를 빌드하며 백엔드에서 HTTP 서버를 시작합니다.

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

remote_agent 객체는 다음 속성을 포함하는 AgentEngine 클래스에 해당합니다.

  • 배포된 에이전트에 관한 정보가 포함된 remote_agent.api_resource agent.operation_schemas()를 호출하여 에이전트가 지원하는 작업 목록을 반환할 수도 있습니다. 자세한 내용은 지원되는 작업 나열을 참고하세요.
  • 동기 서비스 상호작용을 허용하는 remote_agent.api_client
  • 비동기 서비스 상호작용을 허용하는 remote_agent.async_api_client

소스 파일에서

Vertex AI에서 소스 파일로 배포하려면 구성 딕셔너리에 source_packages, entrypoint_module, entrypoint_object, class_methods를 다른 선택적 구성과 함께 제공하여 client.agent_engines.create를 사용하세요. 이 방법을 사용하면 에이전트 객체나 Cloud Storage 버킷을 전달할 필요가 없습니다.

remote_agent = client.agent_engines.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

인라인 소스 배포의 매개변수는 다음과 같습니다.

  • source_packages (필수, list[str]): 배포에 포함할 로컬 파일 또는 디렉터리 경로 목록입니다. source_packages의 파일 및 디렉터리의 총 크기는 8MB를 초과해서는 안 됩니다.
  • entrypoint_module (필수, str): 에이전트 진입점을 포함하는 정규화된 Python 모듈 이름입니다 (예: agent_dir.agent).
  • entrypoint_object (필수, str): 에이전트 애플리케이션을 나타내는 entrypoint_module 내 호출 가능 객체의 이름입니다 (예: root_agent).

  • class_methods (필수, list[dict]): 에이전트의 노출된 메서드를 정의하는 사전 목록입니다. 각 사전에는 name (필수), api_mode (필수), parameters 필드가 포함됩니다. 맞춤 에이전트의 메서드에 관한 자세한 내용은 지원되는 작업 목록을 참고하세요.

    예를 들면 다음과 같습니다.

      "class_methods": [
      {
          "name": "method_name",
          "api_mode": "", # Possible options are: "", "async", "async_stream", "stream", "bidi_stream"
          "parameters": {
              "type": "object",
              "properties": {
                  "param1": {"type": "string", "description": "Description of param1"},
                  "param2": {"type": "integer"}
              },
              "required": ["param1"]
          }
      }
  ]
  ```

  • requirements_file (선택사항, str): source_packages에 지정된 경로 내의 pip 요구사항 파일 경로입니다. 패키지된 소스의 루트 디렉터리에 있는 requirements.txt가 기본값입니다.

배포에는 몇 분이 걸리며, 이 시간 동안 백그라운드에서 다음 단계가 진행됩니다.

  1. Vertex AI SDK는 source_packages에 지정된 경로의 tar.gz 아카이브를 만듭니다.
  2. 이 보관 파일은 인코딩되어 Vertex AI API로 직접 전송됩니다.
  3. Vertex AI Agent Engine 서비스가 보관 파일을 수신하고, 압축을 풀고, requirements_file (제공된 경우)에서 종속 항목을 설치하고, 지정된 entrypoint_module 및 entrypoint_object을 사용하여 에이전트 애플리케이션을 시작합니다.

배포 지연 시간은 필요한 패키지를 설치하는 데 걸리는 총 시간에 따라 달라집니다. 배포된 후 remote_agent은 Vertex AI에서 실행되는 에이전트 애플리케이션의 인스턴스에 해당하며 이를 쿼리하거나 삭제할 수 있습니다.

remote_agent 객체는 다음 속성을 포함하는 AgentEngine 클래스에 해당합니다.

  • 배포된 에이전트에 관한 정보가 포함된 remote_agent.api_resource agent.operation_schemas()를 호출하여 에이전트가 지원하는 작업 목록을 반환할 수도 있습니다. 자세한 내용은 지원되는 작업 나열을 참고하세요.
  • 동기 서비스 상호작용을 허용하는 remote_agent.api_client
  • 비동기 서비스 상호작용을 허용하는 remote_agent.async_api_client

다음은 소스 파일에서 에이전트를 배포하는 예입니다.

from google.cloud.aiplatform import vertexai

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.agent_engines.create(
  config={
      "display_name": "My Agent",
      "description": "An agent deployed from a local source.",
      "source_packages": ["agent_directory"],
      "entrypoint_module": "agent_directory.agent",
      "entrypoint_object": "root_agent",
      "requirements_file": "requirements.txt",
      "class_methods": [
          {"name": "ask", "api_mode": "", "parameters": {
              "type": "object",
              "properties": {
                  "question": {"type": "string"}
              },
              "required": ["question"]
          }},
      ],
      # Other optional configs:
      # "env_vars": {...},
      # "service_account": "...",
  }
)

(선택사항) 에이전트 리소스 ID 가져오기

배포된 각 에이전트에는 고유한 식별자가 포함됩니다. 다음 명령어를 실행하여 배포된 에이전트의 리소스 이름을 가져올 수 있습니다.

remote_agent.api_resource.name

응답으로 다음과 같은 문자열이 표시됩니다.

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

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

  • PROJECT_ID는 배포된 에이전트가 실행되는 Google Cloud 프로젝트 ID입니다.

  • LOCATION은 배포된 에이전트가 실행되는 리전입니다.

  • RESOURCE_ID는 배포된 에이전트의 ID이며 reasoningEngine 리소스로 등록되어 있습니다.

(선택사항) 지원되는 작업 나열

배포된 각 에이전트에는 지원되는 작업 목록이 있습니다. 다음 명령어를 실행하여 배포된 에이전트에서 지원하는 작업 목록을 가져올 수 있습니다.

remote_agent.operation_schemas()

각 작업의 스키마는 호출할 수 있는 에이전트의 메서드 정보를 문서화하는 사전입니다. 지원되는 작업 집합은 에이전트를 개발하는 데 사용한 프레임워크에 따라 다릅니다.

(선택사항) 배포된 에이전트에 권한 부여

배포된 에이전트에 추가 권한을 부여해야 하는 경우 에이전트의 ID 및 권한 설정의 안내를 따르세요.

다음 단계