Agentforce DX 开发者指南

Agentforce DX 将 Salesforce DX 工具扩展到 Agent 开发领域。涵盖环境搭建（VS Code/CLI/扩展包）、Sandbox 与 Scratch Org 选择、两种 Authoring 工作流（新建/修改已有）、Agent Spec 与 Authoring Bundle 生成、Agent Script 编码与 Vibe Coding、发布到组织、元数据同步、Agent 元数据类型解析、以及交互式与程序化预览调试。...

首页/ 文章列表/ Agentforce DX 开发者指南
📅 2026/7/4 ✍️ ponybai 🏷️ Agentforce

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）之间自由切换，形成迭代开发流程：

  1. 在本地 DX 项目中通过生成 Authoring Bundle 来创建 Agent，编写 Agent Script 文件
  2. 将 Authoring Bundle 发布到组织，然后在 Agentforce Builder UI 中继续编辑
  3. 将在组织中所做的元数据更改检索回 DX 项目
  4. 使用 VS Code 创建 Apex 类，实现自定义动作
  5. 将本地更新部署回组织
  6. 预览 Agent 验证行为
  7. 定期将更改提交到 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 用户

1. 在组织中启用 Einstein 和 Agentforce：

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

2. 创建 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 配置。

3. 授权组织：CLI：sf org login web --alias agentforce --set-default。CI/CD 使用 JWT 授权流程。

4. 创建默认 Agent 用户：sf org create agent-user --target-org my-org。自动设置正确的简档和权限集。

创建项目和组织

使用 Agentforce DX 编写 Agent

编写 Agent

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

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

新建 Agent 工作流

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

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

修改已有 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 迭代优化 Spec

生成 Authoring Bundle

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

VS Code 方式：命令面板 → AFDX: Create Agent → 选择模板（默认 / 从 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 中完整语言支持：语法高亮、红色波浪线错误标记、大纲视图显示块符号树。

开发流程：

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

编写 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

发布 Authoring Bundle

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

  1. Agent Script 文件被验证 —— 必须编译成功
  2. 编译后的脚本发布到组织，创建 Bot、BotVersion 和 GenAi* 元数据
  3. 新/更改的元数据被检索回 DX 项目（可使用 --skip-retrieve 跳过）
  4. 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 交互式预览

  1. 打开 Agentforce DX 面板（点击 Activity Bar 中的 Agentforce DX 图标）
  2. 从下拉菜单选择 Agent（Agent Script 部分或 Published 部分）
  3. 选择 Simulation 或 Live Test → Start
  4. 在聊天窗口中与 Agent 对话，查看 Agent 响应
  5. Agent Tracer 标签页：查看 JSON 消息，点击 Open JSON 获取完整 Trace
  6. 保存聊天历史：下载 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 <id>

# 列出会话
sf agent preview sessions

# 结束会话
sf agent preview end --authoring-bundle My_Local_Agent --session-id <id>

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

程序化预览

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