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

エージェントを Agent Runtime にデプロイすると、リクエストを処理するためにリモートで利用できるようになります。このドキュメントでは、実行オブジェクト、ローカル ソースファイル、Dockerfile、Artifact Registry でホストされているコンテナ イメージ、または接続された Git リポジトリから直接、開発ワークフローに基づいてエージェントをデプロイする方法について説明します。

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

  • エージェント オブジェクトからデプロイする: 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. Agent Platform インスタンスを作成する。
  4. 省略可: エージェントのリソース ID を取得します。
  5. 省略可: サポートされているオペレーションを一覧表示します。
  6. 省略可: デプロイされたエージェントに権限を付与します。

デプロイには Agents CLI を使用することもできます。

前提条件

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

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

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

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

Agent Platform インスタンスを作成する

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

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

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

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

Python オブジェクト

Agent Platform にエージェントをデプロイするには、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. Agent Runtime サービスがリクエストを受け取り、コンテナをビルドしてバックエンドで HTTP サーバーを起動します。

Developer Connect

Agent Platform の Developer Connect からデプロイするには、client.agent_engines.create を使用して、構成ディクショナリに developer_connect_source、entrypoint_module、entrypoint_object と、その他の省略可能な構成を指定します。このメソッドを使用すると、接続された 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. Agent Runtime サービスは、指定された Git リポジトリ リビジョンからソースコードを取得します。
  2. サービスは requirements_file から依存関係をインストールします（指定されている場合）。
  3. サービスは、指定された entrypoint_module と entrypoint_object を使用してエージェント アプリケーションを起動します。

ソースファイル

Agent Platform のソースファイルからデプロイするには、構成辞書で 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. Agent Platform SDK は、source_packages で指定されたパスの tar.gz アーカイブを作成します。
  2. このアーカイブはエンコードされ、Agent Platform API に直接送信されます。
  3. Agent Runtime サービスはアーカイブを受け取り、抽出して、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

エージェント プラットフォームで 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 Agent Runtime to use the Dockerfile
        # Other optional configs
    }
)

コンテナ イメージ

コンテナ イメージからデプロイするには、まず Bring your own container の設定手順に沿って、>=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 は Agent Platform で実行されている 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 と権限を設定するの手順に沿って操作します。

次のステップ

ガイド

Agent Platform マネージド ランタイムにデプロイされたエージェントを管理する方法について説明します。

ガイド

Agent Platform Runtime でエージェントを使用します。