goagent

goagent 是一个面向 Go 的 Agent 应用框架。它把大模型、工具调用、运行状态、记忆、工作流与运行时治理组合成统一的编程模型，让开发者能够用 Go 构建可组合、可观测、可持久化的 AI Agent 与 Multi-Agent 系统。

它既适合从一个带工具调用的聊天助手开始，也适合逐步演进到包含 RAG、人工审批、并行工作流、后台队列、Redis 持久化和 DAG 图式执行计划的生产型应用。

当前模块路径：github.com/jiujuan/goagent；要求 Go 1.25 或更高版本。

• 构建能调用业务 API、数据库、脚本或命令行工具的智能助手。
• 构建客服、数据分析、研发助手等按领域分工的 Multi-Agent 系统。
• 编排确定性的串行、并行、循环流程，或由模型驱动的 ReAct / Plan-and-Execute 流程。
• 为 Agent 增加 RAG、分层记忆、跨进程持久化、上下文压缩、限流、重试和人工审核。
• 通过后台任务队列（内存或 Redis）处理长耗时任务，并通过事件总线流式接收进度。

框架以 core 中的消息、事件、状态和指令作为公共语言。agent 既是 Agent 的声明（配置）也是可运行句柄——它自身就是运行时，没有独立的 runner/runtime 层：一次 Run/Stream 会加载状态、驱动模型与工具循环、发布事件并写检查点。

flowchart TB
    U["调用方 / UI / API"] --> A["agent\nNew + Run / Stream / Resume\n（内含运行时循环）"]
    A --> P["prompt\n可组合系统提示"]
    A --> M["llm.Model\nAnthropic / OpenAI 兼容 / Agnes / Mock"]
    A <--> T["tool\n类型化本地函数 / MCP / Web / Exec"]
    A --> MW["middleware\n重试、限流、压缩、Steering、HITL、RAG"]
    A <--> MEM["memory\n向量检索与分层记忆（memx）"]
    A --> WF["工作流 / 计划\nSequential / Parallel / Loop / Pipeline / NewPlan"]
    A --> CP["checkpoint\n内存 / JSONL 文件（按 ThreadID 恢复）"]
    A --> BUS["bus + queue\n事件总线、后台任务、Redis"]
    T --> SB["sandbox\n受限进程执行"]
    A --> E["core.Event\n文本、工具、进度、结果"]
    E --> U

• core：跨模块共享的数据模型——Message、Event（类型化事件）、State、工具调用/结果、指令（Directive）。
• agent：Agent 的声明与运行时本身；实现 LLM 循环、工作流（Sequential/Parallel/Loop/Pipeline）、DAG 计划、委派与 HITL。
• llm：供应商无关的模型接口与韧性层；适配器只需实现统一的请求/响应流（anthropic、openaicompat、agnes、mock）。
• tool：工具契约与泛型函数工具，另提供 mcp、web、exec 等现成工具。
• checkpoint：显式状态快照的持久化——内存与 JSONL 文件后端，支撑跨进程 resume。
• memory：向量检索与自动 RAG；memx 装配规则/项目/工作/文本多层记忆。
• middleware：以装饰器方式包裹模型，加入重试、限流、压缩、steering、HITL、RAG 等通用策略。
• prompt：可组合的系统提示 Section（身份、环境、工具指导、状态）。
• bus、queue、sandbox、vfs：事件总线、异步后台执行、受控外部进程、虚拟文件系统后端。
• config、logger、eval、obs/otel：配置、日志、评测与可观测性等运行时治理设施。

在你的 Go 项目中安装：

go get github.com/jiujuan/goagent

或克隆本仓库后直接运行示例：

git clone https://github.com/jiujuan/goagent.git
cd goagent
go test ./...

离线示例均使用 llm/mock 和模拟 Embedding，因此不需要 API Key 或网络模型调用。

下面是一个最小闭环：模型先请求天气工具，框架执行工具并将结果放回消息历史，模型随后给出最终答复。Run 一行拿到答案，Stream(...).Iter() 则可观察同一次运行的事件流。

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/jiujuan/goagent/agent"
	"github.com/jiujuan/goagent/core"
	"github.com/jiujuan/goagent/llm"
	"github.com/jiujuan/goagent/llm/mock"
	"github.com/jiujuan/goagent/tool"
)

func main() {
	// 类型化工具：JSON schema 从参数结构体反射生成。
	weather := tool.New("get_weather", "查询某城市的当前天气",
		func(_ *tool.Context, in struct {
			City string `json:"city" desc:"城市名"`
		}) (string, error) {
			return in.City + "：晴，25°C", nil
		})

	// mock 模型：首轮请求工具，拿到工具结果后给出最终答复。
	model := mock.New("mock", func(req *llm.Request) *llm.Response {
		if tr, ok := mock.LastToolResult(req); ok {
			return mock.Text("天气结果：" + tr.Content[0].(core.Text).Text)
		}
		return mock.CallTool("c1", "get_weather", `{"city":"北京"}`)
	})

	a, err := agent.New(
		agent.WithModel(model),
		agent.WithInstruction("你是一个友好的天气助手。"),
		agent.WithTools(weather),
		agent.WithMaxTurns(8), // 模型<->工具循环的安全上限
	)
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()

	// A) 一行拿到答案。
	answer, err := a.Run(ctx, "北京天气怎么样？")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("answer:", answer)

	// B) 或流式观察同一次运行的事件。
	for ev, err := range a.Stream(ctx, "上海呢？").Iter() {
		if err != nil {
			log.Fatal(err)
		}
		switch e := ev.(type) {
		case core.ToolDone:
			fmt.Printf("🔧 %s -> %s\n", e.Result.Name, e.Result.Content[0].(core.Text).Text)
		case core.MessageDone:
			if t := e.Message.Text(); t != "" {
				fmt.Println("🤖", t)
			}
		}
	}
}

直接运行仓库中的完整 Quick Start：

go run ./examples/quickstart

把 mock 模型替换成 llm/anthropic 或 llm/openaicompat 的模型实现，即可接入真实文本模型；图像和视频场景可使用 llm/agnes 客户端。请将密钥放在运行环境中，不要写入源码或提交到版本库。

示例均是独立的 main 包，优先阅读文件顶部注释，再运行相应命令。使用真实模型的示例需要设置对应环境变量（多为 AGNES_API_KEY / AGNES_MODEL），未设置时通常只打印用法后退出。

1. 从 examples/quickstart 复制 Agent 与工具的最小骨架，用 agent.New(...) + Run/Stream。
2. 用真实模型适配器替换 llm/mock，并通过环境变量或密钥管理服务注入凭证。
3. 需要连续对话与跨进程恢复时，用 agent.WithCheckpointer(checkpoint.NewFile(dir))，并在运行时用 agent.OnThread(id) 指定线程。
4. 有知识库需求时，用 memory.NewRetriever(...) 配合 middleware.RAG(...) 自动注入，或提供检索工具让模型按需调用。
5. 业务步骤固定时用 Sequential / Parallel / Loop / Pipeline；带依赖的复杂任务用 agent.NewPlan；需要领域专家协作时配置 WithSubAgents 或 AsTool。
6. 对外部命令、删除、支付等高风险动作，同时使用 sandbox 与 middleware.Permission(...)。

agent/        Agent 声明与运行时；工作流与 DAG 计划
core/         消息、事件、状态、指令等公共模型
llm/          模型抽象、韧性层及厂商适配器（anthropic/openaicompat/agnes/mock）
tool/         类型化工具、MCP、Web 与命令执行工具
checkpoint/   显式状态快照持久化（内存 / JSONL 文件）
memory/       向量检索、RAG 与分层记忆（memx/rules/projectmem/workingmem/textmem）
middleware/   重试、限流、压缩、Steering、HITL、RAG
prompt/       可组合系统提示 Section
bus/          进程内事件总线（pub/sub）
queue/        后台任务队列与 Worker 池（内存 / Redis Stream）
sandbox/      外部进程执行策略与默认实现
skills/       文件系统技能包与脚本资源
vfs/          虚拟文件系统后端（core.FileStore 实现）
config/       配置系统（基于 viper）
logger/       日志系统（基于 zerolog）
eval/         评测与打分
obs/          可观测性（OpenTelemetry 集成）
examples/     可独立运行的端到端示例

欢迎通过 Issue 或 Pull Request 提交问题、示例和改进。提交前请至少运行：

go test ./...