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

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

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

Developer Connect

Developer Connect を介してリンクされた Git リポジトリで管理されているプロジェクトにおすすめです。この方法では、ソースコードから直接エージェントのデプロイを効率化し、バージョン管理、チーム コラボレーション、CI / CD パイプラインをネイティブにサポートします。この方法を使用する前に、Developer Connect Git リポジトリのリンクを設定するの手順に沿って、Git リポジトリのリンクを設定します。

このデプロイ方法は Python でのみ使用できます。

公開 Git リポジトリ

HTTPS 経由でアクセスできる公開 Git リポジトリ内のプロジェクトに適しています。この方法では、Developer Connect 接続や Git リポジトリ リンクを設定せずに、リポジトリ URL から直接デプロイできます。この方法は、公開リポジトリのみをサポートしています。限定公開リポジトリからデプロイするには、Developer Connect を使用します。

このデプロイ方法は Python でのみ使用できます。

ソースファイル

CI / CD パイプラインなどの自動化されたワークフローや、Terraform などの Infrastructure as Code ツールに適しており、完全に宣言型の自動デプロイを実現できます。ローカル ソースコードからエージェントを直接デプロイするため、Cloud Storage バケットは必要ありません。

このデプロイ方法は Python でのみ使用できます。

Dockerfile

ソースファイルからのデプロイと似ています。Cloud Storage バケットを必要とせずに、ローカル ソースコードからエージェントを直接デプロイします。この方法は、デプロイされる API サーバーを定義して制御する必要がある場合に適しています。デプロイされたコンテナは、ランタイム コントラクトに準拠している必要があります。

このデプロイ方法は、どの言語でも使用できます。このページの例では Python を使用しています。

コンテナ イメージ

Dockerfile からのデプロイと同様です。Artifact Registry でホストされているコンテナ イメージをデプロイします。この方法は、コンテナ イメージのビルドプロセスを制御し、デプロイ レイテンシを短縮する必要がある場合に使用します。コンテナ イメージはランタイム契約に準拠している必要があります。

このデプロイ方法は、どの言語でも使用できます。このページの例では Python を使用しています。

Agent Platform SDK

Colab などの環境でのインタラクティブな開発に最適で、インメモリ local_agent オブジェクトのデプロイが可能です。この方法は、複雑なシリアル化不可能なコンポーネントを含まない構造のエージェントに最適です。

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

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

前提条件

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

  1. 環境を設定する
  2. エージェントを作成する

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

エージェントのオプション構成を行うことができます。このセクションの例では Python を使用します。

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

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

Developer Connect

Agent Platform の Developer Connect からデプロイするには、構成辞書で developer_connect_source、entrypoint_module、entrypoint_object を指定して client.runtimes.create を使用します。また、他のオプション構成も指定します。この方法では、接続された Git リポジトリからコードを直接デプロイできます。

このデプロイ方法は Python でのみ使用できます。

remote_agent = client.runtimes.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）: エージェントのエントリポイントを含む Python モジュール名。developer_connect_source.dir で指定されたディレクトリを基準とした相対パスです。
  • 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 を使用してエージェント アプリケーションを起動します。

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

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

公開 Git リポジトリ

Agent Platform の公開 Git リポジトリからデプロイするには、client.runtimes.create を使用します。このとき、構成辞書に git_source、entrypoint_module、entrypoint_object、class_methods を指定し、その他のオプションの構成も指定します。非公開リポジトリからデプロイするには、Developer Connect を使用します。

このデプロイ方法は Python でのみ使用できます。

remote_agent = client.runtimes.create(
    config={
        "git_source": {                                 # Required.
            "url": "https://github.com/OWNER/REPO.git", # Required.
            "revision": "main",                         # Required.
            "dir": "path/to/dir",                       # Optional.
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

公開 Git リポジトリのデプロイのパラメータは次のとおりです。

  • git_source（dict）: 公開 Git リポジトリからソースコードを取得するための構成。
    • url（str）: 公開 Git リポジトリの HTTPS URL（例: https://github.com/OWNER/REPO.git）。URL に user:password@ などの認証情報を含めることはできません。
    • revision（str）: 取得するブランチ、タグ、または完全な commit SHA。省略された commit SHA はサポートされていません。
    • dir（str）: 省略可。ビルドが実行されるディレクトリ（リポジトリのルートからの相対パス）。このディレクトリの内容のみがデプロイされます。設定しない場合、リポジトリのルートが使用されます。パスの先頭を / にすることはできません。また、パスに .. セグメントを含めることはできません。
  • entrypoint_module（str）: エージェントのエントリポイントを含む Python モジュール名。git_source.dir で指定されたディレクトリを基準とした相対パスです。
  • entrypoint_object（str）: エージェント アプリケーションを表す entrypoint_module 内の呼び出し可能オブジェクトの名前（例: root_agent）。
  • class_methods（list[dict]）: エージェントの公開メソッドを定義する辞書のリスト。各辞書には、name、api_mode、オプションの parameters フィールドが含まれています。カスタム エージェントのメソッドの詳細については、サポートされているオペレーションを一覧表示するをご覧ください。
  • requirements_file（str）: 省略可。git_source.dir（dir が設定されていない場合はリポジトリのルート）を基準とする pip 要件ファイルのパス。デフォルトは requirements.txt です。

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

  1. Agent Runtime サービスは、指定されたリビジョンでリポジトリのクローンを作成します。
  2. サービスは、requirements_file から依存関係をインストールします（ファイルが存在する場合）。
  3. サービスは、指定された entrypoint_module と entrypoint_object を使用してエージェント アプリケーションを起動します。

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

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

ソースファイル

Agent Platform のソースファイルからデプロイするには、client.runtimes.create を使用します。このとき、構成辞書に source_packages、entrypoint_module、entrypoint_object、class_methods を指定し、その他のオプションの構成も指定します。この方法では、エージェント オブジェクトや Cloud Storage バケットを渡す必要はありません。

このデプロイ方法は Python でのみ使用できます。

# 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.runtimes.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": "",  # Options: "", "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 を使用してエージェント アプリケーションを起動します。

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

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

Dockerfile

Agent Platform で Dockerfile からデプロイする方法は、ソースファイルからデプロイする方法と似ていますが、構成で entrypoint_module、entrypoint_object、requirements_file ではなく image_spec を使用する点が異なります。Dockerfile からビルドされたコンテナは、ランタイム コントラクトに準拠している必要があります。

このデプロイ方法は、どの言語でも使用できます。このセクションの例では Python を使用します。

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

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

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

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

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

コンテナ イメージ

コンテナ イメージからデプロイするには、まず独自のコンテナを使用するの設定手順に沿って、>=1.144 を満たす google-cloud-aiplatform のバージョンをインストールします。コンテナ イメージはランタイム契約に準拠している必要があります。

このデプロイ方法は、どの言語でも使用できます。このセクションの例では Python を使用します。

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

remote_agent = client.runtimes.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
        "display_name": "Container image agent",
    },
)

ここで、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 オブジェクトは、次の内容を含む AgentRuntime クラスに対応します。

Agent Platform SDK

Agent Platform にエージェントをデプロイするには、client.runtimes.create を使用して、local_agent オブジェクトとオプションの構成を渡します。

remote_agent = client.runtimes.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 サーバーを起動します。

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

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

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

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

remote_agent.api_resource.name

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

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

ここで

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

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

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

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

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

remote_agent.operation_schemas()

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

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

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

省略可: エンタープライズ インフラストラクチャを使用してエージェントをデプロイする

セキュリティ レイヤとガバナンス レイヤを含む完全な環境でエージェントをデプロイするには、次の Application Design Center テンプレートをコピーしてカスタマイズします。

次のステップ

ガイド

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

ガイド

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