智能体 | Nanobot 大模型 IO 接口设计

@dataclass(slots=True)
class AgentRunSpec:        # 输入：运行规格（多个可配字段）
    initial_messages: list[dict]      # 起始消息列表
    tools: ToolRegistry               # 可用工具集
    model: str                        # 模型名
    max_iterations: int               # 最大迭代次数
    max_tool_result_chars: int        # 单工具结果截断长度
    hook: AgentHook | None            # 生命周期钩子（流式/进度）
    concurrent_tools: bool            # 是否并行执行工具
    fail_on_tool_error: bool          # 工具出错是否终止
    context_window_tokens: int | None # Token 预算上限
    # ... 还有其他字段

@dataclass(slots=True)
class AgentRunResult:       # 输出：运行结果
    final_content: str | None         # 最终文本回复
    messages: list[dict]              # 完整对话历史
    tools_used: list[str]             # 使用过的工具名
    usage: dict                       # Token 用量统计
    stop_reason: str                  # completed / tool_error / max_iterations ...
    error: str | None                 # 错误信息
    tool_events: list[dict]           # 工具调用事件日志

输入: list[dict]  ← OpenAI Chat 格式作为"通用中间语言"
      [{"role": "system", "content": "..."},
       {"role": "user",   "content": "..."},
       {"role": "assistant", "content": "...", "tool_calls": [...]}]

输出: LLMResponse  ← 统一响应信封
      ├── content: str | None                       # 文本回复
      ├── tool_calls: list[ToolCallRequest]      # 工具调用请求（归一化）
      ├── finish_reason: str                        # stop / tool_calls / length
      ├── usage: dict                               # token 用量统计
      ├── error_*: fields                              # 结构化错误信息
      └── reasoning_content: str                    # 推理内容 (DeepSeek-R1 等)

@dataclass
class ToolCallRequest:
    id: str                    # 统一 ID 格式
    name: str                  # 工具名
    arguments: str             # JSON 字符串参数

外部 LLM APILLMProvider(第三层)AgentRunner(第二层)AgentLoop(第一层)用户外部 LLM APILLMProvider(第三层)AgentRunner(第二层)AgentLoop(第一层)用户→ continue 下一轮→ break 结束循环alt[有 tool_calls][纯文本回复]loop[AR ReAct 循环 (最多 N 轮)]"帮我重构这个函数"ContextBuilder.build_messages()组装 system + history + runtime + user msgrun(AgentRunSpec)tools=all, iterations=10, hook=stream_hook① 上下文治理管道drop_orphan → backfill → microcompact → budget → snipchat_stream_with_retry(messages, tools)② 重试引擎_safe → chat(abstract) → retry if needed③ 协议转换 + HTTP 请求(Anthropic/OpenAI/DeepSeek...)原始响应LLMResponse DTO④ 并行/串行执行工具read_file / grep / edit_file ...追加 tool_results 到 messagesAgentRunResultfinal_content + messages + usage_save_turn(session, messages)OutboundMessage(final_content)

#AgentLoop 调用 AgentRunner
result = await self.runner.run(AgentRunSpec(
    initial_messages=messages,         # 完整对话上下文
    tools=self.tools,               # 工具注册表
    model=self.model,               # 模型名称
    max_iterations=10,              # 最大循环次数
    max_tool_result_chars=16000,    # 单工具结果截断长度
    hook=hook,                      # 流式回调钩子
    fail_on_tool_error=False,       # 工具出错是否终止
    concurrent_tools=True,          # 允许并行工具执行
      ...
))

ToolRegistryLLMProviderAgentRunnerToolRegistryLLMProviderAgentRunner① 上下文治理管道② 调用大模型追加到 messages → 下一轮构建最终结果 → breakalt[有工具调用][纯文本回复]loop[每轮迭代 (max N 次)]清理孤立工具结果回填缺失结果微压缩旧工具输出截断超长结果Token 预算滑动窗口裁剪chat_stream_with_retry(messages, tools)LLMResponseexecute(tool_call_1)execute(tool_call_2) [可并行]tool_resultsAgentRunResult

# 完整调用链
AgentRunner._request_model()                                                        # 流式 or 非流式
  → provider.chat_stream_with_retry(**kwargs)
    → provider._run_with_retry(call=chat_stream, ...)   # 重试引擎
      → provider._safe_chat_stream(...)                 # 异常兜底
        → concrete.chat_stream(...)                     # 真正的 API 调用
          → [协议转换: 内部格式 → 厂商原生格式]
          → [HTTP 请求]
          → [响应解析: 厂商格式 → LLMResponse DTO]

正常响应异常/错误响应瞬时错误永久性错误retry_mode="standard"retry_mode="persistent"指数退避 1s→2s→4s (最多3次)无限重试, 最大60s间隔, 相同错误上限10次HTTP 429 有 Retry-After 头?无 Retry-After按 chunk 周期性回调 UI同上含图片? → 去掉图片重试一次重试图片已去掉仍失败LLMResponse错误 LLMResponseLLMResponse (不抛异常!)调用API成功判断可重试可重试不可重试standard模式persistent模式等待提取RetryAfter固定等待心跳等待特殊策略返回错误响应