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

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

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

Developer Connect

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

このデプロイ方法は 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. 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.agent_engines.create を使用します。この方法では、接続された Git リポジトリからコードを直接デプロイできます。

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

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

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

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

ソースファイル

Agent Platform のソースファイルからデプロイするには、構成辞書で source_packages、entrypoint_module、entrypoint_object、class_methods を指定して client.agent_engines.create を使用します。他のオプション構成も指定できます。この方法では、エージェント オブジェクトまたは 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.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": "",  # 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 オブジェクトは、次の内容を含む AgentEngine クラスに対応します。

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

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

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

コンテナ イメージ

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

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

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

remote_agent = client.agent_engines.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 オブジェクトは、次の内容を含む AgentEngine クラスに対応します。

Agent Platform SDK

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 サーバーを起動します。

デプロイのレイテンシは、必要なパッケージのインストールにかかった合計時間によって異なります。デプロイされると、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 と権限を設定するの手順に沿って操作します。

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

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

次のステップ

ガイド

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

ガイド

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