一、开始排查 Agentforce 问题（Get Started with Agentforce Troubleshooting）
你上线了一个 Agentforce agent，现在它的表现不符合预期——选错了子 agent、跳过了某个操作、或对同一个问题给出不同的答案。纠正通常不是修 bug。在假设系统坏了之前，请记住：大多数 Agentforce 行为问题源于配置，而非 bug。
完成本单元后，你将能够：
- 识别 Agentforce 行为问题的常见类别；
- 列出六项用于诊断问题的常见排查检查；
- 区分配置问题与数据、集成、运行时问题。
引言：Agent 不是机器人（Agents Aren't Bots）
根本的区别在于：传统的确定性机器人遵循固定的决策树，而 Agentforce agent 使用大语言模型（LLM）推理引擎来判断意图，在遵循人类指令的同时协调操作库来选择下一步。
这种灵活性很强大，但也意味着设置上的小缺口会导致行为上的大意外——不清楚的设置给了模型猜测的空间，而猜测正是不一致的来源。Flow 要么通过要么失败；agent 则是解读（interpret）。所以排查 agent 需要与调试 Flow 或触发器不同的心态，而且大多数问题来自配置，不是 bug。
先识别症状（Spot the Symptoms First）
传统自动化出错时，你通常会得到一条指向确切失败行的错误消息。但 agent 不会这样失败——它们会幻觉（hallucinate），即用听起来合理却不真实的信息填补模糊指令中的空白。
例如，用户问「我需要一张票」，agent 无从得知是支持工单、活动门票还是车票，可能就会猜错。而一个具体的请求则给了它正确行动所需的全部信息。
常见的 agent 排查症状：
- agent 没有调用预期的子 agent 或操作；
- 响应不完整、被截断或被改写；
- 知识引用（citation）不出现；
- agent 意外升级到人工；
- 相同输入产生不一致的输出。
这些问题通常由配置或设置导致，而非系统错误。
起草一个版本（Draft a Version）
开始排查时，在 Agentforce Builder 中创建一个草稿版本（draft），这样你的改动会保存到当前版本而不影响生产。
- 在 Agentforce Builder 中创建草稿版本；
- 点击 Preview，在专用 Developer org 中选择 Live Test 模式——它给出最完整的性能画面（agent 可安全修改占位数据）；
- 用 Set Context 指定匹配真实客户上下文的变量；
- 输入一个典型的客户问题，观察发生了什么。
预览对话后，你可以在 Interaction Summary（交互摘要）中跟踪 agent 的推理与行为——它让你深入交互细节，查看 trace、变量，并得到 Agentforce 的辅助分析。
常见排查检查（Common Troubleshooting Checks）
Interaction Summary 是你的第一站，它展示 agent 采取步骤的高层视图（推理步骤、LLM prompt 结果、每次转换路由到哪个子 agent），还给出整个过程的 AI 生成解释。需要更多细节时，点击任一步骤查看完整 trace 数据。
六项常见检查尤其有用：
- 操作选择：子 agent 选对操作了吗？若否，给子 agent 指令增加更多确定性，检查操作描述与过滤器，或尝试操作链（action chaining）。
- 数据与接地：响应数据是否缺失或不完整？底层 Flow、Apex 类或 prompt 模板是否返回正确数据？对照真实来源，检查 trace 中的 Output Evaluation 与 Output Metrics。
- 路由：Agent Router 是否选了预期子 agent？检查子 agent 之间是否有重叠、名称是否泛化、描述是否模糊。
- 访问与上下文：agent 是否有正确的权限与上下文？检查权限、变量初始化、过滤器条件、依赖变量（如
verified == True）。 - 提示与指令：查找冲突或过于复杂的指令，并简化它们。
- 系统约束：配置没问题但响应仍不对时，检查 token 限制、执行限制或流式问题。
想得到第二意见时，可直接从 Interaction Summary 面板点击 Ask Agentforce 获得 AI 辅助分析。
二、修复配置与数据问题（Fix Configuration and Data Issues）
配置与数据问题是 agent 表现不佳的两个最常见原因，而且通常无需改动任何操作或 prompt 就能修复。本单元解决配置错误（权限、功能未启用）、数据错误（同步延迟、映射损坏）以及知识引用缺失问题。
完成本单元后，你将能够：
- 识别 Agentforce 配置错误的常见原因；
- 解决影响 agent 响应的数据问题；
- 配置知识引用（citation）使其出现在 agent 响应中。
解决配置错误（Resolve Configuration Errors）
配置错误表现为：agent 不执行已配置的工作流、出现 Access Denied 或 Insufficient Privileges 错误、或 UI 中缺少 AI 操作。常见原因是缺少用户或集成权限、Flow Orchestration 或 Agentforce 功能未启用、或对象级访问错误。
- 从权限开始：确认 agent 用户的 profile 或 permission set 包含 agent 通过 Flow、Apex 或 prompt 模板交互的每个对象的最低对象权限。调试 Flow 时，务必以 agent 用户身份运行，以发现可能遗漏的权限问题；Apex 则要把 agent 用到的 Apex 类的安全性扩展到 agent 用户的 profile。
- 然后检查 Salesforce Setup，确认工作流依赖的 Agentforce 功能确实已开启。
最佳实践：把所有的 Agentforce 和 AI 相关用户放进一个集中的 permission set group，保持访问一致、让日后审计更快。
排查数据错误（Troubleshoot Data Errors）
并非每个 Agentforce 问题都与 prompt 或路由有关。有时 agent 配置正确，但喂给它的数据或它对话的系统才是问题所在。
数据错误表现为：响应不完整或不相关、AI 生成的洞察不准确、或因缺少必需值导致自动化失败。常见嫌疑是 Data 360 同步延迟或数据流暂停、字段值为 null 或过时、以及记录之间关系不一致。
- 先检查 Data 360 Data Streams，确认数据源处于活跃且同步状态。
- 然后检查源系统与 Data 360 数据模型之间的字段映射——损坏的映射会悄悄丢弃或改变数据。
- 最后运行 SOQL 查询或报表，直接找出缺失、null 或过时的记录。
最佳实践：设置数据质量规则与告警，让这些问题在到达 agent 之前就暴露出来。
修复缺失的知识引用（Fix Missing Knowledge Citations）
如果 agent 的响应没有显示来源引用，先检查以下设置，别急着认定内容不可用：
- 打开 Answer Questions with Knowledge 操作的配置，确认引用已启用。
- 独立测试该操作，确认它自己能返回引用。
- 确认响应没有在 Flow 后续被覆盖。
- 验证底层 Knowledge 文章已发布、已索引、且 agent 可访问。
三、解决路由、操作与提示问题（Resolve Routing, Action, and Prompting Issues）
本单元涵盖路由、操作与提示问题——这些正是 LLM 解读最容易出错的地方。我们探讨 Agent Router 与分类、配置与变量中显式上下文的重要性、如何诊断缺失的子 agent 或操作、提示最佳实践，以及何时仅靠提示不够。
完成本单元后，你将能够：
- 诊断子 agent 或操作为何未被按预期调用；
- 用确定性机制配置上下文变量；
- 应用提示最佳实践以减少不可预测的行为。
解决路由问题（Resolve Routing Issues）
每个 agent 都有一个特殊的子 agent，叫做 Agent Router，它是每次对话的起始子 agent，也是查找路由问题的好起点。
默认情况下，agent 用 Agent Router 对所有其他子 agent 做分类（classification）——根据用户想做什么和 agent 能做什么来选出最相关的子 agent。转换设置在 Agent Router 的推理操作中，agent 会把最近的对话历史与所有子 agent 的名称和描述对比，选出最佳匹配。
你可以像编辑其他子 agent 一样编辑 Agent Router：添加条件、操作和变量来引导分类；用过滤器（「Make this action available when:」）排除某个子 agent；或移除对某子 agent 的引用，让它只能通过其他子 agent 的转换来访问。
上例中，对话按 verified 变量路由：只有客户已验证（verified 等于 True）时，Order Management、General FAQ 和 Escalation 子 agent 才可用；未验证则路由到 Identify Verification 子 agent。
让上下文显式（上）：配置与数据
Agent 就像团队里的新人——它们不了解事情的来龙去脉。你在给 agent 及其操作写指令、描述、方向时，必须非常具体。
原始字段值没有解释就没有意义。一个原始合并字段 {!Account.Id} 无法告诉推理引擎这个值是什么意思、何时可能为空。把它改写成带标签的形式：Account record Id ({!Account.Id})。对每个 prompt 模板和指令都这样思考，问自己：
- 你给 agent 指定了要扮演的角色吗？
- 你解释了每个字段周围的上下文，而不只是字段本身吗？
- 你考虑过相关字段、对象或列表可能为空的情况吗？
让上下文显式（下）：上下文变量
上下文变量需要格外小心。别假设 agent 会从 prompt 指令中推断出它们——它们在 Agentforce Builder 中不会自动可用。要通过操作输出映射、配置中的变量映射、或 Flow 与结构化赋值逻辑来直接设置。
关键规则：任何依赖某上下文变量的逻辑，都需要该变量在求值之前初始化。跳过这一步，agent 可能行为不可预测，或干脆跳过某个子 agent 或操作。检查你的配置，确认变量在 agent 执行的正确时点被设置。
诊断缺失的子 agent 或操作
如果 agent 跳过了你预期的子 agent 或操作，检查这四个常见原因：
- 子 agent 或操作描述中的提示问题；
- 排除了它的子 agent 或操作过滤器；
- 缺失的上下文变量；
- 权限限制。
先检查子 agent 和操作过滤器——确认它们配置正确，并确保它们依赖的上下文变量在求值前存在。
写 agent 能遵循的提示（Write Prompts the Agent Can Follow）
提示问题是意外 Agentforce 行为的最常见原因。使用这些提示最佳实践：
- 划清边界：让子 agent 和指令的边界分明。每个子 agent 应映射到特定角色或任务，目的与范围要显式且不重叠。两个子 agent 指令相似时，agent 就会猜，导致错误。
- 明确清晰：在子 agent 和操作描述中使用无歧义语言，确保指令不冲突。解决代词和术语歧义——「mine」或「my」是常见的困惑来源，「my accounts」是指用户拥有的记录，还是用户作为相关联系人的记录？别让 agent 去猜。
- 避免推断：不要依赖 LLM 去推断业务规则，直接陈述它们。
- 定义范围：清楚定义操作何时应该、何时不应该运行。
- 说明输出：清晰结构化并描述操作输出，指定你想要的语气、简洁度和格式。
收紧描述和指令能解决大量「agent 没按我说的做」的问题。
提示的局限（The Limits of Prompting）
如果所有指令调整都无法产生理想结果，考虑在指令中加入程序化逻辑，以保证更一致的输出。
Agent Script 的美妙之处在于它提供混合推理——既享受程序化逻辑的可预测性，又保留 LLM 的推理能力。用它来强制执行子 agent 的必需工作流，并确定性地管理变量，消除纯提示无法根除的猜测。
四、排查接地、限制与常见错误（Troubleshoot Grounding, Limits, and Common Errors）
本单元涵盖接地与系统限制：修复缺失引用（含被隐藏的 URL）、缓解 token 与字符限制导致的截断响应、解决流式与改写响应，并识别 401 到 500 的常见错误码，以及每轮用户 8 次 LLM 调用的上限。
完成本单元后，你将能够：
- 解决缺失引用与 Knowledge 接地问题；
- 缓解由系统限制导致的截断响应与流式错误；
- 识别常见 Agentforce 错误码及其修复方法。
修复缺失引用（Fix Missing Citations）
只有当 Knowledge 操作返回了引用、且该操作启用了引用时，引用才会出现。检查操作配置、独立测试它、确认响应没有在下游被覆盖、并确保底层文章已发布、已索引、且 agent 可访问。
如果引用仍然缺失：
- 打开 Knowledge 操作配置，确认引用已启用；
- 独立测试操作，确认它自己能返回引用；
- 确保 Flow 后续没有任何东西在引用附加后覆盖响应；
- 验证 Knowledge 文章已发布、已索引、agent 可访问。
有些 URL 因安全原因被隐藏。要修复，在 Setup 中添加 Trusted URLs，并确认 URL 由某个操作返回或已显式允许。
缓解截断响应（Mitigate Truncated Responses）
Agentforce 有真实的限制：LLM 响应约 2,048 tokens，操作输出约 65,000 字符。触到上限，响应就会在句中截断，或操作结果返回不完整。
减少截断响应的方法：
- 用 Show in Conversation，而不是直接嵌入大输出；
- 避免在操作中返回不必要的字段；
- 把复杂请求拆成多个步骤；
- 把大数据存到对象里，通过操作引用，而不是一次性全传。
解决流式与改写响应
一个出现后又变化或消失的响应，可能触发了接地性检查（groundedness check）。让指令准确且具体，避免宽泛或模糊的提示，把响应接地到 Knowledge 或结构化数据。
对于一般的流式错误：检查 prompt 模板是否有 JSON 密集输出等严格格式、简化嵌套指令、并减少大型操作输出。接地与简洁能保持响应稳定。
识别常见错误码（Recognize Common Error Codes）
识别这些常见错误码：
- 401 Unauthorized——刷新 OAuth token。
- 403 Forbidden——更新用户或集成权限。
- 404 Not Found——验证端点 URL 或记录 ID。
- 429 Too Many Requests——添加重试与退避（backoff）逻辑。
- 500 Internal Server Error——查看日志或联系 Salesforce Support。
另外，agent 每轮用户最多可进行 8 次 LLM 调用。触到上限时，查找重复的操作失败、验证循环或过于复杂的工作流，并简化子 agent 流程。
五、解决集成与运行时错误（Resolve Integration and Runtime Errors）
本单元涵盖剩下的两类：集成错误（agent 无法访问 AWS、Slack 或自定义 API 等外部系统）与运行时错误（进程中途停止、异常、循环）。我们逐一讲清症状、原因与分步排查，以及最佳实践。
完成本单元后，你将能够：
- 识别集成错误的症状与原因；
- 识别运行时错误的症状与原因；
- 为每类问题应用正确的排查步骤与最佳实践。
解决集成错误（Resolve Integration Errors）
集成错误看起来不同：agent 无法访问 AWS、Slack 或自定义 API 等外部系统，出现 401 Unauthorized 或 500 Internal Server Error 等错误，还有响应缓慢或超时。常见原因是 OAuth token 过期或 API key 无效、端点 URL 变更但 Salesforce 未更新、或 Named Credential 配置错误。
- 验证 Named Credentials：在 Setup | Security | Named Credentials 中确认它们活跃且指向正确端点。
- 查看 API 日志：在 Event Monitoring | API Usage Logs 中查看哪些调用失败、返回了什么 HTTP 状态。
- 续期认证 token：刷新 OAuth token 或重新授权 connected app。
- 在 Salesforce 之外测试连接：用 Postman 等工具，判断问题在端点本身还是 Salesforce 一侧。
最佳实践：把重试逻辑与监控告警直接构建进 Flow，让瞬时故障不至于变成工单；并且始终先在沙盒中复现问题，别在生产环境实时调试数据或集成问题。
解决运行时错误（Resolve Runtime Errors）
运行时错误包括：进程在完成前停止、Null Pointer Exception 等异常、或永不结束的自动化循环。常见原因是 Flow 逻辑错误或变量未初始化、递归触发器或循环依赖、或超出 governor limits（Salesforce 允许单事务使用的最大资源）。
按以下步骤排查：
- 在 Debug Mode 中逐步执行 Flow，找到失败的节点或变量；
- 查看 Apex debug 日志的堆栈追踪；
- 检查 governor limit 使用情况（SOQL 查询、DML 操作、CPU 时间）；
- 把复杂 Flow 重构成更小的可复用 subflow。
最佳实践：始终配置 Fault Paths，让 Flow 能优雅地处理运行时异常。
文章来源：Trailhead - Agent Behavior Troubleshooting in Agentforce