跳到主要内容

Agent Loop

AgentLoop 是 CountBot 的核心循环,负责处理用户消息、调用 LLM、执行工具、生成响应。

流程概览​

用户消息 → 构建上下文 → LLM 推理 → 有工具调用? → 执行工具 → 追加结果 → 继续推理
                                              ↓
                                          无工具调用 → 返回响应

核心组件​

AgentLoop​

位置: backend/modules/agent/loop.py

from backend.modules.agent.loop import AgentLoop

agent = AgentLoop(
    provider=llm_provider,
    workspace=Path("/workspace"),
    tools=tool_registry,
    context_builder=ctx_builder,
    subagent_manager=sub_mgr,
    model="glm-4.7-flash",
    max_iterations=25,
    max_retries=3,
    temperature=0.0,
    max_tokens=4096,
    thinking_enabled=True,
)

主要方法​

方法说明
process_message()处理用户消息,返回 AsyncIterator[str] 流式响应
execute_tool()执行单个工具调用
process_direct()直接处理消息并返回完整字符串(用于 CLI/Cron)

ContextBuilder​

位置: backend/modules/agent/context.py

负责组装系统提示词和消息列表:

from backend.modules.agent.context import ContextBuilder

builder = ContextBuilder(
    workspace=Path("/workspace"),
    memory=memory_store,
    skills=skills_loader,
    persona_config=persona,
)

系统提示词包含:核心身份、工具使用原则、记忆系统指导、安全准则、已激活技能。

执行流程​

  1. 构建消息: ContextBuilder.build_messages() 组装 system prompt + 历史消息 + 当前消息
  2. LLM 推理: 调用 provider.chat_stream(),逐 chunk 输出内容
  3. 工具调用: 如果 LLM 返回 tool_calls,依次执行并追加结果到消息列表
  4. 循环迭代: 重复步骤 2-3,直到无工具调用或达到迭代上限

终止条件​

  • LLM 未返回 tool_calls(正常完成)
  • 达到 max_iterations 迭代上限(默认 25)
  • 工具调用总数达到上限
  • cancel_token 被触发(用户取消)
  • LLM 返回错误

达到上限时会在响应末尾追加: [达到最大工具调用次数 25]

工具执行​

每次迭代中,AgentLoop 从 ToolRegistry 获取工具定义,以 OpenAI Function Calling 格式传递给 LLM:

tool_definitions = self.tools.get_definitions()

工具执行带自动重试,默认最多 3 次:

attempt 1 → 失败 → sleep(1.0s)
attempt 2 → 失败 → sleep(1.0s)
attempt 3 → 失败 → 记录错误,返回错误信息给 LLM

重试失败后,错误信息作为 tool result 返回给 LLM,LLM 可以尝试其他方案或告知用户失败。

API Key 轮换​

当 LLM 返回 401/429 等认证或限流错误时,如果配置了多个 API Key,AgentLoop 会自动切换到下一个 Key 重试,最多尝试 3 次。

流式响应​

process_message() 返回 AsyncIterator[str]:

WebSocket 消费(Web UI)​

async for chunk in agent.process_message(...):
    await ws.send_json({"type": "stream", "content": chunk})

直接消费(CLI/Cron)​

response = await agent.process_direct(
    content="查看当前目录",
    session_id="cron:daily-report",
    channel="cron",
)

配置参数​

参数默认值说明
max_iterations25最大迭代次数(同时限制工具调用总数)
max_retries3工具执行最大重试次数
retry_delay1.0s重试间隔
temperature0.0LLM 温度参数
max_tokens4096LLM 最大输出 token 数
thinking_enabledTrue是否启用模型思考模式

相关文件​

文件说明
backend/modules/agent/loop.pyAgentLoop 主类
backend/modules/agent/context.pyContextBuilder 上下文构建器
backend/modules/tools/registry.py工具注册表
backend/ws/events.pyWebSocket 事件处理