ezloopezloop
Go Agent Loop Engine

一个干净的 Go Agent 循环引擎

你提供模型 provider 和工具,ezloop 驱动「模型 → 工具 → 模型」的循环直到任务完成,并保证消息历史全程协议完整、可直接存盘恢复。重试、限流、审批、MCP、会话持久化全部是可选扩展,引擎本身零第三方依赖。

Go 1.25+框架层零第三方依赖Apache-2.0go test ./... -race 全绿
agent.go
fsys := fs.NewLocal(".")
agent := core.NewAgent(p,
    core.WithSystemPrompt("你是 ezloop 驱动的命令行助手"),
    core.WithModelWarp(modelretry.Warp()),              // 模型调用:重试
    core.WithToolWarp(limit.Warp(4), safetool.Warp()),  // 工具执行:并发闸 + 防护
    core.WithHooks(
        contextfix.New(),          // 修理外部带入的破损历史
        filetools.New(fsys),       // read/write/edit/terminal 四件套
        askuser.New(),             // 模型向用户提问
        task.New(),                // 并行分身
    ),
    core.WithStreaming(true),
)

state, err := agent.Run(ctx, "帮我看看当前目录有什么")
理念

引擎只做三件事:循环、历史、事件

驱动模型与工具的循环;在任何退出路径下保证消息历史协议完整(每个 tool_call 必有对应结果,可直接存盘恢复);执行过程以事件流实时透出。除此之外的能力全部外挂,不进引擎。

model · 节点

实现 provider.ModelProvider 接入任意模型;WithModelWarp 给每次调用包上重试、降级、路由等中间件。流式可选实现 StreamProvider。

tool · 节点

types.NewTool 从参数结构体反射生成 schema;WithToolWarp 给每次执行包上限流、防护。多个调用默认并发,结果按原始顺序写入历史。

hook · 切面

七个生命周期时机点,外加 GuideHook 静态声明。注册工具、拦截审批、压缩上下文、保存会话——实现对应小接口,按注册序插在对应时机。

2
类装饰器(模型 / 工具)
7+1
个时机钩子 + Guide 声明
1
个 Fork 派生原语
0
引擎对扩展的 import
  • 所有能力都是扩展 —— 重试是装饰器,MCP、审批、会话保存都是钩子。引擎代码不 import 任何扩展,不用不引入,升级互不影响。
  • 状态即消息 —— 循环的全部状态是 LoopState.Messages:可序列化、可存盘,下一轮 WithHistory 原样传回。没有隐藏的内存状态,恢复就是重放历史。
  • 构建后只读 —— NewAgent 之后 Agent 不可变:可以做成全局单例被多个 goroutine 并发使用,Fork 派生分身靠浅拷贝完成。
  • 装饰器在节点内,钩子在节点外 —— warp 决定节点怎么执行,hook 决定流程什么时候插入逻辑,两层互不越界。