深入OneBox(万宝盒)AI Agent工具调用循环实现原理:AgentLoopExecutor与ToolCallTaskManager

原创2026-10-25 21:31:151,460 阅读

深入OneBox(万宝盒)AI Agent工具调用循环实现原理:AgentLoopExecutor与ToolCallTaskManager

OneBox(万宝盒)是一款免费的安卓 AI Agent 与工具箱应用。它的 AI 助手不只是"会聊天",更能通过工具调用循环真正动手干活:记账、记东西、写笔记。这篇文章深入 OneBox 的 AI 功能源码,拆解工具调用循环的核心实现——执行中枢 AgentLoopExecutor 与持久化管家 ToolCallTaskManager,看看 AI 是如何一步步发现工具、执行工具、处理失败,甚至在 App 重启后断点续跑的。

OneBox AI助手工具调用循环演示,展示AI记账功能中工具发现、新增账目、整理回复的执行步骤

Agent Loop 是什么:AI 如何"先想后做"

当你告诉 OneBox 的助手"把感冒药记到主卧药箱",背后发生的是一个 Agent Loop(智能体循环):

  1. LLM 返回一组 tool_calls(工具调用指令);
  2. App 执行这些工具,拿到结果;
  3. 把结果回填给 LLM,让它继续思考;
  4. 若 LLM 又发起新工具调用,回到第 1 步,直到它输出最终回复。

这个循环由 AgentLoopRunner.kt 驱动,它在一个 while 循环中交替执行"一轮工具迭代"和"一次 LLM 追问请求",直到 LLM 不再调用工具、或达到最大迭代次数(可在 10~60 之间配置,默认上限定义于 AIChatStorage.kt)。

而真正的"脏活累活"——工具的执行、确认、失败恢复——交给了本文的主角 AgentLoopExecutor。

AgentLoopExecutor:工具调用的执行中枢

AgentLoopExecutor.kt 是一个全局单例,职责非常清晰:执行已完成构建的 ToolCall 列表,并在每个执行节点把状态持久化到数据库,支持断点续跑。

累积流式 tool_call 碎片

在流式协议中,LLM 的 tool_calls 不是一次性返回的,而是"碎片化"增量到达:第一个数据块通常只带 id 和 function.name,后续数据块逐步追加 function.arguments 的参数片段。

AgentLoopExecutor 通过 accumulateToolCallDeltas 把这些碎片按 index 分桶累积,当 finish_reason == "tool_calls" 时,再由 buildCompletedToolCalls 拼成完整的工具调用列表。

一个值得注意的设计:累积器不挂在单例执行器上,而是放在会话级状态 AgentLoopSessionState.kt 中。这样多个 AI 会话并行对话时,彼此的工具碎片和迭代计数不会互相污染。

批量执行:能并行的并行,要确认的串行

LLM 一次可能返回多个工具调用。executeToolCalls 内部采用分批策略(executeBatchedToolCalls):

工具类型 执行策略 原因
纯查询类(无交互、无登录、无确认、无权限要求) 协程并发批量执行 提升多工具吞吐
需确认 / 需登录 / 需权限 / 交互式工具 逐个串行执行 避免弹窗与权限申请互相冲突

是否可并行由 isEffectivelyParallelizable 判定:五个条件必须全部满足(parallelizable = true 且非交互式、不需确认、不需登录、无权限要求)才会进入并发批次。

五重守卫:动手之前先过安检

每个工具真正执行前,都要通过 evaluateToolExecutionGuards 中的层层检查:

  1. 授权守卫(ToolAuthorizationGuard):判断工具是否被允许调用;
  2. 前置表达式校验:对参数做预执行校验;
  3. 登录检查:声明了 requiresLogin 的工具,未登录直接拒绝;
  4. 权限申请:向系统申请所需 Android 权限,用户拒绝则终止;
  5. 用户确认:高风险工具弹出确认框,展示工具分类、风险级别与原始参数。

OneBox AI工具调用前的确认弹窗,展示工具分类BUSINESS、风险级别SENSITIVE和原始参数,用户可拒绝或继续

有个细节很见功力:所有返回给 LLM 的拒绝/失败结果都统一使用英文 reason_code(如 permission_denied、login_required、user_rejected),避免多语言模型的语义理解偏差,让 AI 能准确理解"为什么没执行"。

超时与重试:单次计时、有限次重试

工具执行采用"每次尝试独立计时"的重试循环(executeSingleToolCall):

  • 超时优先级:工具自身声明 > 远程配置 agentToolTimeoutSeconds > 本地默认 60 秒;
  • 重试安全约束:需要确认、交互式、需登录或需权限的工具一律不重试,防止重复弹窗、重复申请权限;
  • 取消友好:会话被取消后(isShuttingDown 置位),结果照常落库,但跳过 UI 实时回调,避免与取消处理逻辑并发读写状态。

ToolCallTaskManager:每一步都落库的持久化管家

AI 干活可能干到一半 App 被系统杀掉。ToolCallTaskManager.kt 的作用就是把每个工具调用任务的生命周期状态写入 Room 数据库,让"断点续跑"成为可能。

状态机:一个 tool_call 的一生

每次 LLM 返回工具调用后,persistNewTasks 会立即批量入库(此时状态为 PENDING),执行过程中实时更新状态,对应实体为 ToolCallTaskEntity.kt:

状态 含义
PENDING 已入库,等待执行
EXECUTING 正在执行中
WAITING_INPUT 交互式工具,等待用户输入
COMPLETED 执行完成
FAILED 执行失败或已取消

表上建了 conversation_id 与 (conversation_id, status) 两个索引,重启后按会话查未完成任务可以做到毫秒级响应。

断点续跑:App 重启后从哪里继续?

App 重启后,恢复协调器 ToolResumeCoordinator.kt 调用 buildResumeState,根据数据库快照判断三种恢复场景:

场景 判定条件 恢复动作
WaitingInput 存在等待用户输入的任务 优先恢复交互式表单 UI(连表单请求 JSON 都持久化了)
FromTool 存在 PENDING/EXECUTING 任务 从第一个未完成任务的迭代轮次重新执行
CompletedNeedsLLM 任务全部完成但循环未结束 重建上下文,直接向 LLM 发起追问请求

这正是"万宝盒"敢把耗时任务交给 AI 的底气——即使退到桌面、甚至进程被杀,回来时任务还在原地等你。

OneBox交互式工具等待用户输入场景,AI助手就模糊信息弹出表单向用户确认

工具链回放:AI 干的活都能查账

已完成的任务还能通过 toToolCallRecords 转换为 ToolCallRecord 列表,与消息表的 toolCalls JSON 字段兼容。你在聊天界面看到的"调用了哪个模块、执行了几个步骤、产出了什么",以及"我的"页面里的操作记录,数据源头都在这里。过期任务(已完成超过 24 小时)则会被定期清理,数据库不会无限膨胀。

OneBox操作记录页面,展示AI助手每次调用哪个工具、模块及产出内容,可随时回溯

三个角色如何协作:一次完整的循环

把视角拉远,一次工具调用轮次中的分工是这样的:

阶段 负责人 做什么
流式接收 AgentLoopSessionState 累积 tool_call 碎片、计迭代数
入库登记 ToolCallTaskManager 新任务以 PENDING 批量落库
分批执行 AgentLoopExecutor 并行/串行调度、守卫检查、超时重试
状态回写 ToolCallTaskManager 标记 EXECUTING / COMPLETED / FAILED
上下文回填 AgentLoopRunner 工具结果转为消息追加上下文,发起 LLM 追问

循环正常结束后,工具任务会被清除;若达到最大迭代次数,则保留暂停上下文(PausedContext),支持用户点击"继续"后扩展迭代预算继续执行,而不是推倒重来。

设计亮点小结

回顾整个实现,有三个值得借鉴的思路:

  1. 执行器无状态化:单例执行器不持有会话状态,会话级数据下沉到独立的 State 对象,天然支持多会话并行;
  2. 状态即断点:不依赖内存缓存任务进度,每个生命周期节点都落库,进程死亡不是事故而是"待恢复状态";
  3. 面向 LLM 的契约:拒绝与失败结果用结构化的英文 reason_code 表达,让 AI 而非人类去消费这些"错误信息",保证跨模型、跨语言的语义一致性。

如果想继续深入,可以从这几个入口读起:

OneBox 把"AI 动手干活"这件看似魔法的事,拆解成了一条可观测、可持久化、可恢复的工程化流水线。理解了这个循环,你就理解了当下所有 Agent 应用的骨架。

登录后查看全文
OneBox