エージェントをデプロイする

Vertex AI Agent Engine にエージェントをデプロイするには、次のいずれかの方法を選択します。

  • エージェント オブジェクトからデプロイする: Colab などの環境でのインタラクティブな開発に最適で、インメモリ local_agent オブジェクトのデプロイを可能にします。この方法は、複雑なシリアル化できないコンポーネントを含まない構造のエージェントに最適です。
  • ソースファイルからデプロイする: この方法は、CI/CD パイプラインや Terraform などの Infrastructure as Code ツールなどの自動化されたワークフローに適しており、完全に宣言型の自動デプロイを可能にします。エージェントはローカル ソースコードから直接デプロイされるため、Cloud Storage バケットは必要ありません。
  • Dockerfile からデプロイする: この方法は、ソースファイルからデプロイする方法と似ています。エージェントはローカル ソースコードから直接デプロイします。Cloud Storage バケットは必要ありません。この方法は、デプロイされる API サーバーを定義して制御する必要がある場合に適しています。
  • コンテナ イメージからデプロイする: この方法は、Dockerfile からデプロイする方法と似ています。Artifact Registry でホストされているコンテナ イメージをデプロイします。コンテナ イメージのビルドプロセスを制御し、デプロイのレイテンシを短縮する必要がある場合は、この方法を使用します。
  • Developer Connect からデプロイ: Developer Connect を介してリンクされている Git リポジトリで管理されるプロジェクトにおすすめします。この方法では、ソースコードから直接エージェントのデプロイを効率化し、バージョン管理、チーム コラボレーション、CI/CD パイプラインをネイティブにサポートします。このメソッドを使用する前に、Developer Connect Git リポジトリのリンクを設定するの手順に沿って Git リポジトリのリンクを設定します。

使用を開始するには、次の手順を行います。

  1. 前提条件を満たす。
  2. （省略可）デプロイ用にエージェントを構成します。
  3. AgentEngine インスタンスを作成します。
  4. （省略可）エージェントのリソース ID を取得します。
  5. （省略可）サポートされているオペレーションを一覧表示します。
  6. （省略可）デプロイされたエージェントに権限を付与します。

デプロイには、Agent Starter Pack テンプレートを使用することもできます。

前提条件

エージェントをデプロイする前に、次のタスクが完了していることを確認してください。

  1. 環境を設定する。
  2. エージェントを開発する。

（省略可）デプロイ用にエージェントを構成する

エージェントに対して次のオプションの構成を行うことができます。

AgentEngine インスタンスを作成する

このセクションでは、エージェントをデプロイするための AgentEngine インスタンスを作成する方法について説明します。

Vertex AI Agent Engine にエージェントをデプロイするには、次のいずれかの方法を選択します。

  • インタラクティブな開発用のエージェント オブジェクトからデプロイする。
  • Git ベースのワークフローで Developer Connect からデプロイする。
  • ファイルベースのワークフローのソースファイルまたは Dockerfile からのデプロイ。

  • イメージベースのワークフロー用のコンテナ イメージからのデプロイ。

Python オブジェクト

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. 次のアーティファクトのバンドルがローカルに生成されます。

  2. アーティファクトのステージングのために、バンドルが Cloud Storage（対応するフォルダ）にアップロードされます。

  3. それぞれのアーティファクトの Cloud Storage URI は PackageSpec で指定します。

  4. Vertex AI Agent Engine サービスがリクエストを受け取り、コンテナをビルドしてバックエンドで HTTP サーバーを起動します。

Developer Connect

Vertex AI の Developer Connect からデプロイするには、構成ディクショナリで developer_connect_source、entrypoint_module、entrypoint_object とその他の省略可能な構成を指定して client.agent_engines.create を使用します。このメソッドを使用すると、接続された Git リポジトリからコードを直接デプロイできます。

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

Developer Connect のデプロイのパラメータは次のとおりです。

  • developer_connect_source（必須、dict）: ソースコードの取得に関する構成。詳しくは、Developer Connect Git リポジトリのリンクを設定するをご覧ください。
    • git_repository_link（必須、str）: Developer Connect Git リポジトリ リンクのリソース名。
    • revision（必須、str）: 取得するリビジョン（ブランチ、タグ、commit SHA）。
    • dir（必須、str）: リポジトリ内のエージェント コードのルート ディレクトリ。
  • entrypoint_module（必須、str）: developer_connect_source.dir で指定されたディレクトリを基準とした、エージェント エントリポイントを含む Python モジュール名。
  • entrypoint_object（必須、str）: エージェント アプリケーションを表す entrypoint_module 内の呼び出し可能オブジェクトの名前（root_agent など）。
  • requirements_file（省略可、str）: ソースルートを基準とした pip 要件ファイルのパス。デフォルトは requirements.txt です。

デプロイには数分かかります。この間、バックグラウンドで次の手順が実行されます。

  1. Vertex AI Agent Engine サービスは、指定された Git リポジトリ リビジョンからソースコードを取得します。
  2. サービスは、requirements_file から依存関係をインストールします（指定されている場合）。
  3. サービスは、指定された entrypoint_module と entrypoint_object を使用してエージェント アプリケーションを起動します。

ソースファイル

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 内のファイルとディレクトリの合計サイズは 8 MB を超えないようにしてください。
  • 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 を使用してエージェント アプリケーションを起動します。

ソースファイルからエージェントをデプロイする例を次に示します。

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": "...",
  }
)

Dockerfile

Vertex AI の Dockerfile からデプロイする場合、ソースファイルからのデプロイと同様のアプローチが使用されます。デプロイ時に変更されるのは、構成内の entrypoint_module、entrypoint_object、（必要に応じて）requirements_file を image_spec に置き換えることだけです。

Dockerfile を使用してエージェントをデプロイする例を次に示します。

from google.cloud.aiplatform import vertexai

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.agent_engines.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells AgentEngine to use the Dockerfile
        # Other optional configs
    }
)

コンテナ イメージ

コンテナ イメージからデプロイするには、まず 独自のコンテナを使用するのセットアップ手順に沿って、>=1.144 を満たす google-cloud-aiplatform のバージョンをインストールします。次に、次のコードを実行します。

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
    },
)

ここで、CONTAINER_IMAGE_URI は Artifact Registry 内のコンテナ イメージの URI（us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag など）に対応します。

デプロイのレイテンシは、必要なパッケージのインストールにかかった合計時間によって異なります。デプロイされると、remote_agent は Vertex AI で実行されている local_agent のインスタンスに対応し、クエリまたは削除が可能になります。

remote_agent オブジェクトは、次の内容を含む AgentEngine クラスに対応します。

（省略可）エージェントのリソース ID を取得する

デプロイされた各エージェントには固有識別子があります。次のコマンドを実行して、デプロイされたエージェントのリソース名を取得できます。

remote_agent.api_resource.name

レスポンスは次の文字列のようになります。

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

ここで

  • PROJECT_ID は、デプロイされたエージェントが実行される Google Cloud プロジェクト ID です。

  • LOCATION は、デプロイされたエージェントが実行されるリージョンです。

  • RESOURCE_ID は、reasoningEngine リソースとしてのデプロイ済みエージェントの ID です。

（省略可）サポートされているオペレーションを一覧表示する

デプロイされた各エージェントには、サポートされているオペレーションのリストがあります。AgentEngine.operation_schemas を使用して、デプロイされたエージェントでサポートされているオペレーションのリストを取得できます。

remote_agent.operation_schemas()

各オペレーションのスキーマは、呼び出せるエージェントのメソッドに関する情報をドキュメント化したディクショナリです。サポートされているオペレーションのセットは、エージェントの開発に使用したフレームワークによって異なります。

（省略可）デプロイされたエージェントに権限を付与する

デプロイされたエージェントに追加の権限を付与する必要がある場合は、エージェントの ID と権限を設定するの手順に沿って操作します。

次のステップ