在 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 存储桶。
此部署方法仅适用于 Python。
Dockerfile
与从源文件部署类似。您可以直接从本地源代码部署代理,而无需使用 Cloud Storage 存储桶。如果您需要定义和控制已部署的 API 服务器,则此方法适用。部署的容器必须遵循运行时协定。
您可以将此部署方法与任何语言搭配使用。
容器映像
与从 Dockerfile 部署类似。您部署托管在 Artifact Registry 中的容器映像。如果您需要控制容器映像的构建过程并降低部署延迟时间,请使用此方法。容器映像必须遵循运行时协定。
您可以将此部署方法与任何语言搭配使用。
Agent Platform SDK
非常适合在 Colab 等环境中进行交互式开发,支持部署内存中的 local_agent 对象。此方法最适合结构不包含复杂、不可序列化组件的智能体。
如需开始使用,请按以下步骤操作:
- 完成前提条件
- 可选:配置智能体以进行部署
- 创建 Gemini Enterprise Agent Platform 实例
- 可选:获取智能体资源 ID
- 可选:列出支持的操作
- 可选:为所部署的智能体授予权限
前提条件
在部署智能体之前,请确保您已完成以下任务:
可选:配置智能体以进行部署
您可以为智能体进行可选配置。本部分中的示例使用 Python。
创建 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 文件路径。默认值为requirements.txt。
部署需要几分钟时间完成,在此期间,系统会在后台执行以下步骤:
- Agent Runtime 服务会从指定的 Git 代码库修订版本中提取源代码。
- 该服务会从
requirements_file(如果提供)安装依赖项。 - 该服务会使用指定的
entrypoint_module和entrypoint_object启动代理应用。
部署延迟时间取决于安装所需软件包花费的总时间。部署后,remote_agent 对应于在 Agent Platform 上运行的 local_agent 的实例,您可以查询或删除该实例。
remote_agent 对象对应于包含以下内容的 AgentRuntime 类:
- 包含已部署智能体相关信息的
remote_agent.api_resource。 您还可以调用remote_agent.operation_schemas()来返回remote_agent所支持操作的列表。如需了解详情,请参阅支持的操作。 - 允许同步服务交互的
remote_agent.api_client。 - 允许异步服务交互的
remote_agent.async_api_client。
公共 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):可选:相对于git_source.dir(如果未设置dir,则为代码库根目录)的 pip requirements 文件路径。默认值为requirements.txt。
部署需要几分钟时间完成,在此期间,系统会在后台执行以下步骤:
- Agent Runtime 服务会克隆指定修订版本的代码库。
- 该服务会从
requirements_file(如果该文件存在)安装依赖项。 - 该服务会使用指定的
entrypoint_module和entrypoint_object启动代理应用。
部署延迟时间取决于安装所需软件包花费的总时间。部署后,remote_agent 对应于在 Agent Platform 上运行的代理,您可以查询或删除该代理。
remote_agent 对象对应于包含以下内容的 AgentRuntime 类:
- 包含已部署智能体相关信息的
remote_agent.api_resource。 您还可以调用remote_agent.operation_schemas()来返回remote_agent所支持操作的列表。如需了解详情,请参阅支持的操作。 - 允许同步服务交互的
remote_agent.api_client。 - 允许异步服务交互的
remote_agent.async_api_client。
源文件
如需在 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中的文件和目录的总大小不应超过 8MB。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 文件的路径。默认值为打包源代码根目录下的requirements.txt。
部署需要几分钟时间完成,在此期间,系统会在后台执行以下步骤:
- Agent Platform SDK 会为
source_packages中指定的路径创建tar.gz归档。 - 此归档会经过编码,并直接发送到 Agent Platform API。
- Agent Runtime 服务接收归档文件,将其解压缩,从
requirements_file(如果提供)安装依赖项,并使用指定的entrypoint_module和entrypoint_object启动智能体应用。
部署延迟时间取决于安装所需软件包花费的总时间。部署后,remote_agent 对应于在 Agent Platform 上运行的 local_agent 的实例,您可以查询或删除该实例。
remote_agent 对象对应于包含以下内容的 AgentRuntime 类:
- 包含已部署智能体相关信息的
remote_agent.api_resource。 您还可以调用remote_agent.operation_schemas()来返回remote_agent所支持操作的列表。如需了解详情,请参阅支持的操作。 - 允许同步服务交互的
remote_agent.api_client。 - 允许异步服务交互的
remote_agent.async_api_client。
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 代理(/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 类:
- 包含已部署智能体相关信息的
remote_agent.api_resource。 您还可以调用remote_agent.operation_schemas()来返回remote_agent所支持操作的列表。如需了解详情,请参阅支持的操作。 - 允许同步服务交互的
remote_agent.api_client。 - 允许异步服务交互的
remote_agent.async_api_client。
REST
将 Dockerfile 和应用源文件打包到 .tar.gz 归档(最大 8 MB)的根级,对归档进行 base64 编码,然后向 reasoningEngines.create 方法发送 POST 请求:
# 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 请求,并遵循运行时合同。
您可以将此部署方法与任何语言搭配使用。
以下示例展示了用于构建监听 0.0.0.0:8080 的容器映像的 Dockerfile:
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 代理(/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 类:
- 包含已部署智能体相关信息的
remote_agent.api_resource。 您还可以调用remote_agent.operation_schemas()来返回remote_agent所支持操作的列表。如需了解详情,请参阅支持的操作。 - 允许同步服务交互的
remote_agent.api_client。 - 允许异步服务交互的
remote_agent.async_api_client。
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. }, )
部署需要几分钟时间完成,在此期间,系统会在后台执行以下步骤:
- 系统会在本地生成以下制品的软件包:
- 该软件包会上传到 Cloud Storage(位于相应的文件夹下),用来暂存制品。
- PackageSpec 中指定了相应制品的 Cloud Storage URI。
- Agent Runtime 服务会接收请求,并在后端构建容器并启动 HTTP 服务器。
部署延迟时间取决于安装所需软件包花费的总时间。部署后,remote_agent 对应于在 Agent Platform 上运行的 local_agent 的实例,您可以查询或删除该实例。
remote_agent 对象对应于包含以下内容的 AgentRuntime 类:
- 包含已部署智能体相关信息的
remote_agent.api_resource。 您还可以调用remote_agent.operation_schemas()来返回remote_agent所支持操作的列表。如需了解详情,请参阅支持的操作。 - 允许同步服务交互的
remote_agent.api_client。 - 允许异步服务交互的
remote_agent.async_api_client。
可选:获取智能体资源 ID
每个已部署的智能体都有一个唯一标识符。您可以运行以下命令来获取所部署智能体的资源名称:
remote_agent.api_resource.name
响应应如以下字符串所示:
"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"
其中
PROJECT_ID是所部署智能体运行的 Google Cloud 项目 ID。LOCATION是所部署智能体运行所在的区域。RESOURCE_ID是所部署智能体的 ID,以reasoningEngine资源的形式表示。
可选:列出支持的操作
每个已部署的智能体都有一份支持的操作列表。您可以使用 AgentRuntime.operation_schemas 获取已部署的智能体支持的操作列表:
remote_agent.operation_schemas()
每个操作的架构都是一个字典,用于记录您可以调用的代理方法的相关信息。支持的操作集取决于您用于开发智能体的框架:
可选:为所部署的智能体授予权限
如果需要向所部署的智能体授予任何其他权限,请按照为智能体设置身份和权限中的说明操作。
可选:使用企业基础架构部署代理
如需使用包含安全和治理层的完整环境部署智能体,请复制并自定义以下 Application Design Center 模板: