TOOL

Vertex AI Agent Engine 快速教程

如果你正在使用Google的Agent开发工具包（ADK）和Vertex AI Agent Engine，那你很幸运。该平台提供了从首次本地测试到全球规模、企业级部署的无缝路径。

admin

• 8 min read
Vertex AI Agent Engine 快速教程
微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署
AI工具导航 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

构建生成式AI智能体只是成功了一半。一旦你的提示工程完美无缺，工具在本地机器上运行顺畅，你就会面临真正的挑战：将智能体部署到云端，以便用户可以与其交互。

如果你正在使用Google的Agent开发工具包（ADK）和Vertex AI Agent Engine，那你很幸运。该平台提供了从首次本地测试到全球规模、企业级部署的无缝路径。

然而，没有"一刀切"的部署按钮。根据你在软件开发生命周期中所处的位置，你需要不同的策略。在本文中，我们将详细介绍AI智能体的确切生命周期，从快速本地原型开始，一直到自动化的、生产就绪的CI/CD流程。

让我们开始吧。

1、本地构建智能体

在部署之前，我们需要部署的内容。让我们使用ADK构建一个简单的客户支持智能体。在你的本地IDE或Jupyter Notebook中，像这样定义你的智能体：

from google.adk.agents import LlmAgent
from vertexai.preview.reasoning_engines import AdkApp

# 1. 定义智能体的核心逻辑
customer_support_agent = LlmAgent(
    name="retail_support_agent",
    model="gemini-2.5-flash",
    instructions="你是一个在线零售店的有帮助的客户支持助手。请礼貌且简洁。"
)

# 2. 将其包装在AdkApp中，以便Agent Engine知道如何提供它
adk_app = AdkApp(agent=customer_support_agent)

在这个阶段，你可能正在使用adk_app.run("我的订单在哪里？")在本地测试查询。它运行完美。现在，你想测试它在云端托管时的行为。

2、快速通道——内存Python对象部署

当你处于原型设计阶段（通常在Google Colab或Jupyter Notebook中迭代）时，你不想浪费时间设置Dockerfile、复杂的文件夹结构或Git分支。你只想现在就将你的实时代码推送到云端。

为此，你可以使用内存Python对象部署。

在幕后，这个方法获取当前位于你计算机RAM中的实时adk_app对象，使用序列化（通过cloudpickle）将其"冻结"为文件，上传到Google Cloud Storage存储桶，然后在Vertex AI服务器上将其"解冻"。

代码：

import vertexai
from vertexai.preview import reasoning_engines

# 初始化Vertex AI。对象部署必须需要暂存桶
# 这样Vertex AI才有地方上传序列化的.pkl文件。
vertexai.init(
    project="your-gcp-project-id", 
    location="us-central1", 
    staging_bucket="gs://my-agent-staging-bucket"
)

print("正在将实时智能体部署到Vertex AI...")

# 直接部署实时的内存对象
remote_agent = reasoning_engines.ReasoningEngine.create(
    reasoning_engine=adk_app,  # 传递实时Python对象
    requirements=[
        "google-adk",
        "google-cloud-aiplatform[adk,reasoningengine]"
    ],
    display_name="交互式笔记本原型"
)

print(f"成功！智能体端点：{remote_agent.resource_name}")

**为什么它很棒：**只需几秒钟。它是数据科学家想要在云环境中测试快速提示调整时的终极"保存状态"。

**为什么不用于生产：**序列化出了名地脆弱。如果你的智能体使用不可序列化的组件（如打开的数据库连接、网络套接字或复杂的线程锁），此部署将崩溃。此外，因为它依赖于本地机器的状态，所以几乎不可能可靠地复现。

3、认真对待——通过CI/CD实现生产化

你的原型在利益相关者中大获成功。现在，软件工程团队需要接手。

生产化意味着从脆弱的内存对象部署转向健壮的CI/CD（持续集成/持续部署）流水线。你需要版本控制、同行评审、自动化测试和可复现的构建。

为此，你必须将代码打包成物理文件（例如agent.py文件和requirements.txt文件）。Vertex AI Agent Engine为你提供了两种出色的方式来在生产工作流中部署这些文件。

生产选项A：从源文件部署

使用此方法，你的CI/CD流水线（如GitHub Actions、GitLab CI或Jenkins）或基础设施即代码工具（如Terraform）将本地源文件目录打包并直接推送到Vertex AI。

Vertex AI然后使用你的文件从头构建一个新的容器。没有pickle、没有冻结的内存——只是标准的、健壮的Python执行。

代码（Python SDK）：

from vertexai.preview import reasoning_engines

# 不传递对象，而是传递源代码目录的路径
remote_agent = reasoning_engines.ReasoningEngine.create(
    reasoning_engine="./my_agent_src_directory", 
    requirements="./my_agent_src_directory/requirements.txt",
    display_name="生产智能体 - 源文件部署"
)

（注意：如果你在终端或CI脚本中使用ADK CLI，可以通过运行以下命令实现完全相同的效果：adk deploy agent_engine --agent_folder ./my_agent_src_directory）

生产选项B：从Developer Connect部署（GitOps）

如果你的CI/CD服务器不推送文件到Google Cloud，而是让Google Cloud在代码合并时直接从你的Git仓库拉取文件呢？

这就是Developer Connect的作用。你将Google Cloud项目直接链接到你的GitHub、GitLab或Bitbucket仓库。你配置Vertex AI监视特定分支（例如main）。当触发时，Vertex AI进入你的仓库，获取代码并部署它。

代码：

from google.cloud import aiplatform_v1beta1

# 1. 初始化服务客户端
client = aiplatform_v1beta1.ReasoningEngineServiceClient()

# 2. 定义Developer Connect GitOps源
developer_connect_source = aiplatform_v1beta1.ReasoningEngineSpec.SourceCodeSpec.DeveloperConnectSource(
    # GCP中已链接Git仓库的资源名称
    repository="projects/12345/locations/us-central1/connections/my-github-connection/gitRepositoryLinks/my-agent-repo",
    branch="main",
    directory="src/customer_support_agent"  # 仓库内的文件夹
)

# 3. 通过底层API创建Reasoning Engine
operation = client.create_reasoning_engine(
    parent="projects/12345/locations/us-central1",
    reasoning_engine=aiplatform_v1beta1.ReasoningEngine(
        display_name="生产智能体 - GitOps部署",
        spec=aiplatform_v1beta1.ReasoningEngineSpec(
            package_spec=aiplatform_v1beta1.ReasoningEngineSpec.PackageSpec(
                python_version="3.11"
            ),
            source_code_spec=aiplatform_v1beta1.ReasoningEngineSpec.SourceCodeSpec(
                developer_connect_source=developer_connect_source,
            ),
        )
    )
)
remote_agent = operation.result()

4、源文件 vs Developer Connect用于CI/CD

选项A和选项B都适用于生产，但它们迎合不同的架构理念。以下是它们在设计CI/CD流程时的对比：

从源文件部署（"推送"方法）

优点：

  • 最大灵活性：你可以在CI运行器中运行复杂的自定义构建步骤（如编译动态资源、运行密集型单元测试或获取动态密钥），然后再将最终打包的目录推送到GCP。
  • IaC友好：与Terraform或Pulumi等工具完美集成，这些工具天生擅长压缩本地目录并将其推送到云端端点。
  • 不需要暂存桶：与内存对象方法不同，源文件部署处理打包而不需要你管理GCS暂存桶。

缺点：

  • 需要你的CI/CD运行器安全地持有具有足够权限的Google Cloud凭据来执行部署。
  • 如果开发者从笔记本电脑手动运行命令，完全绕过CI/CD流水线，则存在"本地状态"部署的风险。

从Developer Connect部署（"拉取"或GitOps方法）

优点：

  • 安全和审计的黄金标准：部署与特定的Git提交哈希不可变地绑定。如果生产中出现问题，你确切知道是哪个提交导致的，使回滚变得简单。
  • 无凭据CI/CD：你的外部CI工具（如GitHub Actions）不需要高级GCP部署凭据。GCP承担获取代码的责任，大大减少了你的攻击面。
  • 真正的GitOps：鼓励一种文化，即main分支是生产中运行内容的绝对、无可争议的真相来源。

缺点：

  • 初始设置较高：需要前期进行管理工作来配置Developer Connect、授权OAuth应用并建立Git提供商和Google Cloud之间的安全链接。
  • 预处理能力较弱：因为Vertex AI直接从仓库拉取代码，你不能轻易地在仓库和部署之间运行自定义构建脚本或代码转换。

5、结束语

如果你是数据科学家在笔记本上试验想法，请使用Python对象部署。它快速且无摩擦。

如果你的团队严重依赖Terraform、自定义CI脚本或需要预部署构建步骤的复杂monorepo，请选择源文件部署。

如果你的组织优先考虑安全性、GitOps和严格的可审计性，并且你想要一个在每次PR合并时自动部署的自动化流水线，那么Developer Connect是终极的企业解决方案。

部署愉快！

原文链接: From Prototype to Production: Mastering Agent Deployment on Vertex AI Agent Engine

汇智网翻译整理，转载请标明出处