Agentforce DX Agent 管理指南

使用 Agentforce DX 管理 Agent 的完整指南。涵盖激活/停用、在 Builder 中打开、通过元数据检索和部署将 Agent 移动到新组织（七步流程）、三种 Agent 元数据类型与版本匹配、三种 Manifest 清单模式、以及环境设置/脚本/发布/同步/预览/测试/CI/CD 的常见问题排查。...

首页/ 文章列表/ Agentforce DX Agent 管理指南
📅 2026/7/4 ✍️ ponybai 🏷️ agentforce, salesforce, devops
管理 Agent

激活和停用 Agent

你可以直接从 VS Code 或 CLI 命令激活或停用 Agent。激活 Agent 使其在连接的渠道上对用户可用，停用 Agent 则结束其打开的交互并使所有连接无法访问。

VS Code 方式

  1. 在 VS Code 中打开你的 Salesforce DX 项目
  2. 在资源管理器中导航到 Bot（.bot-meta.xml）或 BotVersion（.botVersion-meta.xml）元数据组件文件
  3. 右键点击 → AFDX: Activate Agent 或 AFDX: Deactivate Agent

CLI 方式

# 激活
sf agent activate --target-org my-org
# 选择要激活的非活跃 Agent；使用标志跳过提示
sf agent activate --api-name MyAgent --version 2

# 停用
sf agent deactivate --target-org my-org

在 Agentforce Builder 中打开 Agent

VS Code：右键 .agent 文件 → AFDX: Open Authoring Bundle in Default Org。CLI：

sf org open agent --api-name Local_Agent_Info
# 或按 Authoring Bundle 打开
sf org open agent --authoring-bundle Local_Agent_Info
# 浏览器选项
sf org open agent --api-name MyAgent --browser chrome --private
激活、停用和打开

使用元数据将 Agent 移到新组织

创建 Agent 后，你可以通过检索和部署其元数据将其移到另一个组织（如从 Sandbox 到 Production）。理解 Agent 的三种元数据类型是成功移动的关键。

元数据移动

三种 Agent 类型及其元数据

类型元数据可编辑？说明
草稿 Agent仅 AiAuthoringBundle✅ 可以修改编辑已创建但尚未提交的 Agent
已提交 AgentAiAuthoringBundle + Bot + BotVersion❌ 已锁定每次提交创建新 BotVersion；保存则创建新 AiAuthoringBundle 版本
传统 Agent仅 Bot + BotVersion✅ 可以编辑覆盖Agent Script 之前的版本，无提交阶段

版本不匹配问题

如果保存次数多于提交次数，AiAuthoringBundle 版本与 Bot/BotVersion 版本将不匹配。例如：11 次保存（AiAuthoringBundle v1-v11），7 次提交（Bot/BotVersion v1-v7）。

找到匹配版本：打开 AiAuthoringBundle 文件夹中的 bundle-meta.xml，查看 <target> 元素，它显示对应的 BotVersion 和 GenAiPlannerBundle 版本。

Agent 元数据类型

七步移动流程

步骤 1：设置本地开发环境 — 安装 Salesforce CLI，授权源和目标组织：sf org login web --alias <org alias>，在两个组织中都启用 Einstein 和 Agentforce。

步骤 2：创建 Salesforce DX 项目 — sf template generate project --name <name> --template standard --manifest，创建带示例 package.xml 清单文件的项目。

步骤 3：在清单文件中定义元数据 — 编辑 manifest/package.xml，指定要检索的元数据。注意：对于大型组织，列出具体元数据类型而非使用 * 通配符以防止超时。

步骤 4（可选）：处理版本不匹配 — 从 bundle-meta.xml 的 target 元素中查找各元数据类型的正确版本号。

步骤 1-4

步骤 5：检索 Agent 元数据 — sf project retrieve start --manifest manifest/package.xml --target-org <org alias>，将所有指定元数据从源组织拉到本地 DX 项目。

步骤 6（可选）：更新草稿 Agent 的用户名 — 检索的元数据包含源组织的用户名，与目标组织不同。在 sfdx-project.json 的 "replacements" 属性中配置字符串替换：

"replacements": [{
  "glob": "**/*-meta.xml",
  "stringToReplace": "sourceuser@salesforce.com",
  "replaceWithEnv": "TARGET_AGENT_USER"
}]

草稿 Agent 可以使用字符串替换；已提交 Agent 不可编辑，需在目标组织创建新版本。

步骤 7：部署到新组织 — sf project deploy start --source-dir force-app --target-org my-target。重要：不要修改检索到的元数据再部署 —— 可能破坏组织。部署后在目标组织配置 Agent 用户和权限，或使用 sf org create agent-user 创建新 Agent 用户。

步骤 5-7

三种清单（Manifest）模式

模式用途示例
所有 Agent（通配符）移动所有内容<members>*</members> 对所有类型
单个 Agent 版本部署特定提交版本BotVersion: NGA_Service_Agent.v2
GenAiPlannerBundle: NGA_Service_Agent_v2
AiAuthoringBundle: NGA_Service_Agent_2
版本不匹配保存 ≠ 提交的计数BotVersion: TestAgent.v7（对应 AiAuthoringBundle TestAgent_9）

命名规则：BotVersion 使用 .vN（如 NGA_Service_Agent.v2），GenAiPlannerBundle 使用 _vN（如 _v2），AiAuthoringBundle 使用 _N（如 _2）。

清单示例

排查 Agentforce DX 常见问题

排查问题

环境设置和 Agent Script 错误

  • Agentforce 未启用 → 设置 → Einstein Setup（开启）+ Agentforce Agents（开启）；Scratch Org 请确保定义文件包含 AgentforceStandardAgents 功能
  • 验证失败 → 检查缩进（类似 YAML 的作用域）、缺少冒号、未声明变量、不支持的表达式。VS Code 扩展在 .agent 文件中提供内联错误高亮
  • 验证通过但预览失败 → 检查 config 块是否设置了有效的 default_agent_user（指向活跃的 Agent 用户）
  • 生成的 .agent 文件为空/极少 → 使用 --spec 标志传入 Agent Spec YAML 文件提供 LLM 上下文；细化 Spec 中的描述
设置、脚本和 Bundle 问题

发布、同步和预览问题

  • 发布后 Agent 未出现在 Builder 中 → 验证正确的组织（sf org display），刷新 Agentforce Builder 页面
  • 实时预览中 Apex/Flow 更改未反映 → 发布只部署 Authoring Bundle，不部署 Apex/Flow。先部署 Apex/Flow：sf project deploy start --metadata "ApexClass:MyActionClass"，再发布
  • 检索未返回所有 Bundle 版本 → 使用通配符：--metadata "AiAuthoringBundle:My_Agent*"
  • 部署失败 "missing required metadata" → 已提交 Agent 需要 AiAuthoringBundle 和 Bot/BotVersion，使用包含所有类型
  • 模拟 vs 实时模式 → 模拟（--simulate-actions）仅测试脚本逻辑；实时（--use-live-actions）测试真实 Apex/Flows，才可使用 Apex Replay Debugger
发布、同步和预览问题

测试和 CI/CD 问题

  • agent test create 失败 → 必须先发布 Agent：sf agent publish authoring-bundle --api-name My_Agent
  • 本地通过但 CI 中失败 → CI 无法使用 Web 登录 → 设置 JWT 授权流程；Agent 未激活 → 在运行测试前添加 sf agent activate；异步测试 → 使用 sf agent test resume --job-id <id> 轮询
  • 指标分数低（连贯性、完整性、简洁性） → 优化 start_agent 块中的系统指令；在子代理定义中添加更具描述性的动作描述；使用 Agent Preview 进行自由对话并检查 Trace 输出
  • 退出码 1 = 执行错误（非断言失败）—— 检查结果输出以区分
测试和 CI/CD 问题

掌握 Agent 管理技能对于将 Agent 从开发推进到生产部署至关重要。始终验证你正在操作正确的组织，在发布后刷新浏览器页面，并使用 VS Code 的 Problems 标签页查看详细错误位置。