文档中心

Appearance

✨费用中心控制台

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

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

智能体实例一直待启动 ​

警告

仅限 AgentWorks 管理控制台

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

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

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

Playground 无法连接 ​

  • 确认实例为 运行中。
  • 刷新 Playground 并观察连接状态。
  • 检查浏览器网络请求。
  • 检查智能体实例是否刚被重新配置。
  • 如果实例因平台维护或故障中断，等待状态恢复为 运行中 后重新建立会话。

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 未激活或资源读取失败 ​

  1. 打开来源智能体模板的 插件 页签，确认存在目标技能组。
  2. 检查技能组选择了目标 Skill 和预期版本。
  3. 创建或更新测试智能体实例，确保它使用最新智能体模板配置。
  4. 使用必须依赖该 Skill 的输入，并在 Trace 中确认发生了 Skill 激活。
  5. 如果任务需要相关文件，确认 Trace 中发生了资源读取，并核对相对路径与所选版本中的文件路径一致。
  6. 使用目标版本独有的短语或样例，确认没有解析到 latest 或其他版本。

Skill 中的脚本不会因为资源被读取而自动执行，Skill 文件也不会自动进入沙箱。任务还需要沙箱执行时，分别检查两条路径：

  1. 在 Trace 中确认智能体激活了目标 Skill，并读取了预期版本的资源。
  2. 确认智能体模板已经关联所需沙箱模板或实例，并且智能体实例使用最新配置。
  3. 在 Playground 中确认运行时可以使用预期的沙箱工具。
  4. 确认沙箱本身具备任务所需文件、运行时和依赖。
  5. 使用低风险输入完成一次显式执行，并在 Trace 和沙箱运行记录中核对工具调用与输出。

如果 Skill 使用正常但沙箱执行失败，应从沙箱工具、文件、运行时、依赖和网络限制继续排查。不要把 Skill 资源读取当作沙箱文件准备或脚本执行的证明。

MCP 工具不可用 ​

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

知识库回答缺少资料 ​

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

沙箱执行失败 ​

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

渠道用户无法初始化 ​

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

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

渠道中显示失败信息 ​

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

找到对应 Trace ​

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

没有对应 Trace ​

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

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

WebSocket 绑定目标不可选 ​

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

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

  1. 确认已对渠道账号选择 启用。
  2. 打开 凭证管理 的 WebSocket Token。
  3. 检查客户端使用的 Token 是否仍为停用状态。停用渠道账号会停用该账号的所有 WebSocket Token，重新启用账号不会自动恢复它们。
  4. 启用或替换仍需使用的 Token，让客户端重新连接并验证鉴权、心跳和消息往返。

渠道账号无法删除 ​

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

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

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

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