部署代理程式

將代理部署至 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 存放區連結。這個方法僅支援公開存放區。如要從私人存放區部署,請使用 Developer Connect。

這個部署方法僅適用於 Python。

來源檔案

非常適合用於 CI/CD 管道等自動化工作流程,以及 Terraform 等基礎架構即程式碼工具,可實現完全宣告式和自動化的部署作業。這項指令會直接從本機原始碼部署代理,不需要 Cloud Storage bucket。

這個部署方法僅適用於 Python。

Dockerfile

與從來源檔案部署類似。您可以直接從本機原始碼部署代理,不需使用 Cloud Storage bucket。如果您需要定義及控管部署的 API 伺服器,這個方法就很合適。部署的容器必須遵守執行階段合約。

這個部署方法適用於任何語言。

容器映像檔

與從 Dockerfile 部署類似。您部署了託管於 Artifact Registry 的容器映像檔。如果您需要控管容器映像檔的建構程序,並縮短部署延遲時間,請使用這個方法。容器映像檔必須符合執行階段合約。

這個部署方法適用於任何語言。

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 部署,請使用 client.runtimes.create,並在設定字典中提供 developer_connect_source、entrypoint_module 和 entrypoint_object,以及其他選用設定。這個方法可讓您直接從連結的 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):要擷取的修訂版本 (分支版本、標記或修訂版本 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 網址 (例如 https://github.com/OWNER/REPO.git)。網址不得包含憑證,例如 user:password@。
    • revision (str):要擷取的分支版本、標記或完整修訂版本 SHA。不支援縮寫的修訂版本 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):選用。pip 需求檔案的路徑,相對於 git_source.dir (如果未設定 dir,則為存放區根目錄)。預設為 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 bucket。

這個部署方法僅適用於 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):選用。pip 需求檔案的路徑,位於 source_packages 指定的路徑中。預設為封裝來源根目錄中的 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

在代理平台中,從 Dockerfile 部署的方式與從來源檔案部署類似,差別在於您必須在來源檔案中加入 Dockerfile,並在設定中指定 image_spec,而非 entrypoint_module、entrypoint_object 和 requirements_file。從 Dockerfile 建構的容器必須透過通訊埠 8080 監聽 0.0.0.0 上的 HTTP 要求,並遵守執行階段合約。

這個部署方法適用於任何語言。

首先,在專案目錄的根目錄中建立 Dockerfile,用於安裝依附元件,並在 0.0.0.0:8080 上啟動 HTTP 伺服器:

Python

FROM python:3.13-slim
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8080

# Start an ADK API server or custom FastAPI server on 0.0.0.0:8080:
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

Go

FROM golang:1.24 AS builder
WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /app/server .

FROM gcr.io/distroless/static-debian12
WORKDIR /app
COPY --from=builder /app/server /app/server

EXPOSE 8080

# For an ADK Go agent using the built-in launcher:
# CMD ["/app/server", "web", "-host", "0.0.0.0", "-port", "8080", "agentengine"]
# For a custom Go HTTP server listening on 0.0.0.0:8080:
CMD ["/app/server"]

TypeScript

FROM node:22-slim
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

EXPOSE 8080

# For an ADK TypeScript agent (with @google/adk-devtools in package.json):
# CMD ["npx", "adk", "api_server", "/app/agents/my_agent", "--host=0.0.0.0", "--port=8080"]
# For a custom Node.js HTTP server listening on 0.0.0.0:8080:
CMD ["node", "dist/index.js"]

Java

FROM maven:3.9-eclipse-temurin-17
WORKDIR /app

COPY pom.xml .
COPY src ./src
RUN mvn package -DskipTests

EXPOSE 8080

# For an ADK Java agent using AdkWebServer (set --server.address=0.0.0.0):
# CMD ["sh", "-c", "mvn exec:java -Dexec.mainClass=com.google.adk.web.AdkWebServer -Dexec.args='--server.address=0.0.0.0 --server.port=${PORT:-8080} --adk.agents.source-dir=.'"]
# For a packaged Java HTTP server JAR listening on 0.0.0.0:8080:
CMD ["java", "-jar", "target/app.jar"]

如果容器實作執行階段合約轉送端點 (/api/reasoning_engine 和 /api/stream_reasoning_engine,ADK Go agentengine 啟動器也會公開),請在 class_methods (或 REST 中的 spec.classMethods) 宣告支援的作業,以便透過標準 query 和 streamQuery 要求叫用代理。如果容器執行 ADK API 伺服器 (例如 TypeScript 的 npx adk api_server 或 Java 的 AdkWebServer),請透過基礎 API Proxy (/api/run 和 /api/run_sse) 叫用其 /run 和 /run_sse 端點。

接著,使用 Agent Platform SDK、REST API 或 Terraform,從本機來源檔案和 Dockerfile 部署代理:

Agent Platform SDK

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile
#
# For other languages, pass your project's source files and Dockerfile in source_packages:
#   Go:         ["main.go", "go.mod", "go.sum", "Dockerfile"]
#   TypeScript: ["src", "package.json", "package-lock.json", "tsconfig.json", "Dockerfile"]
#   Java:       ["src", "pom.xml", "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
        # Optional: declare class_methods if your container implements /api/reasoning_engine or /api/stream_reasoning_engine
        # "class_methods": class_methods,
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

部署作業延遲時間取決於建構容器映像檔及安裝必要套件所需的總時間。部署完成後,remote_agent 會對應至在 Agent Platform 上執行的代理,您可以查詢或刪除該代理。

remote_agent 物件對應至 AgentRuntime 類別,其中包含下列項目:

REST

在 .tar.gz 封存檔 (大小上限為 8 MB) 的根層級封裝 Dockerfile 和應用程式來源檔案,並以 Base64 編碼封存檔,然後傳送 POST 要求至 reasoningEngines.create 方法:

# Package your Dockerfile and source files at the root of a tar.gz archive
# (replace main.py and requirements.txt with your project's source files):
tar -czf /tmp/source.tar.gz Dockerfile main.py requirements.txt

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines" \
  -d "{
    \"displayName\": \"Dockerfile agent\",
    \"spec\": {
      \"sourceCodeSpec\": {
        \"inlineSource\": {
          \"sourceArchive\": \"$(base64 < /tmp/source.tar.gz | tr -d '\n')\"
        },
        \"imageSpec\": {}
      }
    }
  }"

要求會傳回長時間執行的 Operation,容器建構和部署作業完成後,該作業會解析為已部署的 ReasoningEngine 資源。

容器映像檔

如要從容器映像檔部署,請先按照「自備容器」的設定操作說明,建構映像檔並推送至 Artifact Registry。如果使用 Agent Platform SDK 建立 Agent Platform 執行個體,請務必安裝符合 >=1.144 的 google-cloud-aiplatform 版本。容器映像檔必須透過通訊埠 8080 監聽 0.0.0.0 上的 HTTP 要求,並遵守執行階段合約。

這個部署方法適用於任何語言。

以下範例顯示 Dockerfile,用於建構監聽 0.0.0.0:8080 的容器映像檔:

Python

FROM python:3.13-slim
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8080

# Start an ADK API server or custom FastAPI server on 0.0.0.0:8080:
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

Go

FROM golang:1.24 AS builder
WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /app/server .

FROM gcr.io/distroless/static-debian12
WORKDIR /app
COPY --from=builder /app/server /app/server

EXPOSE 8080

# For an ADK Go agent using the built-in launcher:
# CMD ["/app/server", "web", "-host", "0.0.0.0", "-port", "8080", "agentengine"]
# For a custom Go HTTP server listening on 0.0.0.0:8080:
CMD ["/app/server"]

TypeScript

FROM node:22-slim
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

EXPOSE 8080

# For an ADK TypeScript agent (with @google/adk-devtools in package.json):
# CMD ["npx", "adk", "api_server", "/app/agents/my_agent", "--host=0.0.0.0", "--port=8080"]
# For a custom Node.js HTTP server listening on 0.0.0.0:8080:
CMD ["node", "dist/index.js"]

Java

FROM maven:3.9-eclipse-temurin-17
WORKDIR /app

COPY pom.xml .
COPY src ./src
RUN mvn package -DskipTests

EXPOSE 8080

# For an ADK Java agent using AdkWebServer (set --server.address=0.0.0.0):
# CMD ["sh", "-c", "mvn exec:java -Dexec.mainClass=com.google.adk.web.AdkWebServer -Dexec.args='--server.address=0.0.0.0 --server.port=${PORT:-8080} --adk.agents.source-dir=.'"]
# For a packaged Java HTTP server JAR listening on 0.0.0.0:8080:
CMD ["java", "-jar", "target/app.jar"]

如果容器實作執行階段合約轉送端點 (/api/reasoning_engine 和 /api/stream_reasoning_engine,ADK Go agentengine 啟動器也會公開),請在 class_methods (或 REST 中的 spec.classMethods) 宣告支援的作業,以便透過標準 query 和 streamQuery 要求叫用代理。如果容器執行 ADK API 伺服器 (例如 TypeScript 的 npx adk api_server 或 Java 的 AdkWebServer),請透過基礎 API Proxy (/api/run 和 /api/run_sse) 叫用其 /run 和 /run_sse 端點。

建構容器映像檔並推送至 Artifact Registry 後,請使用 Agent Platform SDK、REST API 或 Terraform 部署代理:

Agent Platform SDK

remote_agent = client.runtimes.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Optional: declare class_methods if your container implements /api/reasoning_engine or /api/stream_reasoning_engine
        # "class_methods": class_methods,
        # 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 上執行的代理,您可以查詢或刪除該代理。

remote_agent 物件對應至 AgentRuntime 類別,其中包含下列項目:

REST

向 reasoningEngines.create 方法傳送 POST 要求:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines" \
  -d '{
    "displayName": "Container image agent",
    "spec": {
      "containerSpec": {
        "imageUri": "CONTAINER_IMAGE_URI"
      }
    }
  }'

其中 CONTAINER_IMAGE_URI 對應至 Artifact Registry 中容器映像檔的 URI (例如 us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag)。要求會傳回長時間執行的 Operation,並在部署完成後解析為已部署的 ReasoningEngine 資源。

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. 系統會在本機產生一組構件,當中含有:
    • *.pkl:對應 local_agent 的 pickle 檔案。
    • requirements.txt:文字檔案,包含套件需求。
    • dependencies.tar.gz:包含額外套件的 tar 檔案。
  2. 為了暫存構件,這個檔案包會上傳至 Cloud Storage (位於對應的資料夾)。
  3. 各個構件的 Cloud Storage URI 會在 PackageSpec 中指定。
  4. Agent Runtime 服務會接收要求、建構容器,並在後端啟動 HTTP 伺服器。

部署作業延遲時間取決於安裝必要套件所需的總時間。部署完成後,remote_agent 會對應至在 Agent Platform 上執行的 local_agent 執行個體,且可供查詢或刪除。

remote_agent 物件對應至 AgentRuntime 類別,其中包含下列項目:

選用:取得代理資源 ID

每個部署的代理都有專屬 ID。您可以執行下列指令,取得已部署代理的資源名稱:

remote_agent.api_resource.name

回應應類似下列字串:

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

其中

選用:列出支援的操作

每個部署的代理都有一份支援作業清單。您可以使用 AgentRuntime.operation_schemas 取得已部署代理支援的操作清單:

remote_agent.operation_schemas()

每項作業的結構定義都是字典,記錄了可呼叫的代理方法資訊。支援的操作組合取決於您開發代理時使用的框架:

選用:授予已部署代理的權限

如果需要為部署的代理程式授予任何額外權限,請按照「設定代理程式的身分和權限」中的操作說明操作。

選用:使用企業基礎架構部署代理

如要部署代理,並提供包含安全性和管理層的完整環境,請複製並自訂下列 Application Design Center 範本:

後續步驟

指南

瞭解如何管理已部署至 Agent Platform 代管執行階段的代理。

指南

透過 Agent Platform Runtime 使用代理。