agentscope.go

概述

新增能力（v2.7.0）

快速开始

go get github.com/linkerlin/agentscope.go

import (
    "context"
    "fmt"
    "os"

    "github.com/linkerlin/agentscope.go/agent/react"
    "github.com/linkerlin/agentscope.go/message"
    "github.com/linkerlin/agentscope.go/model/openai"
)

func main() {
    chatModel, _ := openai.Builder().
        APIKey(os.Getenv("OPENAI_API_KEY")).
        ModelName("gpt-4o-mini").
        Build()

    agent, _ := react.Builder().
        Name("Assistant").
        SysPrompt("You are a helpful AI assistant.").
        Model(chatModel).
        Build()

    response, _ := agent.Call(context.Background(), message.NewMsg().
        Role(message.RoleUser).
        TextContent("Hello! What can you help me with?").
        Build())

    fmt.Println(response.GetTextContent())
}

支持的模型

按模型提供商快速上手

cd scripts/model_examples/openai_chat_call
export OPENAI_API_KEY=sk-...
go run .

Cookbook

核心包

Channel 多平台集成

// 1. 构建 channel 子系统
wh := channel.NewWebhookChannel("webhook-1")
router := channel.NewChatRouter(channel.RouteTable{
    ChannelID: "webhook-1",
    Bindings:  []channel.Binding{{ChatIDPrefix: "dev-", AgentID: "dev-agent", SessionPrefix: "dev-"}},
})
gateway := channel.NewGateway(router, runner)   // runner 适配 SessionManager
dispatcher := channel.NewDispatcher(gateway, channel.NewRegistry())

// 2. 平台适配器（3 选 1）
// dc := discord.New("discord-1", os.Getenv("DISCORD_TOKEN"))          // Discord
// fc := feishu.New("feishu-1", appID, appSecret)                      // 飞书（纯 HTTP）

// 3. 启动 + 服务 webhook 端点
dispatcher.StartAll(ctx)
mux.Handle("/webhook", wh)   // 或 fc（飞书事件订阅 URL）

Hub 市场

h, _ := builtin.NewFSHub("./catalog", "demo", "Demo Hub", "")
mcps, next, _ := h.ListMCPCards(ctx, "", 0, 20)   // 浏览（游标分页）
hub.InstallSkill(ctx, skillCard, "./skills")      // 下载+解压（zip-slip 防护）
mgr, _ := hub.InstallMCPs(ctx, mcps)              // 弹性连接（缺失二进制跳过）

Console 终端 TUI

go run ./examples/console

治理平面（Control Plane）

k := controlplane.NewKernel(controlplane.NewMemoryStore())
// Goal → Todo → ShouldRun → Writeback → SpendSlot
// HTTP：/api/v1/controlplane/* ；opt-in auto-solidify 见 AppConfig.AutoSolidifyOnGoalComplete

ONNX 生产化（多模态本地推理）

import "github.com/linkerlin/agentscope.go/embedding/onnx"

// 图像预处理（CLIP）→ 输出 NCHW [1,3,224,224]
preprocessor := onnx.NewImagePreprocessor(onnx.DefaultCLIPPreprocessConfig())
vec, _ := preprocessor.Preprocess(imageReader)

// 音频预处理（Whisper）→ 输出 Mel 频谱图 [1,80,3000]
audioProc := onnx.NewAudioPreprocessor(onnx.DefaultWhisperPreprocessConfig())
mel, _ := audioProc.Preprocess(pcmSamples, 16000)

// CLIP 图像嵌入器（HTTP 代理）
clip := onnx.NewCLIPImageEmbedder(onnx.DefaultCLIPImageEmbedderConfig())
embedding, _ := clip.EmbedImage(vec)

// 跨模态相似度（图像-文本对齐）
sim, _ := onnx.CrossModalSimilarity(imageEmbedding, textEmbedding)

// 模型管理器：自动下载/缓存/版本管理
manager, _ := onnx.NewModelManager(onnx.DefaultModelManagerConfig())
manager.RegisterModel(onnx.PredefinedModels()[0]) // CLIP ViT-B/32

A2A 增强（认证 + 限流 + WebSocket）

import "github.com/linkerlin/agentscope.go/a2a"

// 安全服务器：认证 + 限流 + CORS + 日志
server := a2a.NewSecureServer(card, runner, store)
server.auth.AddAPIKey("sk-xxx", "production-client")
server.WithRateLimit(a2a.NewRateLimiter(100, 200)) // 100 req/s, burst 200

// WebSocket 实时任务推送
wsServer := a2a.NewWebSocketEnabledServer(card, runner, store)
// 客户端通过 WebSocket 订阅任务状态，实时接收 task_update 事件

性能基准

高层生产服务 Bootstrap（强烈推荐）

appCfg := gateway.AppConfig{
    Agent:                 myAgent,
    Storage:               service.NewMemoryStorage(),
    JWTAuth:               jwtAuth,
    WorkspaceBaseDir:      "./workspaces",
    AutoStandardTools:     true,           // 自动为 sessions 注入 file+task+web+json+schedule 等
    AutoToolOffload:       true,
    DefaultPermissionMode: permission.ModeExplore,
    EmbeddingModel:        embedding.NewOpenAI(apiKey, "text-embedding-3-small"),
    EmbeddingCacheDir:     "./.embed_cache", // 自动 WithFileCache
}
srv := gateway.NewApp(appCfg)
srv.RegisterAppRoutes(jwtAuth)
srv.Start()   // 自动恢复 persisted schedules
defer srv.Close()

Embedding 包

import "github.com/linkerlin/agentscope.go/embedding"

emb := embedding.NewOpenAI(os.Getenv("OPENAI_API_KEY"), "text-embedding-3-small")
emb = embedding.WithFileCache(emb, ".cache/embeddings") // 可选

vecs, _ := emb.Embed(ctx, []string{"hello world"})

使用工具

import "github.com/linkerlin/agentscope.go/tool"

myTool := tool.NewFunctionTool(
    "weather",
    "获取指定城市的当前天气",
    map[string]any{
        "type": "object",
        "properties": map[string]any{
            "city": map[string]any{"type": "string"},
        },
        "required": []string{"city"},
    },
    func(ctx context.Context, input map[string]any) (any, error) {
        city := input["city"].(string)
        return fmt.Sprintf("%s 天气晴朗，22°C", city), nil
    },
)

agent, _ := react.Builder().
    Name("WeatherBot").
    Model(chatModel).
    Tools(myTool).
    Build()

记忆管理

基础 Memory

import "github.com/linkerlin/agentscope.go/memory"

mem := memory.NewInMemoryMemory()
agent, _ := react.Builder().
    Name("Assistant").
    Model(chatModel).
    Memory(mem).
    Build()

ReMe 长期记忆（文件 + 向量）

import "github.com/linkerlin/agentscope.go/memory"
import "github.com/linkerlin/agentscope.go/memory/handler"

// 创建向量记忆
v, _ := memory.NewReMeVectorMemory(cfg, counter, nil, embedModel)

// 注入编排器，实现自动提取与检索
orch := handler.NewMemoryOrchestrator(personalSum, proceduralSum, toolSum, memTool, profileTool, historyTool, dedup)
v.SetOrchestrator(orch)

// 端到端自动提取个人/任务记忆并写入向量库
res, _ := v.SummarizeMemory(ctx, msgs, "alice", "coding_task", "")

// 统一检索
nodes, _ := v.RetrieveMemoryUnified(ctx, "Go 最佳实践", "alice", "coding_task", "", memory.RetrieveOptions{TopK: 5})

ReAct 记忆注入编排

import "github.com/linkerlin/agentscope.go/memory"

// 创建 ReAct 步级记录器
recorder := memory.NewReactStepRecorder(memory.NewInMemoryStepStore())

// 创建记忆注入编排器（4 种策略：recent/targeted/personal/hybrid）
orchestrator := memory.NewReactOrchestrator(recorder, store, memory.DefaultReactOrchestratorConfig())

// 在 ReAct 循环中注入相关记忆
memNodes, sysMsg, _ := orchestrator.InjectMemory(ctx, query, history, "alice", "coding_task")

// 复盘提取：成功路径 / 失败教训 / 新知识
replay := memory.NewReactReplayExtractor(memory.DefaultReactReplayConfig())
result, _ := replay.Replay(ctx, steps)

钩子系统（人机协作）

import "github.com/linkerlin/agentscope.go/hook"

loggingHook := hook.HookFunc(func(ctx context.Context, hCtx *hook.HookContext) (*hook.HookResult, error) {
    fmt.Printf("[%s] Agent: %s\n", hCtx.Point, hCtx.AgentName)
    return nil, nil
})

agent, _ := react.Builder().
    Name("Assistant").
    Model(chatModel).
    Hooks(loggingHook).
    Build()

计划笔记本

import "github.com/linkerlin/agentscope.go/plan"

notebook := plan.NewPlanNotebook()
p := notebook.CreatePlan("研究任务")
notebook.AddStep(p.ID, "搜索信息")
notebook.AddStep(p.ID, "总结发现")

// 作为工具在 Agent 中使用
agent, _ := react.Builder().
    Name("Planner").
    Model(chatModel).
    Tools(notebook.AsTool()).
    Build()

多模型后端示例

Anthropic

import "github.com/linkerlin/agentscope.go/model/anthropic"

chatModel, _ := anthropic.NewBuilder().
    APIKey(os.Getenv("ANTHROPIC_API_KEY")).
    ModelName("claude-3-5-sonnet-20241022").
    Build()

Gemini

import "github.com/linkerlin/agentscope.go/model/gemini"

chatModel, _ := gemini.NewBuilder().
    APIKey(os.Getenv("GEMINI_API_KEY")).
    ModelName("gemini-1.5-flash").
    Build()

DashScope（阿里云）

import "github.com/linkerlin/agentscope.go/model/dashscope"

chatModel, _ := dashscope.Builder().
    APIKey(os.Getenv("DASHSCOPE_API_KEY")).
    ModelName("qwen-max").
    Build()

Ollama

import "github.com/linkerlin/agentscope.go/model/ollama"

chatModel, _ := ollama.NewBuilder().
    BaseURL("http://127.0.0.1:11434/v1").
    ModelName("llama3.2").
    Build()

DeepSeek

import "github.com/linkerlin/agentscope.go/model/deepseek"

chatModel, _ := deepseek.Builder("sk-...").
    ModelName(deepseek.ModelChat).
    Build()

Moonshot (Kimi)

import "github.com/linkerlin/agentscope.go/model/moonshot"

chatModel, _ := moonshot.Builder("sk-...").
    ModelName(moonshot.Model8K).
    Build()

xAI (Grok)

import "github.com/linkerlin/agentscope.go/model/xai"

chatModel, _ := xai.Builder("xai-...").
    ModelName(xai.ModelGrok2).
    Build()

vLLM

import "github.com/linkerlin/agentscope.go/model/vllm"

chatModel, _ := vllm.Builder("http://localhost:8000/v1", "sk-...").
    ModelName("meta-llama/Meta-Llama-3-8B-Instruct").
    Build()

OpenAI Response API

import "github.com/linkerlin/agentscope.go/model/openai_response"

chatModel, _ := openai_response.Builder().
    APIKey(os.Getenv("OPENAI_API_KEY")).
    ModelName("o3").
    ThinkingEnable(true).
    ReasoningEffort("medium").
    Build()

多 Agent 编排

顺序执行（Pipeline）

import "github.com/linkerlin/agentscope.go/pipeline"

pipe := pipeline.New("ResearchPipe", plannerAgent, writerAgent)
resp, _ := pipe.Call(ctx, message.NewMsg().Role(message.RoleUser).TextContent("Go 并发模式").Build())

广播调度（MsgHub）

import "github.com/linkerlin/agentscope.go/msghub"

hub := msghub.New()
hub.Register("coder", coderAgent)
hub.Register("reviewer", reviewerAgent)
results := hub.Broadcast(ctx, msg) // map[string]*message.Msg

并行 / 条件 / 循环（Workflow）

import "github.com/linkerlin/agentscope.go/workflow"

// 并行：让两个 Agent 同时处理，合并结果
par := workflow.NewParallel("DualCheck", nil, agentA, agentB)

// 条件：根据输入内容决定走哪个分支
cond := workflow.NewCondition("Router",
    func(m *message.Msg) bool { return strings.Contains(m.GetTextContent(), "urgent") },
    urgentAgent, normalAgent)

// 循环：反复优化直到满足质量条件
loop := workflow.NewLoop("Refiner", editorAgent,
    func(m *message.Msg) bool { return !strings.Contains(m.GetTextContent(), "FINAL") },
    5)

实时对话 Gateway

import "github.com/linkerlin/agentscope.go/gateway"

srv := gateway.NewServer(agent)
http.ListenAndServe(":8080", srv)

MapReduce 工作流

import "github.com/linkerlin/agentscope.go/workflow"

mr := workflow.NewMapReduce(
    "DocSummary",
    func(m *message.Msg) []string { return splitIntoParagraphs(m.GetTextContent()) },
    summarizerAgent, // mapper
    synthesizerAgent, // reducer
    4, // parallelism
)

Agent 自省/反思模式

import "github.com/linkerlin/agentscope.go/reflection"

agent := reflection.NewSelfReflectingAgent(
    "RefiningWriter",
    writerAgent,
    criticAgent,
    func(_, critique *message.Msg) bool {
        return strings.Contains(critique.GetTextContent(), "PASS")
    },
    3, // max iterations
)

resp, _ := agent.Call(ctx, message.NewMsg().Role(message.RoleUser).TextContent("topic").Build())

示例

可观测性

追踪中间件

import (
    "github.com/linkerlin/agentscope.go/observability"
    "github.com/linkerlin/agentscope.go/agent/react"
)

tracer := observability.NewOTelTracer(...) // 或 LangSmith tracer 等
tracingMW := &observability.TracingMiddlewareAdapter{
    Tracer: tracer,
    Name:   "my-agent",
}

agent, _ := react.Builder().
    Name("TracedAgent").
    Model(chatModel).
    Middlewares(tracingMW).  // 直接用于 middleware 链
    Build()

traced := observability.NewTracedAgent("my-agent", baseAgent).WithTracer(tracer)

LangSmith 追踪

import (
    "github.com/linkerlin/agentscope.go/event"
    "github.com/linkerlin/agentscope.go/observability"
)

client := observability.NewLangSmithClient(os.Getenv("LANGSMITH_API_KEY"))
observer := observability.NewLangSmithObserver(client, "my-project", "session-1")

bus := event.NewBus(100)
go observer.Observe(ctx, bus)

agent, _ := react.Builder().
    Name("TracedAgent").
    Model(chatModel).
    WithEventBus(bus).
    Build()

OpenTelemetry

import "github.com/linkerlin/agentscope.go/observability"

tp, _ := observability.InitTracerProvider("agent-service")
defer tp.Shutdown(context.Background())

GEP 自演化与 Evolver 对齐

为什么对齐 Evolver？

快速使用（Mock 先行，生产接 MCP）

import "github.com/linkerlin/agentscope.go/evolver"

flow := evolver.NewGEPFlow(evolver.NewMockEvolver()) // 生产：换成真实 backed client
runCfg := evolver.RunConfig{Context: "recurring gateway timeout on large payload", Strategy: "repair-only"}
runRes, solRes, _ := flow.RunAndSolidify(ctx, runCfg, false /* 设 true 干运行 */)

fmt.Println("Selected gene:", runRes.SelectedGene.ID)
fmt.Println("Solidified capsule:", solRes.CapsuleID)

// Skill 蒸馏为 Gene（对齐 skillDistiller）
sk := &skill.AgentSkill{Name: "timeout_recovery", Description: "...", SkillContent: "..."}
gene := sk.DistillToGene(evolver.CategoryRepair)
flow.Client.UpsertGene(ctx, gene)

// 演化记忆 recall（narrative 风格）
_ = flow.Client.Remember(ctx, evolver.RememberRequest{Text: "...", Type: "capsule", Category: evolver.CategoryRepair})
hits, _ := flow.Client.Recall(ctx, evolver.RecallRequest{Query: "timeout", Category: "capsule"})

部署与迁移

贡献与社区

许可证