Agentforce DX 开发指南

Agentforce DX 完整开发指南：环境搭建（VS Code + Salesforce CLI + Extension Pack）、三种开发者环境选择（Sandbox/Scratch Org/Developer Edition）、Agent Spec 生成与迭代、Authoring Bundle 工作流、Agent Script 编码与 Vibes 辅助、发布与同步元数据、预览与调试（Simulated/Live/Trace）。将 Agent 开发融入 Salesforce DevOps。...

首页/ 文章列表/ Agentforce DX 开发指南
📅 2025/7/14 ✍️ ponybai 🏷️ agentforce, salesforce, dx, devops

使用 Agentforce DX 构建 Agent

s127

Agentforce DX 是 Salesforce DX 工具链的扩展，让 Agent 开发融入现代 DevOps 流程。它将 Agent 作为元数据管理，提供 CLI 命令和 VS Code 扩展来在 Agentforce Studio 之外创建、预览和测试 Agent，并在本地 DX 项目与 Scratch Org、Sandbox、生产环境之间迁移 Agent 元数据。

Agentforce Builder UI 和 Testing Center 让你通过点击而非代码来创建和测试 Agent。但现代 DevOps 流程要求将 Agent 源代码存储在版本控制系统（VCS）中作为生产环境的唯一真相源，Agentforce DX 使之成为可能。

什么是 Agentforce DX？

s128

Agentforce DX 提供低代码工具（Agentforce Builder、Flow Builder）和专业代码工具（VS Code、Salesforce CLI）之间的灵活切换。典型的迭代开发流程：

  1. 本地创作：生成 Authoring Bundle（含 Agent Script 蓝图），编码脚本，预览 Agent
  2. 发布到 Org：发布 Bundle，在 Agentforce Builder UI 中继续编辑
  3. 拉取变更：将 Org 中的元数据变更拉回本地 DX 项目
  4. 编码自定义动作：用 VS Code + Vibes 创建 Apex 类，更新 Agent Script
  5. 部署：将本地更新部署回 Org
  6. 提交 VCS：定期将变更提交到 GitHub（真相源）

反馈与更新：通过 GitHub Issues 提交反馈，查看周发布说明了解最新变更。

设置开发环境

s129

设置 Agentforce DX 环境与标准 Salesforce DX 环境类似，增加了一些 Agent 特定任务。

安装专业代码工具

s130
  1. 下载安装 VS Code
  2. 从 VS Code Marketplace 安装 Salesforce Extension Pack（含 Agentforce DX、Agent Script Language Server、Apex、Vibes 等扩展）
  3. 安装 Salesforce CLI
  4. 在 VS Code 集成终端运行 sf search agent 查看可用命令
  5. 使用 sf agent generate authoring-bundle --help 查看命令详情

AI 工具选择：推荐使用 Agentforce Vibes Extension（安全 AI 模型）。也可使用 Cursor、Claude Code 等第三方 AI 工具，配合 sf-skills 仓库中的 Agentforce Skills。

两个 Vibes 产品：Agentforce Vibes Extension（VS Code 扩展，本地安装）和 Agentforce Vibes IDE（基于 Web 的 VS Code，预装 Salesforce Extension Pack + CLI）。

开发者环境选择

s131
环境特点适用场景
Sandbox生产 Org 的副本，含元数据。Developer/Developer Pro 可频繁刷新Agent 依赖 Data Library/Data 360 时；集成和用户测试
Scratch Org空环境，快速创建，源驱动开发不依赖 Data Library 的 Agent；全新功能开发
Developer Edition免费，含 Agentforce + Data 360学习和原型验证

推荐：Agent 依赖 Data Library 时使用 Sandbox。组合 Data 360 和 Agentforce 是创建成功 Agent 的最佳方式。

创建项目、授权 Org 与 Agent 用户

s132

创建 Salesforce DX 项目（Agent 模板）

Agent 模板创建含示例 Agent（Local Info Agent）的 DX 项目，包含三种子代理类型（Apex/Prompt Template/Flow）和 Scratch Org 配置文件：

# VS Code: View > Command Palette > SFDX: Create Project > Agent 模板
# 或 CLI:
sf template generate project --name agentforcedx --template agent
cd agentforcedx

授权 Org

# VS Code: SFDX: Authorize an Org
# 或 CLI:
sf org login web --alias agentforce --set-default
# CI/CD 系统使用 JWT 授权流程

启用 Einstein 和 Agentforce

  1. 如需 Data 360：Setup > Data Cloud Setup Home > Turn On Data 360（最多 60 分钟）
  2. Setup > Einstein Setup > Turn on Einstein
  3. Setup > Agentforce Agents > 启用 Agentforce

系统权限

系统管理员自动拥有所有权限。非管理员需要：发布 Bundle（Modify All Data + Manage AI Agents）、预览 Agent（Agent Platform Builder）。生成/验证 Bundle 无需额外权限。

创建 Agent 用户

sf org create agent-user --target-org my-org
# 自定义名称：
sf org create agent-user --first-name Service --last-name Agent --base-username service-agent@corp.com --target-org my-org

命令自动：创建 Einstein Agent User 配置文件用户、分配必需权限集（AgentforceServiceAgentBase/AgentforceServiceAgentUser/EinsteinGPTPromptTemplateUser）、生成全局唯一用户名。Agent 用户无密码，不能登录 Salesforce。

使用 Agentforce DX 创作 Agent

s133

创作 Agent 指生成和编码 Agent Script 文件，然后发布到开发 Org。Agent Script 是下一代 Agentforce Agent 的基础——结合自然语言的灵活性和程序化表达式的可靠性。

Agent 的 Agent Script 文件是 AiAuthoringBundle（Authoring Bundle）元数据组件的一部分。可以从零在 DX 项目中生成，也可以先在 Org 中创建然后拉取。

创作新 Agent 的工作流

s134
  1. （可选但推荐）生成 Agent Spec：sf agent generate agent-spec 创建 YAML 文件
  2. 生成 Authoring Bundle：基于 Spec 文件生成含 Agent Script 的 Bundle
  3. 编码 Agent Script：在 VS Code 中编辑 .agent 文件（语法高亮/linting/验证）
  4. 预览 Agent：交互式测试，模拟或 Live 模式
  5. 发布 Bundle：发布到 Org，同步元数据

拉取并修改已有 Agent 的工作流

s135
  1. 在 Agentforce Builder 中创建 Agent（使用新版 Builder，非 Legacy）
  2. 拉取所有 Authoring Bundle：sf project retrieve start --metadata AiAuthoringBundle --metadata Agent --target-org <org>
  3. 在 VS Code 中编码 Agent Script 文件
  4. 预览 → 发布

生成 Agent Spec 文件

s136

Agent Spec 是 YAML 格式文件，包含 Agent 基本信息和 LLM 生成的子代理列表。虽然可选，但强烈推荐——它让后续生成的 Agent Script 文件更贴合你的特定需求。

生成与迭代优化

s137
# 交互式生成
sf agent generate agent-spec --target-org my-org

# 使用 Flag 跳过提示
sf agent generate agent-spec --type customer \
  --company-name "Coral Cloud Resorts" \
  --company-description "Provide a luxury experience." \
  --max-topics 4 --tone formal

# 迭代改进：传入已有 Spec 文件 + 优化属性
sf agent generate agent-spec --spec specs/agentSpec.yaml \
  --role "Manage luxury resort concierge services including bookings, dining, spa, and activities"

迭代策略：Spec 文件上部是你提供的 Agent 属性，下部是 LLM 生成的子代理列表。反复运行命令，每次传入最新 Spec + 优化属性，LLM 生成的子代理列表逐步改进。

Flags：--type（customer/internal）、--company-name、--company-description、--role、--max-topics、--tone。使用 --help 查看完整列表。

生成 Authoring Bundle

s138

Authoring Bundle 包含 Agent 的蓝图——Agent Script 文件（.agent）。可以从 Agent Spec 文件或直接从模板生成。

VS Code 与 CLI 生成

s139
# 基于 Spec 文件生成
sf agent generate authoring-bundle --spec specs/agentSpec.yaml

# 不基于 Spec（生成样板 Agent Script）
sf agent generate authoring-bundle --agent-name MyAgent

# VS Code: Command Palette > SFDX: Generate Agent Authoring Bundle

生成的 Bundle 在 aiAuthoringbundles/ 目录下。每个 Bundle 包含 Agent Script 文件（.agent）和相关配置。可以先发布空 Bundle 在 Org 中创建 Agent 元数据（不推荐——基于 Agent Script 的 Agent 更灵活易维护）。

编码 Agent Script 文件

s140

Agent Script 文件（.agent）是 Agent 的完整蓝图。Agentforce DX 在 VS Code 中完全支持 Agent Script 语言：语法高亮、linting、内部验证。

Agent Script 概览与编码工作流

s141

Agent Script 文件结构：system（指令+消息）、config（developer_name/default_agent_user/description）、variables（全局变量）、start_agent（入口+路由）、subagent（子代理+动作）。

编码循环：编辑 .agent 文件 → 保存 → sf agent validate 验证编译 → 预览测试 → 再编辑。Agent Script 是编译型语言，保存版本时编译为底层元数据。

# 验证 Agent Script 文件
sf agent validate authoring-bundle --file aiAuthoringbundles/MyAgent/MyAgent.agent

Vibe Coding + Sample Prompts + 验证

s142

Agentforce Vibes 辅助编码：用自然语言描述需求（如"如果订单总额超 $100 则免运费"），Vibes 自动生成对应的 Agent Script 代码。Vibes 也支持自动代码补全。

Sample Prompts（示例提示词）：在 Agent Script 中添加 sample_prompts 属性，定义 Agent 能处理的示例用户问题。有助于测试和文档化。

编码提示：Agent Script 中指定 default_agent_user 为之前创建的 Agent 用户名。使用 sf agent validate 频繁验证确保编译通过。

发布 Authoring Bundle 到 Org

s143

发布工作流

s144
# 发布到默认 Org
sf agent publish authoring-bundle --file aiAuthoringbundles/MyAgent/MyAgent.agent

# VS Code: Command Palette > SFDX: Publish Agent Authoring Bundle

发布过程：自动创建底层 Agent 元数据（AiAuthoringBundle + Agent 类型）→ 同步元数据到 Org → Agent 可在 Agentforce Builder 中打开编辑 → 可 Commit Version + Activate。

发布后 Agent 进入"Ready to Test"状态。可在 Org 的 Testing Center 中测试，也可继续在 VS Code 中编码和重新发布。

同步开发 Org 与 DX 项目

s145

拉取、部署与删除 Agent 元数据

s146
# 拉取所有 Authoring Bundle 和 Agent 元数据
sf project retrieve start --metadata AiAuthoringBundle --metadata Agent --target-org my-org

# 拉取特定 Bundle 及其所有版本
sf project retrieve start --metadata "AiAuthoringBundle:Local_Info_Agent*" --target-org my-org

# 部署本地元数据到 Org
sf project deploy start --target-org my-org

# 删除 Agent（需先停用）
sf agent delete --target-org my-org --agent-name MyAgent

同步原则：VCS（GitHub）是真相源。在 Org 中做的任何变更都应拉回本地 DX 项目并提交到 VCS。在本地做的变更都应部署到 Org。

Agent 元数据：浅析

s147

元数据类型：Bundle 与 Agent

s148
元数据类型说明
AiAuthoringBundle包含 Agent Script 文件（.agent）的 Authoring Bundle。每个 Agent 一个 Bundle，支持版本管理
AgentAgent 实例元数据。引用 Authoring Bundle + 版本号 + 激活状态 + 连接配置（Messaging/Voice 等）

Bundle 文件在 aiAuthoringbundles/<AgentName>/ 下，含 <AgentName>.agent（Agent Script）和版本子目录。Agent 元数据在 agents/ 下。

预览和调试 Agent

s149

预览类型与模式

s150
维度选项
预览类型Simulated（模拟）：动作返回 mock 数据（未实现真实动作时）
Live：动作调用真实 Flow/Apex/Prompt
预览位置VS Code 内置面板 / CLI 命令 / Agentforce Builder UI
Trace开启后输出每个推理步骤的详细日志（响应时间、工具选择、Prompt 内容）

VS Code 交互式预览

s151
# CLI 预览
sf agent preview authoring-bundle --file aiAuthoringbundles/MyAgent/MyAgent.agent

# VS Code: 右键 .agent 文件 > SFDX: Preview Agent
# 或 Command Palette > SFDX: Preview Agent Authoring Bundle

VS Code 预览面板支持：输入 utterance（用户发言）、查看 Agent 响应、切换 Simulated/Live 模式、开启 Trace 查看推理细节、配合 Apex Replay Debugger 断点调试。

程序化预览与会话 Trace 文件

s152
# 带 Trace 的 CLI 预览
sf agent preview authoring-bundle --file aiAuthoringbundles/MyAgent/MyAgent.agent --trace

# 生成会话 Trace 文件（JSON 格式，含完整推理链）
# Trace 文件可用于分析 Agent 行为、排查问题、回归测试

Trace 文件包含：每次客户发言的完整推理过程、选择的工具和原因、LLM 输入/输出 Prompt、每个步骤的时间戳。适合深度调试和 CI/CD 自动化测试。

Agentforce DX 将 Agent 开发完全融入现代 Salesforce DevOps 流程。建议配合 Agent Script 开发指南、Agent 测试 和 Agent 管理 章节形成完整的开发-测试-部署知识体系。