> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Vertex AI Agent Engine 快速教程
- URL: https://www.hubwiz.com/blog/vertex-ai-agent-engine-quick-tutorial/
- Published: 2026-03-21T02:59:35.000Z
- Updated: 2026-03-21T02:59:35.000Z
- Description: 如果你正在使用Google的Agent开发工具包（ADK）和Vertex AI Agent Engine，那你很幸运。该平台提供了从首次本地测试到全球规模、企业级部署的无缝路径。
- Author: admin
- Tags: TOOL, VERTEX AI AGENT ENGINE, #Import 2026-10-14 14:41

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

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

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

让我们开始吧。

## 1、本地构建智能体

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

```python
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服务器上将其"解冻"。

**代码：**

```python
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）：**

```python
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进入你的仓库，获取代码并部署它。

**代码：**

```python
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](https://medium.com/@jjaladi/from-prototype-to-production-mastering-agent-deployment-on-vertex-ai-agent-engine-27f7f409bb56?ref=hubwiz.com)

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