文档中心

Appearance

控制台

排查智能体实例运行问题 ​

排查智能体开发服务平台（AgentWorks）的运行问题时，从用户看到的症状开始，按智能体实例、访问方式、能力资源和外部服务逐层检查。

调用后智能体实例仍未启动 ​

重要

仅限 AgentWorks 管理控制台

修改租户能力开关，或者确认和调整租户的沙箱规格分配，只能在独立的 AgentWorks 管理控制台 完成。AgentWorks 控制台用户可以检查页面上是否出现预期选项；缺少选项时，请让管理员检查租户能力和沙箱资源分配。

创建实例后，打开 Playground，或通过已开启的 API、渠道发起一次无副作用的测试调用。平台会按需启动实例；调用失败，并且刷新实例列表后仍显示 待启动 时，再按以下步骤排查。

  1. 检查来源智能体模板是否仍存在。
  2. 检查模型凭证和模型是否可用。
  3. 检查所有必填实例参数。
  4. 检查租户是否允许所引用能力。
  5. 检查沙箱规格和环境是否分配给租户。
  6. 检查 MCP、知识库组和技能组实例。
  7. 向部署管理员提供实例 ID、发生时间和页面错误信息，请其继续检查平台日志。

先定位第一个实例的创建或启动错误，再决定是否重新创建。

Playground 无法连接 ​

  • 首次连接可能需要启动实例，请稍等片刻后刷新 Playground 并观察连接状态。
  • 刷新实例列表；调用后仍显示 待启动 时，按调用后智能体实例仍未启动继续检查。
  • 检查浏览器网络请求。
  • 检查智能体实例是否刚被重新配置。
  • 如果实例因平台维护或故障中断，在服务恢复后重新连接 Playground，再发送一次无副作用的测试请求。

微应用界面未加载或操作失败 ​

  1. 确认智能体实例已经采用最新智能体模板配置。
  2. 打开来源智能体模板的 插件配置，确认只有目标沙箱选择了 微应用。
  3. 确认目标沙箱使用已经准备并验证的兼容环境。选择 微应用 不会把普通沙箱转换成微应用环境。
  4. 检查沙箱实例能否正常启动。沙箱工具也无法使用时，继续按沙箱执行失败排查规格、环境、网络和审批。
  5. 刷新 Playground，再使用虚构数据执行一次可撤销操作。
  6. 问题仍然存在时，记录智能体实例 ID、沙箱资源 ID、发生时间和界面错误信息，再联系当前环境的技术支持人员。

如果目标插件选择现有沙箱实例，排查和重启可能影响所有引用方。确认引用范围后再变更共享实例。

API 调用返回未授权 ​

  • 确认使用 dbg_ 或 agt_，不是 wst_。
  • 确认 Token 属于目标智能体实例。
  • 确认 API 调用状态 已开启。
  • 检查 Token 是否过期、停用或已经重新生成。
  • 如果刚重新开启 API 调用状态，检查对应 Agent API Token 是否仍为停用；重新开启调用不会自动启用它。
  • 检查 Authorization 头没有被代理移除。

即使 HTTP 状态为 200，也要检查 JSON 响应中的 http_status_code 和 data.reason。

同一会话无法继续 ​

  • stream_in_progress：等待当前流 done，不要并发调用。
  • pending_interrupt：先发送 interrupt_response。
  • not_found：当前调用任务的状态已经无法查询，但这不表示会话历史已被删除。先核对外部系统是否已经产生业务结果，再根据业务需要继续原会话或创建新会话。
  • 流异常断开：查询调用任务状态，再决定响应、重置或重试。

调用任务完成、失败或被重置，都不等于 API 会话已经结束。参见管理 API 会话、调用任务和中断。

长会话变慢或接近上下文上限 ​

  1. 判断后续任务是否仍需参考原对话。不需要时，API 调用不发送原 session_id；渠道单聊使用 /session new。
  2. 需要继续原会话时，打开智能体模板的 压缩配置，确认 启用压缩 已开启，并优先使用推荐的 使用新版压缩。旧版压缩（兼容模式）已弃用，不推荐用于新配置；仅在迁移或排查现有旧版配置时选择可调用的压缩模型。
  3. 智能体模板修改后，编辑并保存目标智能体实例，使实例采用更新后的配置；切换压缩方式后行为仍未变化时，重启测试实例再验证。
  4. 排查旧版压缩时，如果仍在触发前接近上下文上限，降低 压缩模型最大长度或 压缩阈值。使用新版压缩时没有这些字段；两种方式都应减少不必要的大段工具返回。
  5. 使用固定长会话比较事实保留、工具连续性、延迟和 Token 用量；每次只修改一个参数。

上下文压缩默认关闭，也不是会话过期或历史删除功能。需要跨会话保留稳定事实时，使用记忆库或业务系统；需要按期限清理历史时，按目标环境的数据保留和清理流程处理。参见在长会话中启用压缩。

已创建能力资源，但智能体没有使用 ​

  1. 打开来源智能体模板的 插件 页签。
  2. 确认列表中存在预期插件，并核对类型、名称和资源 ID。
  3. 如果缺少关联，编辑智能体模板，在 插件配置 中单击 添加插件，选择目标模板或实例并保存。
  4. 如果智能体模板已经更新，编辑并保存目标智能体实例，使其使用最新配置。
  5. 发送能明确触发该能力的测试输入，并在 Trace 或相应运行记录中确认实际使用的资源。

能力资源存在、插件关联已经保存和运行时实际使用是三个不同检查点，应依次确认。

排查 Skill 选择、版本、资源和执行 ​

先在 Trace 中判断问题停在哪个阶段，再检查对应配置。没有选择 Skill、使用错误版本、无法读取相关资源和缺少执行能力是四类不同问题。

Trace 中没有 Skill 激活 ​

  1. 打开来源智能体模板的 插件 页签，确认存在目标技能组。
  2. 检查技能组选择了目标 Skill 和预期版本。
  3. 创建或更新测试智能体实例，确保它使用最新智能体模板配置。
  4. 检查目标 Skill 的名称和描述是否明确说明适用任务，并确认没有与同一技能组中的其他 Skill 高度重叠。
  5. 使用必须依赖该 Skill 才能正确完成的输入进行测试。
  6. 在当前默认 Skill 提供方下，检查 Trace 中是否出现 default.activate_skills。

使用不会触发目标 Skill 的输入再次测试，确认智能体不会在无关请求中激活它。

Skill 激活后使用了错误版本 ​

  1. 检查技能组为目标 Skill 选择的是明确版本还是 latest。
  2. 需要验证特定版本时，选择明确版本号，不要依赖可能变化的 latest。
  3. 创建或更新测试智能体实例，使版本选择进入最新运行配置。
  4. 使用只存在于目标版本中的短语、步骤或样例测试。
  5. 在 Trace 和最终结果中确认实际内容来自目标版本。

Skill 已激活但资源读取失败 ​

  1. 确认所选版本的 SKILL.md 明确引用了需要读取的文件。
  2. 核对相对路径、文件名大小写和目录层级是否与所选版本中的文件一致。
  3. 在当前默认 Skill 提供方下，检查 Trace 中是否出现 default.read_skill_resource，并核对请求的相对路径。
  4. 如果 SKILL.md 已经包含完成任务所需的全部信息，不应仅因没有资源读取调用就判断 Skill 失败。

Skill 内容已加载但操作没有执行 ​

Skill 中的脚本不会因为资源被读取或挂载而自动执行。任务还需要执行命令、脚本或外部操作时：

  1. 确定应由沙箱、MCP、平台工具包还是用户工具包执行目标操作。

  2. 确认智能体模板已经关联所需能力，并且智能体实例使用最新配置。

  3. 需要沙箱执行时，按关联方式检查文件：

    • 同时使用技能组和 沙箱 - 模板：列出 /skills，找到目标 Skill 和所选版本中的文件。
    • 使用 沙箱 - 实例：先核对是否有需要不同 Skill 集合的智能体复用该实例。这种组合不受支持，应改用 沙箱 - 模板。所有引用方使用相同 Skill 集合时，再确认所需文件已经在共享实例中另行准备。

  4. 确认沙箱具备所需运行时和依赖，并把输出写到可写工作目录。

  5. 使用低风险输入显式调用预期工具或命令。

  6. 在 Trace 和相应执行记录中分别核对工具调用与输出。

Skill 或技能组的版本选择刚发生变化时，先更新或重新创建非生产智能体实例并再次核对实际文件，再更新生产实例。

如果 Skill 使用正常但目标操作失败，应从相应工具的身份、权限、文件、运行时、依赖或网络限制继续排查。不要把 Skill 资源读取当作操作已经执行的证明。参见为 Skill 配置执行能力。

MCP 工具不可用 ​

  1. 在 MCP 实例中选择 测试连接。
  2. 检查 Server URL、TLS、Headers和 超时（秒）。
  3. 查看 工具列表。
  4. 检查智能体模板是否引用正确的 MCP 模板或实例。
  5. 检查智能体模板的工具权限规则、默认行为和待处理中断。
  6. 检查外部 MCP Server 日志。

沙箱回收后 MCP 工具返回 unknown tool ​

已关联沙箱的 MCP 工具连接在沙箱被回收并重新创建后，复用原 MCP 会话可能返回 unknown tool。看到平台诊断信息后，请继续按以下步骤重新建立工具连接并验证恢复结果。

  1. 停止继续使用原工具连接，不要盲目重试可能产生副作用的操作。
  2. 记录智能体实例 ID、沙箱资源 ID、工具名称、会话或调用任务 ID、发生时间和原始错误。
  3. 重新初始化或重新建立工具连接。只有已经确认当前接入路径会为新建会话建立全新工具连接时，才把新建会话作为恢复方式；否则重启非生产测试实例后再次加载工具列表。无法确认或仍然失败时，停止调用并联系平台支持。
  4. 在 Trace、沙箱运行记录 和 MCP Server 日志中核对原调用是否已经产生副作用。
  5. 使用无副作用的只读调用确认工具重新可用，再恢复生产请求。

不要把观察到的回收间隔写成固定 SLA。问题反复出现时，把上述关联 ID 和时间交给平台支持定位。

知识库回答缺少资料 ​

  • 确认资料已进入目标集合。
  • 检查最近入库任务并选择 日志。
  • 确认知识库组包含目标集合。
  • 检查智能体实例实际引用的组实例。
  • 调整并测试 top_k。
  • 用 Trace 确认是否发生检索。

沙箱执行失败 ​

  • 检查 沙箱运行记录。
  • 确认规格和环境匹配 Docker 或虚拟机类型。
  • 检查资源、超时和空闲回收。
  • 检查环境变量实例参数。
  • 检查 DNS、私网访问和带宽策略。
  • 检查工具调用是否被权限规则中断。

沙箱中出现其他用户或任务的文件和状态 ​

如果看到来源不明的文件、文件被覆盖或删除、非预期的 Skill，或者某个任务的资源占用、重启和清理影响其他任务，请检查是否误用了共享沙箱。

  1. 确认受影响请求实际进入的智能体实例。
  2. 分别核对这些智能体实例关联的沙箱类型和实际资源 ID；再到来源智能体模板的 插件 页签确认选择的是沙箱模板还是现有沙箱实例。进入同一个智能体实例，或不同智能体实例显示同一个实际沙箱资源 ID，表示这些请求使用同一个沙箱。
  3. 如果不是有意共享，把智能体模板改为选择 沙箱 - 模板，再创建或更新需要隔离的智能体实例。需要按渠道用户分开时，使用模板绑定和 /init。
  4. 使用两个测试用户或智能体实例分别创建名称不同的测试文件，并核对沙箱资源 ID。预期隔离时，资源 ID 应不同，且一方不能读取或修改另一方的测试文件。
  5. 如果确实需要共享，分别使用约定的工作目录和文件名，避免并发修改同一内容，并统一安排更新、重启和清理。这样只能减少冲突，不能把共享实例变成独立隔离环境。

参见选择沙箱模板或实例。

渠道用户无法初始化 ​

  • 确认渠道账号使用模板绑定。
  • 使用 /init 或 /init KEY=VALUE。
  • 检查缺失的模板参数。
  • 检查 禁用单聊 是否已开启。它优先于单聊允许名单。
  • 检查用户和群聊允许名单。
  • 检查是否已有用户绑定。
  • 检查动态创建的智能体实例是否进入运行状态。

QQ 渠道账号只提供单聊设置，因此启用禁用单聊会阻止 QQ 用户发送普通消息和 /init。飞书用户从单聊初始化时也需要保持该选项关闭。

渠道中显示失败信息 ​

记录失败消息对应的渠道账号、用户、发送时间和完整错误信息。随后在绑定的智能体实例中查找同一时间的 Trace。不要连续重复提交可能产生副作用的操作。

找到对应 Trace ​

  1. 确认失败发生在模型、工具、外部服务还是权限审批。
  2. 飞书中显示同一轮响应的多个工具调用时，分别核对每个调用的工具名称、参数、状态和结果。不要把一个失败项当作全部调用都失败，也不要仅根据卡片同时显示多项就判断工具同时执行。
  3. 涉及子代理时，打开 后台任务。如果状态为 等待审批，在主智能体所在飞书会话中处理审批卡片。
  4. 根据失败位置检查模型凭证、工具连接、审批规则或外部服务。
  5. 修复问题后，使用固定输入重新测试，并确认渠道回复、Trace 和后台任务结果一致。

没有对应 Trace ​

  1. 打开 渠道账号，确认目标账号已经启用并处于在线状态。
  2. 检查账号的绑定模式和绑定目标。实例绑定应指向仍然存在且可以运行的智能体实例。
  3. 使用模板绑定时，在 用户绑定 中确认该用户已经绑定到有效智能体实例；尚未初始化时，让用户发送 /init。
  4. 修复状态或绑定后，发送不会修改业务数据的固定测试消息，并再次检查是否产生 Trace。
  5. 仍然失败时，把渠道账号、用户、发送时间和完整错误信息交给管理员。管理员可以据此检查渠道接入和消息处理状态。

渠道已经显示失败并不表示智能体实例停止运行。是否继续接收消息取决于实例、渠道账号和接入开关的状态。

飞书审批卡片点击后没有继续 ​

点击允许或拒绝后，卡片仍停留在等待状态且没有最终回复时，不要再次点击，也不要重发原请求。工具可能尚未执行，也可能已经执行但渠道没有返回结果；先把本次结果视为无法确定。

  1. 记录渠道账号、会话、审批卡片中的工具名称和发生时间，不要记录凭证。
  2. 在绑定的智能体实例中查找同一时间的 Trace，并在 MCP 服务或实际写入的业务系统中核对是否产生结果或副作用。
  3. 会话一直无法处理新消息时，使用 /session fix 恢复后续消息处理。旧审批仍需按上一步通过 Trace、MCP 服务或实际写入的业务系统核对结果。
  4. 使用无副作用消息确认会话恢复后，停止操作旧卡片并联系平台支持。

在一项允许测试和一项拒绝测试都得到明确最终结果之前，不要把该飞书账号用于生产审批。

未知斜杠指令没有透传 ​

开启 未命中的斜杠指令透传给 Agent后，使用无副作用的虚构命令检查 Agent 回复和新的 Trace。开关显示为开启但没有这两项结果时：

  1. 把开关恢复为关闭，确认未知命令重新返回 /help。
  2. 不要继续发送可能触发模型、工具或外部写入的未知命令。
  3. 记录渠道账号、发生时间和测试命令名称，联系平台支持检查账号配置是否已经应用。

飞书消息进入非目标智能体 ​

如果 /init、用户绑定或普通回复指向非目标智能体，先检查是否有多个已启用的飞书渠道账号使用同一个 App ID。

  1. 停止向该飞书应用发送测试或业务消息。
  2. 只保留一个目标渠道账号启用，停用复用同一 App ID 的其他账号，刷新后确认它们保持离线。无法确认旧连接已经停止时，先联系平台支持。
  3. 确认旧连接已经停止后，从保留账号发送 /help 和一条无副作用消息，核对回复、用户绑定和智能体实例一致。
  4. 仍然进入非目标智能体时，停用相关账号并联系平台支持；不要反复发送 /init，以免创建更多非预期实例或用户绑定。

WebSocket 绑定目标不可选 ​

  • 在 渠道账号 中切换到 WebSocket，使用 绑定 Agent 查找已经使用该目标的账号。
  • 已停用的 WebSocket 渠道账号仍保留绑定目标。需要继续使用该目标时，重新使用现有账号；需要替换账号时，先选择 停用，再选择 删除旧账号。
  • 多个客户端连接同一个绑定目标时，在同一个渠道账号下创建多个 WebSocket Token，不要为同一个目标重复创建渠道账号。

需要重新规划渠道账号或为多个客户端分别签发 Token 时，参见创建 WebSocket 渠道账号和为客户端创建 Token。

重新启用 WebSocket 账号后仍无法连接 ​

  1. 确认已对渠道账号选择 启用。
  2. 打开 凭证管理 的 WebSocket Token。
  3. 刷新 Token 列表，逐个检查绑定到该账号的 Token 状态。渠道账号的停用或重新启用不能替代这项核对。
  4. 只启用或替换仍需使用的 Token，并停用其他仍显示为启用的 Token；让客户端重新连接并验证鉴权、心跳和消息往返。

仍然无法连接时，按连接并完成鉴权核对所用鉴权路径，再根据 WebSocket 错误处理返回的 HTTP 状态、错误帧或 Close Code。修复后重新验证消息往返。

渠道账号无法删除 ​

先选择 停用，确认状态变为 已停用，再选择 删除。如果账号刚完成停用，刷新渠道账号列表或详情页后再确认状态。删除前还应盘点用户绑定、智能体实例、客户端配置和仍在使用的 Token。

修改智能体模板后结果没有变化 ​

检查智能体实例列表是否显示 智能体模板更新，实例需手动更新。编辑并保存目标智能体实例，再重新测试。

修改智能体模板或能力模板后，请逐个更新并验证正在运行的智能体实例。