专为高可靠性 AI Agent 设计的异步优先运行时框架

Unreal Agent 是一个面向生产级 AI Agent 场景打造的 Go 语言运行时框架，它不提供大模型或前端界面，而是专注解决「Agent 在真实业务中如何稳定、可追溯、可恢复地长期运行」这一核心难题。它用严谨的状态建模（Session、Inbox、Operation）、严格的执行边界（同步 translator + 异步 operation）和版本化持久化设计，把原本容易失控的 LLM 调用链，变成可审计、可回滚、可沙箱隔离的确定性工作流。尤其适合需要处理用户多轮交互、外部工具调用、失败重试与状态恢复的关键业务场景。

核心功能

会话级输入幂等性保障：通过内存中的 Session Inbox 自动去重同一请求的多次投递（如网络超时重发），避免因重试导致重复执行工具（如重复扣款、重复发消息），确保用户操作“一次生效”而非“多次触发”。
原子化工具调用状态追踪：将“模型想调什么工具”（tool call）、“是否合法”（translator 验证结果）、“实际执行了什么”（operation 提交）、“执行结果如何”（operation 状态）四者在存储层原子绑定，杜绝状态错位——比如模型说“查天气”，验证通过后生成 operation，但执行失败时仍能准确记录“已尝试且失败”，而非丢失上下文。
可分叉、可恢复的会话历史：Session 存储是 append-only 且支持 fork 的持久化结构，允许你在任意历史节点创建分支（例如 A/B 测试不同提示词路径）、或在崩溃后从最后一致点精确恢复，无需从头 replay 整个对话流。
零 I/O 的上下文构建器（Context Builder）：在内存中智能组装 LLM 输入（如截断长日志、压缩历史摘要），并明确返回“哪些内容被省略/压缩”，让模型知道自己看到的是精简版——既控制 token 成本，又避免模型误判信息完整，比简单 truncation 更透明可靠。
解耦式工具执行架构：Tool Translator（同步、无 I/O、仅校验+序列化）与 Operation Manager（异步、可远程、可沙箱）严格分离。你可在本地快速验证工具参数合法性，再将真正耗时/高危的操作（如执行 Bash 命令、调用第三方 API）交由独立进程或远程沙箱执行，大幅提升安全性与资源隔离性。
开箱即用的标准化工具集：内置 Bash（安全受限 shell）、ViewImage（图像内容解析）、Skill-Use（技能编排）三类工具定义及对应 translator，无需从零实现基础能力，且所有工具 schema 可扩展、可替换。
版本化持久化契约：Session 存储格式、Operation 序列化结构均带显式版本号；不兼容升级时会主动报错而非静默损坏数据，为长期运行的 Agent 提供强数据演进保障。
可插拔组件设计：Coordinator、Session Store、LLM Adapter 等核心组件均通过接口定义，开发者可无缝替换为自研实现——例如用 Redis 替代默认文件存储、用自定义认证逻辑对接私有 LLM 服务、或用 Kubernetes Job 管理 operation 执行。

技术亮点

Async-first 架构落地扎实：不是简单套用 async/await，而是从设计哲学上区分“协调层”（Coordinator 事件循环，必须轻量同步）与“执行层”（Operation Manager 异步 actor），禁止 translator 做 I/O 或阻塞，从根本上规避事件循环卡死风险，保障高并发下稳定性。
状态机驱动的 Agent 生命周期：将 Agent 行为抽象为 Input → Inbox 去重 → Coordinator 持久化 → LLM Turn → Tool Call → Translator 验证 → Operation 提交 → Operation 执行 → 状态回填的清晰闭环，每个环节职责单一、边界明确，便于调试与监控。
“无副作用”上下文构建原则：Context Builder 明确禁止 I/O 和持久化依赖，只做内存内确定性变换，并强制返回截断/压缩元数据，使 LLM 输入生成过程完全可复现、可测试，避免隐藏状态污染推理一致性。
沙箱就绪的 Operation 分发机制：README 中明确指出可构建“代理型 Operation Manager”，将序列化后的 operation 发往远程沙箱进程执行——这意味着 Bash 工具可运行在隔离容器中，即使脚本出错也不会影响主协调进程，真正实现安全边界。
Go 语言工程优势深度利用：依托 Go 的强类型接口、高效 goroutine 调度、静态链接与跨平台编译能力，实现低内存占用、秒级启动、单二进制部署，特别适合嵌入边缘设备或作为微服务组件集成。

适合哪些人用

主要面向三类技术决策者与开发者：

AI 基础设施工程师：正在构建企业级 Agent 平台，需要稳定、可观测、可运维的底层运行时，而非玩具级 demo 框架。例如：某金融科技公司用 Unreal Agent 支撑客服工单自动处理系统，当用户上传多张发票图片时，系统需可靠调用 OCR 工具、核对金额、生成报销单并通知财务，全程要求状态可追溯、失败可重试、操作不可重复。
垂直领域 Agent 开发者：聚焦特定场景（如 DevOps 自动化、科研文献分析、IoT 设备管控），需要快速集成 LLM 与自有工具链，同时保证关键操作（如重启服务器、提交代码、下发指令）的安全隔离与执行确认。例如：某云厂商内部用其构建“运维助手”，用户自然语言提问“查看过去一小时 CPU 超过90%的实例”，系统自动执行 Cloud CLI 命令、解析返回、生成摘要并附带原始命令日志供审计。
开源工具链贡献者：希望参与构建下一代 Agent 标准化基础设施，欣赏清晰接口设计与版本化契约，愿为可扩展的工具注册中心、LLM 适配器生态添砖加瓦。

快速上手

项目采用标准 Go 工程结构，无需复杂配置即可体验核心流程：

安装 Go 1.21+，克隆仓库：git clone https://github.com/unreallabsai/unreal-agent.git
进入 cmd 目录编译示例 agent：cd unreal-agent/cmd/unreal-agent && go build -o unreal-agent
设置 OpenAI API Key：export OPENAI_API_KEY=sk-xxx
启动本地 agent（使用默认文件存储与内置工具）：./unreal-agent --llm-provider=openai --model=gpt-4o
发送首个请求（通过 HTTP API 或参考 benchmarks 中的 client 示例）：
POST /v1/sessions
Body: {"input": "列出当前目录下的 .go 文件"}
响应将包含 session_id、initial_turn_id 及后续轮次的完整状态追踪路径。

关键配置项：可通过 --session-store-path 指定持久化目录，--tools 启用/禁用内置工具（如 --tools=bash,viewimage），自定义 LLM Adapter 需实现 harness/llm.Adapter 接口并注册。

同类对比 / 注意事项

vs LangChain / LlamaIndex：后者侧重于开发范式与工具集成便利性，而 Unreal Agent 专注运行时可靠性——它不提供链式调用 DSL，但提供了 Session 恢复、Operation 沙箱、输入幂等性等 LangChain 默认不具备的企业级能力；二者可互补：用 LangChain 构建 prompt 工程，用 Unreal Agent 托管执行。
vs AutoGen / CrewAI：这些框架强调多 Agent 协作角色，而 Unreal Agent 是单 Agent 运行时，更轻量、更可控；若需多角色，可基于其 Session Fork 能力构建分支协作流，而非硬编码角色调度逻辑。
注意事项：默认 Session Store 基于本地文件系统，生产环境务必替换为 Redis 或数据库实现；Bash 工具默认启用但需严格审查权限（建议配合 seccomp 或容器限制）；首次运行需手动创建 session 存储目录，否则报错不友好；LLM Adapter 错误需自行捕获重试逻辑，框架仅透传 provider 错误。