跳到主要内容

代理循环 (Clawdbot)

代理循环（Agentic loop）是代理的一次完整“真实”运行：输入 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。它是将消息转化为动作和最终回复的权威路径，同时保持会话状态的一致性。

在 Clawdbot 中，循环是每个会话的一次单一、序列化的运行，它在模型思考、调用工具和流式传输输出时发出生命周期和流事件。本篇文档将解释该权威循环是如何端到端连接的。

入口点​

  • 网关 RPC：agent 和 agent.wait。
  • CLI：agent 命令。

工作原理（高级别）​

  1. agent RPC 校验参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回 { runId, acceptedAt }。
  2. agentCommand 运行代理：
    • 解析模型 + 思考/详细程度默认值
    • 加载技能快照
    • 调用 runEmbeddedPiAgent (pi-agent-core 运行时)
    • 如果嵌入式循环未发出 生命周期结束/错误，则发出该事件
  3. runEmbeddedPiAgent：
    • 通过每个会话 + 全局队列对运行进行序列化
    • 解析模型 + 身份验证配置文件并构建 pi 会话
    • 订阅 pi 事件并流式传输助手/工具增量
    • 强制执行超时 -> 如果超过则中止运行
    • 返回有效载荷 + 用量元数据
  4. subscribeEmbeddedPiSession 将 pi-agent-core 事件桥接到 Clawdbot agent 流：
    • 工具事件 => stream: "tool"
    • 助手增量 => stream: "assistant"
    • 生命周期事件 => stream: "lifecycle" (phase: "start" | "end" | "error")
  5. agent.wait 使用 waitForAgentJob：
    • 等待 runId 的 生命周期结束/错误
    • 返回 { status: ok|error|timeout, startedAt, endedAt, error? }

队列 + 并发​

  • 运行按会话键（会话通道）序列化，并可选地通过全局通道。
  • 这可以防止工具/会话竞争，并保持会话历史的一致性。
  • 聊天频道可以选择馈送此通道系统的队列模式（收集/引导/跟进）。 参见 命令队列。

会话 + 工作区准备​

  • 解析并创建工作区；沙箱化运行可能会重定向到沙箱工作区根目录。
  • 加载技能（或从快照中重用）并注入到环境变量和提示词中。
  • 解析引导/上下文文件并将其注入到系统提示词报告中。
  • 获取会话写入锁；在流式传输之前打开并准备 SessionManager。

提示词组装 + 系统提示词​

  • 系统提示词由 Clawdbot 基础提示词、技能提示词、引导上下文和单次运行覆盖项构建。
  • 强制执行特定模型的限制和压缩预留令牌。
  • 有关模型看到的内容，请参见 系统提示词。

钩子点（您可以拦截的地方）​

Clawdbot 有两个钩子系统：

  • 内部钩子 (网关钩子)：针对命令和生命周期事件的事件驱动脚本。
  • 插件钩子：代理/工具生命周期和网关管道内部的扩展点。

内部钩子 (网关钩子)​

  • agent:bootstrap：在系统提示词最终确定之前，构建引导文件时运行。 使用此钩子添加/删除引导上下文文件。
  • 命令钩子：/new、/reset、/stop 和其他命令事件（参见钩子文档）。

有关设置和示例，请参见 钩子。

插件钩子（代理 + 网关生命周期）​

这些钩子运行在代理循环或网关管道内部：

  • before_agent_start：在运行开始前注入上下文或覆盖系统提示词。
  • agent_end：在完成后检查最终消息列表和运行元数据。
  • before_compaction / after_compaction：观察或标注压缩周期。
  • before_tool_call / after_tool_call：拦截工具参数/结果。
  • tool_result_persist：在工具结果写入会话记录之前同步转换它们。
  • message_received / message_sending / message_sent：入站 + 出站消息钩子。
  • session_start / session_end：会话生命周期边界。
  • gateway_start / gateway_stop：网关生命周期事件。

有关钩子 API 和注册详情，请参见 插件。

流式传输 + 部分回复​

  • 助手增量从 pi-agent-core 流式传输，并作为 assistant 事件发出。
  • 块流式传输可以在 text_end 或 message_end 发出部分回复。
  • 推理流式传输可以作为单独的流或作为块回复发出。
  • 有关分块和块回复行为，请参见 流式传输。

工具执行 + 消息工具​

  • 工具开始/更新/结束事件在 tool 流上发出。
  • 在记录/发出之前，会对工具结果的大小和图像有效载荷进行清理。
  • 跟踪消息工具的发送，以抑制重复的助手确认。

回复整形 + 抑制​

  • 最终有效载荷由以下部分组装：
    • 助手文本（及可选的推理内容）
    • 内联工具摘要（当 verbose + 允许时）
    • 模型出错时的助手错误文本
  • NO_REPLY 被视为静默令牌，并从传出有效载荷中过滤掉。
  • 从最终有效载荷列表中移除消息工具重复项。
  • 如果没有可渲染的有效载荷剩余且工具出错，则发出回退工具错误回复 （除非消息工具已经发送了用户可见的回复）。

压缩 + 重试​

  • 自动压缩发出 compaction 流事件并可以触发重试。
  • 在重试时，内存缓冲区和工具摘要会被重置，以避免重复输出。
  • 有关压缩管道，请参见 压缩。

事件流（目前）​

  • lifecycle：由 subscribeEmbeddedPiSession 发出（并由 agentCommand 作为回退发出）
  • assistant：来自 pi-agent-core 的流式增量
  • tool：来自 pi-agent-core 的流式工具事件

聊天频道处理​

  • 助手增量被缓冲到聊天 delta 消息中。
  • 在 生命周期结束/错误 时发出聊天 final。

超时​

  • agent.wait 默认值：30s（仅针对等待）。timeoutMs 参数可覆盖。
  • 代理运行时：agents.defaults.timeoutSeconds 默认 600s；在 runEmbeddedPiAgent 中止计时器中强制执行。

可能提前结束的地方​

  • 代理超时（中止）
  • AbortSignal（取消）
  • 网关断开连接或 RPC 超时
  • agent.wait 超时（仅限等待，不停止代理）