Agentforce DX Agent 管理指南

使用 Agentforce DX 管理 Agent

使用 Agentforce DX，你可以直接从 VS Code 或 CLI 命令激活、停用和在 Builder 中打开 Agent。

激活、停用与在 Builder 中打开

激活 / 停用 Agent

激活使 Agent 在连接的通道上对用户可用。停用则结束其所有开放交互，使其对所有连接不可达。

VS Code：右键 .bot-meta.xml 或 .botVersion-meta.xml → AFDX: Activate/Deactivate Agent

# CLI 激活（交互式选择）
sf agent activate --target-org my-org

# 直接激活（指定版本和 API 名称）
sf agent activate --api-name MyAgent --version 2 --target-org my-org

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

在 Builder 中打开 Agent

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

# 按 API 名称打开
sf org open agent --api-name Local_Agent_Info

# 按 Authoring Bundle API 名称打开
sf org open agent --authoring-bundle Local_Agent_Info

# 指定版本、浏览器
sf org open agent --api-name MyAgent --version 2 --browser chrome --private

使用元数据将 Agent 迁移到新 Org

创建 Agent 后，可以通过检索和部署元数据将其迁移到另一个 Org（如从 Sandbox 到 Production）。

理解 Agent 元数据类型

Agent 类型	元数据表示	可编辑
Draft Agent（草稿）	AiAuthoringBundle	是
Committed Agent（已提交）	AiAuthoringBundle + Bot + BotVersion	否
Legacy Agent（传统）	Bot + BotVersion	n/a

关键概念：Draft（未提交）Agent 和版本仅用 AiAuthoringBundle 表示。Committed Agent 需要 AiAuthoringBundle + Bot/BotVersion。Legacy Agent 没有提交阶段。

迁移步骤 1-4：环境准备到版本匹配

Step 1：设置本地环境 — 安装 Salesforce CLI、授权源和目标 Org（sf org login web --alias org-alias）、确保两个 Org 都启用了 Einstein 和 Agentforce。

Step 2：创建 DX 项目 — sf template generate project --name myproject --template standard --manifest

Step 3：定义 Manifest — 编辑 manifest/package.xml。关键元数据类型：Bot（Agent 顶层）、BotVersion（特定版本）、AiAuthoringBundle（Agent Script + 元数据）、GenAiPlannerBundle（推理引擎）、GenAiPlugin/GenAiFunction（子代理/动作）、ApexClass/Flow/GenAiPromptTemplate。

Step 4：处理版本不匹配 — 当保存次数 > 提交次数时，AiAuthoringBundle 版本号可能与 Bot/BotVersion 不匹配。在 bundle-meta.xml 的 target 元数据中找到正确的匹配版本。

迁移步骤 5-7：检索到部署

Step 5：检索元数据 — sf project retrieve start --manifest manifest/package.xml --target-org source-org

Step 6：更新用户名（可选） — 使用 string replacement 将源 Org Agent 用户名替换为目标 Org 的用户名。在 sfdx-project.json 中配置 replacements，用环境变量 TARGET_AGENT_USER 替换。Draft Agent 可自动替换；Committed Agent 需手动配置。

Step 7：部署 — sf project deploy start --source-dir force-app --target-org my-target。切勿修改检索到的元数据后上传——可能损坏 Org。部署后需分配 Agent 用户和权限。

提示：Committed Agent 不可编辑。如需更改，先创建新版本再添加用户。

Manifest 示例总结

Manifest 类型	适用场景	注意事项
All Agents	检索所有 Agent（含 Legacy）	用 * 通配符；大型 Org 建议列出具体类型而非通配
Single Agent Version	检索单个 Agent 的特定版本 + 依赖	部署单版本前必须先部署完整 Agent；用 NGA_Service_Agent.v2 格式
Mismatched Versions	AuthoringBundle 版本号 ≠ Bot 版本号	用 bundle-meta.xml 的 target 找正确版本

Agentforce DX 问题排查

环境设置 + Agent Script + Authoring Bundle 问题

Agentforce 未启用：Setup > Einstein Setup 启用 Einstein；Setup > Agentforce Agents 启用 Agentforce。Scratch Org 确保 def 文件含 AgentforceStandardAgents feature。

Agent Script 验证失败：常见原因：缩进不对齐、块名后缺冒号、引用未声明变量、不支持的表达式。VS Code Agent Script Language 扩展提供内联错误高亮。

验证通过但预览失败：检查 config 块的 default_agent_user 是否为开发 Org 中的有效活跃 Agent 用户。

生成的 .agent 文件内容过少：使用 --spec flag 传入 Agent Spec 文件。无 Spec 时命令只生成默认模板。

Spec 细节模糊：Spec 质量影响生成结果。提供清晰描述、具体业务流程、详细动作说明、示例用户场景后重新生成。

误用 agent create：agent create 创建不基于 Agent Script 的传统 Agent，部分 DX 命令不兼容。改用 Authoring Bundle 工作流。

发布 + 同步 + 预览问题

发布成功但 Builder 中看不到 Agent：sf org display 确认 Org；刷新 Builder 页面。

Apex/Flow 变更在 Live Preview 中未生效：发布 Bundle 不会自动部署 Apex/Flow。先 sf project deploy start --metadata "ApexClass:MyClass" 再发布。

拉取不到所有 Bundle 版本：使用通配符 "AiAuthoringBundle:My_Agent*"，否则只拉取未版本化的 draft bundle。

部署失败 missing required metadata：Committed Agent 需同时有 AiAuthoringBundle 和 Bot/BotVersion。使用包含所有必要类型的完整 manifest。

Simulated vs Live 模式选择：Simulated（动作未实现时、测试纯脚本逻辑时）；Live（Apex/Flow/Prompt 已部署时使用，需配合 Apex Replay Debugger 调试）。Apex 断点只在 Live 模式生效。

多个预览会话冲突：sf agent preview sessions --api-name My_Agent 列出 → sf agent preview send --session-id <id> 指定会话 → sf agent preview stop --session-id <id> 停用多余会话。

测试与 CI/CD 问题

agent test create 报 Agent 不存在：必须先发布 Agent 到 Org 才能创建测试。

本地测试通过但 CI 失败：检查：CI 环境是否使用 JWT 授权（Web login 不可用）；Agent 是否已激活；异步测试是否用 --wait 或 agent test resume 轮询结果（注意 exit code 1 表示执行错误而非断言失败）。

Metric 分数偏低：通常因 Agent 指令或动作描述过于模糊。优化 start_agent 系统指令、添加更详细的子代理动作描述、使用 Agent Preview + Trace 分析推理偏差。

掌握 Agent 生命周期管理是生产级 Agent 部署的关键。建议配合 CI/CD 流水线实现自动化的激活-测试-部署流程。