Unreal Agent 扩展完全指南：自定义 Tool、LLM Adapter 与 Operation Manager 开发

Unreal Agent 扩展完全指南自定义 Tool、LLM Adapter 与 Operation Manager 开发【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agentUnreal Agent 是 Unreal Labs 推出的一个异步优先async-firstAgent Harness智能体执行框架用 Go 编写。它把会话状态管理、LLM 调用、工具执行拆成了多个可替换的组件官方明确鼓励你用自定义实现替换其中任何一块。本文面向新手带你用 3 个扩展点——自定义 Tool工具、LLM Adapter模型适配器、Operation Manager操作管理器——完整理解并扩展这个框架。先看懂架构7 大组件各管什么在动手之前先花 1 分钟建立全局认知。Unreal Agent 的代码分为三层目录角色harness/核心库你扩展的主要目标cmd/基于该库的可执行程序如 unreal-agent-runnerbenchmarks/基准测试官方在 README.md 中给出了组件职责表核心链路是用户输入 → Session Inbox(去重) → Coordinator(协调器) ↓ ↓ Session Store(持久化) Context Builder(拼装模型输入) ↓ LLM Adapter(调用模型) ↓ Tool Registry(解析工具调用) ↓ Operation Manager(异步执行操作)记住这个流程后面三个扩展点都对应链路上的关键节点。扩展点一开发自定义 Tool工具Tool 是模型能调用的能力比如执行 Shell 命令、查看图片。框架把一个 Tool 拆成两半Definition定义给模型看的 JSON Schema名称、描述、参数Translator翻译器校验模型发来的工具调用翻译成可持久化、可异步执行的Operation核心接口在 harness/tool/tool.go 中Translate(ctx, call) CallStatus把一次工具调用转换成操作引用TranslateResult(...)把操作结果格式化回给模型新手要点Translator 运行在协调器的事件循环上必须同步、不能做 I/O、不能挂起——所有耗时工作都应交给 Operation 去异步执行。这是初学者最容易踩的坑。参考实现照着 Bash 工具写内置 Bash 工具的完整实现只有 100 多行是最好的模板位于 harness/tool/bash/bash.goTranslate中校验参数 → 构造operation.Spec→ 通过ctx.Submit(spec)提交并返回等待中状态TranslateResult中根据操作状态运行中/完成/失败拼装给模型的文本注册方面harness/tool/registry.go 的NewRegistry负责把静态翻译器和启用的工具名单组合起来未启用的工具会被unavailableTranslator兜底。轻量替代方案Skill技能不想写代码时可以用Skill只需在目录下放一个带 YAML frontmatter 的SKILL.md文件含name和description两个字段harness/tool/registry.go 中的DiscoverSkills会自动发现并注册。技能执行由内置的SkillUse工具harness/tool/skill_use.go驱动适合让模型按文档操作的场景。扩展点二编写 LLM Adapter模型适配器LLM Adapter 负责把准备好的模型输入发给具体模型厂商并返回归一化的响应同时接管鉴权、取消和厂商错误处理。接口极其简洁只有 1 个方法harness/llm/adapter.gotype Adapter interface { Respond(context.Context, Request, RequestOptions) (Response, error) }Request/Response等归一化类型定义在 harness/llm/model.go涵盖消息、工具调用、推理内容reasoning等所有会话项——你只需把厂商的原始响应转换成这套通用语言。快速上手基于 Responses API 的适配器如果你想接入的模型也兼容OpenAI Responses API可以站在现成轮子上harness/llm/responsesapi/ 提供了通用的流式适配、重试策略和请求/响应编解码。项目内置的 OpenAI 客户端 harness/llm/clients/openai/client.go 就是这么做的——不到 60 行代码只是配置了BaseURL、APIKey和重试次数而已。其他现成适配器可参考harness/llm/clients/ollama/ — 本地 Ollamaharness/llm/clients/openrouter/ — OpenRouter 聚合harness/llm/clients/fireworks/ — Fireworks扩展点三实现 Operation Manager操作管理器Operation 是工具翻译器产出的可序列化的工作描述而 Operation Manager 就是驱动这些操作异步执行的 actor 运行时。它的接口定义在 harness/operation/operation.gotype Manager interface { Add(Operation) error // 启动一个操作每个 ID 最多一次 Cancel(ID, string) error // 取消操作 Updates() -chan Operation // 订阅操作状态更新 }操作有 6 种状态ready → awaiting → completed / failed / canceled外加canceling全程可持久化、可恢复。本地实现与代理思路默认的LocalOperationManager在 harness/operation/local_manager.go 中它内部按Type分发到 Shell、ViewImage、Value、SkillUse 等处理器并依赖 harness/primitives/ 提供的底层原语进程启动、文件读写、定时器、远程调用等。官方推荐的扩展思路见 README.md Extending the harness 一节实现一个proxy operations manager把序列化的操作转发到远程沙箱进程里的本地管理器中执行——这样工具就能跑在隔离环境里。这正是接口设计的价值会话历史格式带版本号、操作永远可序列化跨进程传输毫无障碍。动手路线图如何验证你的扩展加 Tool仿照 harness/tool/bash/bash.go 实现Translator在NewRegistry处注册先在测试里验证参数校验逻辑参考 harness/tool/bash/bash_test.go换 Adapter实现Respond单方法用 harness/llm/responsesapi/ 可省掉编解码换 Manager实现Add / Cancel / Updates三个方法本地跑通后考虑代理到沙箱跑 CLI通过 cmd/unreal-agent-runner/ 的入口见 main.go以 JSON 请求驱动一次完整会话观察 JSONL 持久化的会话项确认你的组件真正参与到了链路中常见问题 FAQQ1Translator 里能不能直接发 HTTP 请求不能。Translator 必须同步无 I/O耗时工作一律封装成 Operation 交给 Manager 执行。Q2自定义操作类型后恢复会话会出问题吗不会。框架承诺 session 存储格式带版本号、向后兼容不支持的旧版本会显式报错而不是静默损坏harness/sessionstore/。Q3项目依赖多吗很少。go.mod 中直接依赖只有 uuid、image、sys 等几个库代码风格清晰非常适合通读源码学习。总结扩展点接口适合场景自定义 Tooltool.Translator给模型加新能力查数据库、控硬件LLM Adapterllm.Adapter接入自有/新模型厂商Operation Manageroperation.Manager沙箱隔离执行、分布式执行Unreal Agent 的设计哲学很纯粹把 Agent 的每个环节抽象成小接口各自可替换、可测试。从内置的 Bash 工具和 OpenAI 客户端开始读起你会发现扩展它并没有想象中那么难。【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考