Unreal Agent 工具系统拆解Tool Translator 如何让 AI 工具调用完全无阻塞【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agentUnreal Agent 是 Unreal Labs 开源的 Async-first异步优先AI Agent 执行框架。本文拆解它的工具系统模型发出 Tool Call 后由 Tool Translator 在协调器事件循环上同步完成校验与翻译把真实工作打包成可序列化的 Operation 交给独立运行时异步执行——工具跑得再慢也永远不会阻塞 Agent 的主循环 为什么 AI Agent 最容易卡在“工具调用”上传统写法里Agent 收到模型的工具调用后会直接执行跑一条ls、读一张图、装一个依赖……执行期间主流程只能干等。命令跑 30 秒整个会话就冻结 30 秒多个工具调用之间也无法并行。Unreal Agent 给出的答案是彻底解耦“翻译”和“执行”核心就一条规则来自项目 README.md 的术语表Tool translator只做两件事校验工具调用、把它翻译成若干 Operation。它在协调器事件循环上同步运行禁止做任何 I/O、禁止挂起循环。也就是说真正干活跑 shell、读文件、看图片全部下沉到独立的 Operation 运行时协调器只管记账和调度。核心角色一个“纯函数”式的 Tool TranslatorTranslator 的接口只有两个方法定义在 harness/tool/tool.goTranslate(ctx, call)—— 模型给出工具调用后纯内存地完成参数校验产出CallStatusTranslateResult(callID, status, operations)—— 把记录在案的状态与操作输出格式化成模型能读懂的结果文本。CallStatus的取值也极简只有两种结果harness/tool/tool.go结果含义Error校验失败直接把错误信息回给模型WaitingFor翻译成功附带已提交 Operation 的 ID 列表以 Bash 工具为例harness/tool/bash/bash.go解析command参数 → 检查 NUL 字节等非法输入 → 构造一个 Shell 类型的operation.Spec→ 调用ctx.Submit(spec)拿到 ID → 返回WaitingFor: [id]。全程没有执行命令没有网络请求微秒级完成 ✅这里的关键是Context.Submit的契约harness/tool/tool.go只分配 ID、记录惰性数据不做 I/O、不向其他队列派活。工作稍后才由协调器统一派发保证事件循环的原子性。三层流水线Tool Call → CallStatus → Operation整个工具系统就是一条单向流水线每一层职责清晰模型发出 Tool Call │ ▼ Tool Translator同步、无 I/O在协调器事件循环上运行 │ 校验 翻译 ▼ CallStatusError 或 WaitingFor 操作 ID─── 原子写入 Session Store │ ▼ Operation Manager独立 Actor 运行时异步执行 shell / 读图等真实工作 │ 完成后推送状态更新 ▼ TranslateResult → 工具结果回填模型上下文 → 进入下一轮Operation本质上是一个可序列化的工作描述harness/operation/operation.go带 ID、类型、版本、状态和 JSON 状态的不可变值对象。它的状态机很直观ready → awaiting → completed / failed / canceledharness/operation/operation.go。默认实现是LocalOperationManagerharness/operation/local_manager.go——一个自带 goroutine 的 Actor 运行时协调器通过Add把操作丢进来它通过Updates()通道把状态变更推回来。注意接口注释里的点睛之笔“local implementation is swappable”未来可以换成远程代理管理器把操作序列化后发到远程沙箱里执行而协调器一行代码都不用改。协调器事件循环无阻塞的“心脏”在哪里跳翻译只是第一步不阻塞的真正保证在协调器主循环harness/coordinator/loop.go一个select统一多路等待同时监听 Inbox 输入、Operation 状态更新、模型响应、心跳定时器和宽限定时器。谁先到就处理谁没有任何“轮询等待某个工具”的逻辑。模型调用本身也异步化requestModelResponse里用go func()把 LLM 请求丢到后台harness/coordinator/loop.go响应通过 channel 回传等待期间循环照样响应新输入。操作派发是批量且幂等的dispatchOperationToManager跳过已终态的操作保证同一 ID 最多入队一次。长时间等待有“心跳”兜底当只有工具调用在跑时按ToolHeartbeatInterval定期向 Inbox 投递 Heartbeat 控制消息把正在运行的工具调用列表汇报出来harness/coordinator/loop.go用户能实时看到进度而不是面对一片死寂。所以哪怕模型一口气并行发出 5 个 Bash 调用协调器也只是 5 次微秒级的翻译 派发然后继续处理下一条用户消息——这就是标题里“完全无阻塞”的由来 内置三件套Bash、ViewImage、SkillUse工具集是固定注册表模式由 harness/tool/static.go 声明三个静态工具注册表在 harness/tool/registry.go 中构建工具能力特点Bash后台执行 shell 命令描述中明确鼓励“独立命令以并行工具调用方式发出”ViewImage查看本地 JPEG/PNG/BMP/TIFF/WebP 图片路径相对于工作区SkillUse按名称加载已注册技能的指令技能动态注册/注销两个值得一提的细节优雅降级如果某工具未配置注册表会装入一个unavailableTranslatorharness/tool/static.go翻译时直接返回“not configured”错误状态模型收到友好提示而不是崩溃。技能动态发现DiscoverSkills会扫描目录下*/SKILL.md的 YAML frontmatterharness/tool/registry.go技能可运行时注册SkillUse工具则把“读取技能文件”也做成一个异步 Operationharness/tool/skill_use.go——连读文件都不例外一切走操作流水线。为什么这套设计“断电也能续命”无阻塞之外还有一个隐藏福利每个工具调用的状态都随 Operation 原子落盘。协调器翻译完成后立刻把ToolCallStatus追加写入 Session Storeharness/coordinator/loop.go会话历史是追加式append-only可 fork 的harness/sessionstore/恢复时按页加载历史并对每条记录过的调用校验工具是否仍可用harness/coordinator/loop.go操作本身带版本号且永远可序列化LocalOperationManager在重启后能把未完成的 Shell 操作从断点继续。这意味着Agent 跑到一半被杀掉重启后能精确恢复“哪些工具调用还在等待、输出写到哪里了”而不是从头再来。对跑长任务的 Agent 来说这比单纯“不阻塞”更值钱 关键源码索引想深入阅读的话按这个顺序走最短路径工具抽象与翻译契约harness/tool/tool.go工具注册表与技能发现harness/tool/registry.go工具 JSON Schema 定义harness/tool/static.goBash 翻译器示例harness/tool/bash/bash.goOperation 值对象与状态机harness/operation/operation.go本地操作 Actor 运行时harness/operation/local_manager.go协调器事件循环与心跳harness/coordinator/loop.go可执行的 Runner 入口cmd/unreal-agent-runner/main.go设计约定词汇表与组件表README.md一句话总结Unreal Agent 的工具系统用了一个朴素但威力巨大的原则翻译要快执行要慢两者必须分家。Tool Translator 像海关一样只做秒级查验放行把“重活”打包成带 ID 的 Operation 交给独立的 Actor 运行时慢慢干协调器靠单一事件循环 channel 心跳在工具漫长执行期间保持全速响应。理解了这个“翻译/执行分离 操作流”模型再回头看市面上任何 Agent 框架的卡顿与恢复问题都会清晰许多 【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考