激活和停用 Agent
你可以直接从 VS Code 或 CLI 命令激活或停用 Agent。激活 Agent 使其在连接的渠道上对用户可用，停用 Agent 则结束其打开的交互并使所有连接无法访问。
VS Code 方式
在 VS Code 中打开你的 Salesforce DX 项目
在资源管理器中导航到 Bot（
.bot-meta.xml）或 BotVersion（.botVersion-meta.xml）元数据组件文件右键点击 → 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 版本。
七步移动流程
步骤 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 元素中查找各元数据类型的正确版本号。
步骤 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 用户。
三种清单（Manifest）模式
模式用途示例
所有 Agent（通配符）移动所有内容<members>*</members> 对所有类型
单个 Agent 版本部署特定提交版本BotVersion: NGA_Service_Agent.v2GenAiPlannerBundle: NGA_Service_Agent_v2AiAuthoringBundle: 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 中的描述
发布、同步和预览问题
发布后 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 = 执行错误（非断言失败）—— 检查结果输出以区分
掌握 Agent 管理技能对于将 Agent 从开发推进到生产部署至关重要。始终验证你正在操作正确的组织，在发布后刷新浏览器页面，并使用 VS Code 的 Problems 标签页查看详细错误位置。
