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

Vertex AI Agent Engine にエージェントをデプロイするには、次の 2 つの主な方法から選択します。

  • エージェント オブジェクトからデプロイする: Colab などの環境でのインタラクティブな開発に最適で、インメモリ local_agent オブジェクトのデプロイを可能にします。この方法は、複雑な非シリアル化可能なコンポーネントを含まない構造のエージェントに最適です。
  • ソースファイルからデプロイする: この方法は、CI/CD パイプラインや Terraform などの Infrastructure as Code ツールなどの自動化されたワークフローに適しており、完全に宣言型の自動デプロイを実現できます。エージェントはローカル ソースコードから直接デプロイされ、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. 次のアーティファクトのバンドルがローカルに生成されます。

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

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

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

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

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

ソースファイルから

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 が指定されている場合は、requirements_file から依存関係をインストールし、指定された entrypoint_module と entrypoint_object を使用してエージェント アプリケーションを起動します。

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

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

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

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 は、reasoningEngine リソースとしてのデプロイ済みエージェントの ID です。

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

デプロイされた各エージェントには、サポートされているオペレーションのリストがあります。次のコマンドを実行して、デプロイされたエージェントでサポートされているオペレーションのリストを取得できます。

remote_agent.operation_schemas()

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

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

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

次のステップ