Agentforce DX 构建代理

什么是 Agentforce DX？

Salesforce DX 是一套用于在 Salesforce 平台上构建、测试和交付应用的工具。Agentforce DX 将这些工具扩展到 Agent 开发领域。Agent 和其它 Salesforce 自定义配置一样也是元数据，因此可以存储在版本控制系统（VCS）中作为真相源。

Agentforce DX 提供 CLI 命令和 VS Code 扩展，让你在 Agentforce Studio 之外创建、预览和测试 Agent，并在 DX 项目、Scratch Org、Sandbox 和生产组织之间移动 Agent 元数据。

Agentforce DX 概述

Pro-Code 与 Low-Code 工具的协作

在构建 Agent 时，你可以在低代码工具（如 Agentforce Builder UI、Flow Builder）和专业代码工具（VS Code、Salesforce CLI）之间自由切换，形成迭代开发流程：

在本地 DX 项目中通过生成 Authoring Bundle 来创建 Agent，编写 Agent Script 文件
将 Authoring Bundle 发布到组织，然后在 Agentforce Builder UI 中继续编辑
将在组织中所做的元数据更改检索回 DX 项目
使用 VS Code 创建 Apex 类，实现自定义动作
将本地更新部署回组织
预览 Agent 验证行为
定期将更改提交到 VCS（如 GitHub）—— VCS 是真相源

设置开发环境

安装专业代码工具

基本工具包括 VS Code（IDE，包含代码编辑器、构建自动化、调试器、智能代码补全）和 Salesforce CLI（命令行界面，Agent 相关命令归在 "agent" 主题下）。

Salesforce 扩展包（精选组合）：

Agentforce DX —— 创建、预览和测试 Agent
Agent Script Language Server —— .agent 文件的语法高亮、代码检查和验证
Apex Language Server —— Apex 代码支持
Apex Replay Debugger —— 调试 Agent 调用的 Apex 类
Agentforce Vibes —— AI 辅助：从自然语言生成代码、自动建议补全

Agentforce Vibes IDE（基于 Web 的 VS Code）：预装扩展包和 CLI，可在浏览器中构建 Agent。你也可以使用其他 AI 工具（Cursor、Claude Code），只需安装 Salesforce CLI 并从 sf-skills GitHub 仓库下载 Agentforce Skills。

安装专业代码工具

开发者环境选择

环境
特点
适用场景

Sandbox
生产组织的副本，含创建时的元数据
推荐用于 Agentforce DX，尤其当 Agent 需要 Data Library 时

Scratch Org
空白环境，快速创建，源驱动开发
Agent 不需要 Data Library 时使用

Developer Edition Org
免费注册，已启用 Agentforce 和 Data 360
学习和实验

开发者环境

创建 DX 项目、授权组织和 Agent 用户

在组织中启用 Einstein 和 Agentforce：

开启 Data 360（如需要，可能需要最多 60 分钟）
设置 → Einstein Setup → Turn on Einstein
设置 → Agentforce Agents → Enable Agentforce

创建 Salesforce DX 项目：使用 "Agent" 项目模板（含示例 "Local Info Agent"）。CLI：sf template generate project --name agentforcedx --template agent。VS Code：命令面板 → SFDX: Create Project → Agent 模板。包含必需的 Einstein + Agentforce 设置的 Scratch Org 配置。
授权组织：CLI：sf org login web --alias agentforce --set-default。CI/CD 使用 JWT 授权流程。
创建默认 Agent 用户：sf org create agent-user --target-org my-org。自动设置正确的简档和权限集。

创建项目和组织

使用 Agentforce DX 编写 Agent

编写 Agent

工作流一：从零开始创建新 Agent

（可选但推荐）生成 Agent Spec YAML 文件：sf agent generate agent-spec --target-org <org>，捕获 Agent 角色、公司信息和 LLM 生成的子代理列表
生成 Authoring Bundle：sf agent generate authoring-bundle，基于 Agent Spec 文件或默认模板
编写 Agent Script 文件：在 VS Code 中直接编辑或使用 Agentforce Vibes 进行 Vibe Coding
预览 Agent：模拟模式（Mock 动作）或实时模式（真实 Apex/Flows）
发布到组织：sf agent publish authoring-bundle

新建 Agent 工作流

工作流二：获取并修改已有 Agent

在 Agentforce Builder 中创建 Agent（必须使用新 Builder，不能是 Legacy）
检索 Authoring Bundle 到 DX 项目：sf project retrieve start --metadata AiAuthoringBundle --metadata Agent --target-org <org>
在 VS Code 中编辑 Agent Script 文件
预览 → 发布

修改已有 Agent 工作流

生成 Agent Spec 文件

Agent Spec 是一个 YAML 格式文件，包含 Agent 的基本信息。上部是你提供的 Agent 属性，下部是 LLM 生成的子代理列表。虽然可选，但使用 Spec 能让 Authoring Bundle 中的 Agent Script 更加定制化。

迭代优化：使用 --spec 标志重新运行命令，每次迭代改进描述，获得更好的子代理列表：

sf agent generate agent-spec --target-org <org>



![Agent Spec](https://sfdcvideotest.oss-cn-beijing.aliyuncs.com/media/ADG001/slide_136/image.png)

![迭代优化 Spec](https://sfdcvideotest.oss-cn-beijing.aliyuncs.com/media/ADG001/slide_137/image.png)


### 生成 Authoring Bundle


Authoring Bundle 是 Agent 的蓝图，属于 `AiAuthoringBundle` 元数据类型，包含 Agent 的 `.agent` 脚本文件。

VS Code 方式：命令面板 &rarr; AFDX: Create Agent &rarr; 选择模板（默认 / 从 Agent Spec YAML）

CLI 方式：

`sf agent generate authoring-bundle
# 或使用标志：
sf agent generate authoring-bundle --no-spec --name "My Bundle" --api-name My_Bundle`

输出：aiAuthoringBundles/<API-name>/ 目录，包含 .agent 文件 + .bundle-meta.xml。

生成 Authoring Bundle

VS Code 和 CLI 方式

编写 Agent Script 文件

VS Code 中完整语言支持：语法高亮、红色波浪线错误标记、大纲视图显示块符号树。

开发流程：

从 aiAuthoringBundles/<API-name>/ 目录打开 .agent 文件
编写 Agent Script
Vibe Coding：打开 Agentforce Vibes 面板，启用 developing-agentforce、testing-agentforce、observing-agentforce Skills，输入自然语言提示
定期验证：右键 → AFDX: Validate This Agent（或 sf agent validate authoring-bundle）
定期预览查看效果

编写 Agent Script

Agent Script 编码工作流

Agentforce Vibes Skills：

developing-agentforce —— 使用 Agent Script 构建、修改和部署 Agent
testing-agentforce —— 自动化测试用例推导、冒烟测试、Trace 分析、迭代修复
observing-agentforce —— 监控和可观察性

Vibe Coding 提示示例："Review all the agent instructions and improve them for focus and conciseness."

Vibe Coding

发布 Authoring Bundle

发布是指将 Agent Script 文件编译生成 Bot 和 GenAi 元数据的过程，相当于在 Agentforce Builder UI 中点击 Commit Version。发布流程：

Agent Script 文件被验证 —— 必须编译成功
编译后的脚本发布到组织，创建 Bot、BotVersion 和 GenAi* 元数据
新/更改的元数据被检索回 DX 项目（可使用 --skip-retrieve 跳过）
bundle-meta.xml 被填充 Agent 元数据映射

VS Code：右键 .agent 文件 → AFDX: Publish this Agent。先部署任何本地 Apex/Flow 更改。CLI：sf agent publish authoring-bundle。

注意：只有草稿（未版本化）的 Bundle 可以发布；已版本化的 Bundle 名称后会追加版本号（如 My_Bundle_1）。

发布工作流

同步开发组织与 DX 项目

使用标准 Salesforce DX 命令管理 Agent 元数据：

操作
Authoring Bundle (AiAuthoringBundle)
Published Agent (Agent 伪类型)

检索
--metadata AiAuthoringBundle:Local_Info_Agent
--metadata Agent:Local_Info_Agent（含 Apex + Flows）

部署
--metadata AiAuthoringBundle:Local_Info_Agent
--metadata Agent:Local_Info_Agent（仅 Agent 元数据）

删除
删除 Bundle + 关联的 Bot/BotVersion/GenAiPlannerBundle
仅删除 Agent 元数据（不含 Apex/Flow）

使用通配符处理所有版本：--metadata "AiAuthoringBundle:Local_Info_Agent*"。

检索、部署和删除

Agent 元数据：浅析

Agent 元数据

理解 Agent 关联的元数据类型有助于开发：

元数据类型
用途

AiAuthoringBundle
Agent 的蓝图，包含 .agent 脚本文件

Bot
Einstein Bot（聊天机器人）的顶层表示

BotVersion
特定版本的配置，一次只有一个活跃版本

GenAiPlannerBundle
推理引擎——将其加入 Bot+BotVersion 后将 Chatbot 升级为 Agent

GenAiPlugin
表示子代理（针对特定工作的一系列动作）

GenAiFunction
表示 Agent 动作

核心公式：Bot + BotVersion = 基础聊天机器人。Bot + BotVersion + GenAiPlannerBundle = 智能 Agent。

元数据类型

预览和调试 Agent

预览和调试

两种预览源

Agent Script 文件（本地） —— 直接从 DX 项目中的 .agent 文件预览
已发布的 Agent（组织中） —— 预览已在组织中的激活 Agent

两种预览模式

模拟模式（Simulated） —— 仅使用 Agent Script 文件，Mock 所有动作。无组织数据风险，适用于 Apex/Flows 未就绪时
实时模式（Live） —— 使用组织中的真实 Apex 类、Flows、提示模板和用户。最准确。可使用 Apex Replay Debugger

Trace 消息

实时查看预览与组织之间交换的精确 JSON 消息，包括 Agent 如何解释话语、选择了哪些动作及其原因、API 调用、响应生成。会话结束后可下载 Response 和 Tracer JSON 文件。

预览类型和模式

VS Code 交互式预览

打开 Agentforce DX 面板（点击 Activity Bar 中的 Agentforce DX 图标）
从下拉菜单选择 Agent（Agent Script 部分或 Published 部分）
选择 Simulation 或 Live Test → Start
在聊天窗口中与 Agent 对话，查看 Agent 响应
Agent Tracer 标签页：查看 JSON 消息，点击 Open JSON 获取完整 Trace
保存聊天历史：下载 Response 和 Trace 文件

VS Code 交互式预览

程序化预览（适用于 CI/CD 和 Vibe-Coding）

`# 开始会话
sf agent preview start --authoring-bundle My_Local_Agent

发送消息

sf agent preview send --authoring-bundle My_Local_Agent --utterance "What can you do?" --session-id

列出会话

sf agent preview sessions

结束会话

sf agent preview end --authoring-bundle My_Local_Agent --session-id `
```

会话 Trace 文件包含 transcript.json（完整对话记录）和 traces/.json（完整 API 消息：响应类型、意图、调用的子代理、执行计划等）。

程序化预览

Agentforce DX 将现代 DevOps 实践引入 Agent 开发，让你能够在本地编写、验证、预览和发布 Agent，同时保持版本控制作为真相源。

文章来源：https://www.salesforcecrm.cn/article/agentforce/agentforce-dx-guide.html

Agentforce DX 开发者指南

什么是 Agentforce DX？

Pro-Code 与 Low-Code 工具的协作