Agent 执行循环

概述

Agent Loop 是 Agent 的完整执行路径：消息接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。每个 Session 同一时刻只有一个串行运行的 Loop，保证会话状态一致性。

核心要点

入口点：Gateway RPC（agent / agent.wait）或 CLI agent 命令

执行流程：

1. agent RPC 验证参数、解析 Session，立即返回 { runId, acceptedAt }
2. agentCommand 解析模型、加载 Skills、调用 runEmbeddedPiAgent
3. runEmbeddedPiAgent 通过 per-session + global 队列串行化运行，订阅 pi 事件并流式输出
4. subscribeEmbeddedPiSession 将 pi 事件桥接为三类流：lifecycle、assistant、tool
5. agent.wait 等待 lifecycle end/error，返回 { status, startedAt, endedAt }

并发控制：

• 按 session key 串行（session lane），再进入 global lane（默认 main）
• 会话写锁（file-based）防止多进程竞争，默认超时 60000ms
• 写锁默认非重入，需要嵌套时显式传 allowReentrant: true

Hook 系统（两套）：

• 内部 Hook：agent:bootstrap、命令事件（/new、/reset、/stop）
• 插件 Hook：before_model_resolve、before_prompt_build、before_agent_reply、agent_end、before_tool_call/after_tool_call、message_received/message_sending/message_sent、session_start/session_end 等

超时配置：

• Agent 运行时默认 172800s（48 小时）：agents.defaults.timeoutSeconds
• agent.wait 默认 30s（仅等待，不终止 Agent）
• 模型空闲超时：models.providers.<id>.timeoutSeconds

回复抑制：精确 token NO_REPLY/no_reply 会被过滤，不发送给用户

配置/使用

{
  agents: {
    defaults: {
      timeoutSeconds: 172800,
      blockStreamingDefault: "off"
    }
  },
  session: {
    writeLock: { acquireTimeoutMs: 60000 }
  }
}

相关页面

• architecture — Gateway 整体架构
• queue — 命令队列与并发控制
• streaming — 流式输出机制
• context — 上下文组装
• session — 会话管理