AgentScope.go Deep Dive: A Production-Grade Go Agent Framework

Project: https://github.com/linkerlin/agentscope.go Positioning: A Go implementation of AgentScope — a production-grade AI agent development framework Core paradigm: ReAct (Reasoning + Acting)

Key Points

• AgentScope.go is not a toy library: it is a full-featured agent framework targeting production, with 744 Go files covering 10+ model backends, ReMe long-term memory, the A2A protocol, ONNX local multimodal inference, GEP self-evolution, and complete Gateway service capabilities.
• Layered architecture: Application (Gateway / Studio / Production Service) → Orchestration (Workflow / Pipeline / MsgHub / Reflection / Plan) → Agent (ReActAgent V1/V2) → Capabilities (Model / Tool / Memory / Hook / Middleware) → Infrastructure (Message / Event / State / Session / Observability).

Dual-Version Agent Interface

• V1 keeps things simple: Call and CallStream for synchronous and streaming responses.
• V2 is event-driven: ReplyStream emits event.AgentEvent streams, LoadState/SaveState support suspend-resume, and InjectEvent lets external systems (HTTP handlers, WebSockets, other goroutines) resume a paused agent — enabling Human-in-the-loop workflows.

ReAct Loop Implementation

The core loop (replyInternal) runs up to maxIterations, executing: pre-model hooks → context compression (PyV2-aligned) → memory injection (ReMe auto-integration) → model call → post-model hooks → final-answer check → concurrent tool execution via errgroup.Group → appending tool results to history. Highlights:

• Concurrent tool calls with errgroup.Group
• External tools injected via context (session tools)
• Workspace binding: file tools are automatically sandboxed
• Full lifecycle hooks: PreCall / BeforeTool / AfterTool / PostCall
• Fine-grained stream events (block-level deltas, HITL suspend points)

Multimodal Message System

Messages (Msg) contain typed ContentBlock slices: TextBlock, ImageBlock (URL/base64), AudioBlock, VideoBlock, ToolUseBlock, ToolResultBlock, ThinkingBlock (Anthropic / OpenAI o-series reasoning), and HintBlock. This aligns with OpenAI / Anthropic / Gemini API formats and treats tool calls and results as first-class citizens.

Model Layer: 10+ Unified Backends

A single ChatModel interface (Chat, ChatStream, ModelName) unifies:

| Implementation | Backends | |---|---| | Native HTTP + SSE | Anthropic Claude, Gemini | | OpenAI-compatible | OpenAI, DeepSeek, Moonshot, xAI, DashScope, vLLM, Ollama | | OpenAI Response API | OpenAI o3 / o4-mini (reasoning_effort) |

A separate Formatter layer converts unified Msg objects to vendor-specific JSON.

Memory System: ReMe Long-Term Memory

From simple InMemoryMemory and WindowMemory up to ReMe implementations (in-memory, file, vector). ReMe provides:

1. Layered memory types: Personal, Procedural, and Tool memory 2. Automatic extraction/retrieval: MemoryOrchestrator plus unified retrieval (vector + keyword + hybrid) 3. Hybrid search: BM25 full-text (FTS5 trigram + CJK fallback), HNSW vector search with brute-force fallback, and reranking 4. Dream evolution: compressing conversations into long-term memories with versioning

Benchmarks: embedding cache hit 550 ns/op; vector search (1000 nodes) 229 μs/op; full-text search (1000 docs) 97 μs/op; ReMe file memory add 463 μs/op.

Tool System

Built-in tools cover file operations (Read/Write/Edit/Glob/Grep), shell commands, web search/browse, JSON processing, task management, scheduling, subagent invocation, and multimodal processing. Execution pipeline: model outputs ToolUseBlock → PermissionEngine check (HITL confirmation) → workspace sandbox binding → concurrent execution → result compression/offload → ToolResultBlock returned to the model.

Workflow Orchestration

Three tiers: Pipeline (sequential), MsgHub (broadcast between registered agents), and Workflow (Parallel, Condition routing, Loop with termination predicates, and MapReduce).

Gateway: From Library to Product

Endpoints: POST /chat, POST /chat/stream (SSE), GET /chat/ws (WebSocket). Production features include JWT multi-tenancy with workspace isolation, a three-mode permission engine (ACCEPT_EDITS / EXPLORE / VIEW), session persistence (JSONFile / Redis), automatic standard tool injection, tool result offloading, and A2A protocol support (AgentCard / Task / SSE / Registry / WebSocket).

ONNX Local Multimodal Inference

Pure Go preprocessing pipelines (CLIP image preprocessing → NCHW [1,3,224,224]; Whisper audio → Mel spectrogram [1,80,3000]) proxied over HTTP to an ONNX Runtime service — zero CGO dependency, no Python required. Image preprocessing runs at 3.5 ms/op (1024×768 → 224×224); audio preprocessing is ~9.7 s/op for 30s input (optimizable).

GEP Self-Evolution (Phase 6)

The Gene Evolution Protocol introduces Genes (signals_match + strategy + constraints + validation), Capsules (success snapshots with blast radius and execution traces), and a closed loop of Run → Reflect → Solidify. Via an MCP gateway, agents can invoke evolver__evolver_run to trigger automatic error repair, solidification, and audit trails.

Observability & Design Philosophy

OpenTelemetry tracing and LangSmith observers plug into the V2 event bus (ReplyStart, TextBlockDelta, ToolCallStart/End, ThinkingBlockDelta, UserConfirmRequest HITL suspend points).

Design principles: production-first (concurrency safety, graceful shutdown, context cancellation), idiomatic Go (builder pattern, context.Context throughout, minimal dependencies), protocol alignment with Python AgentScope v2 and OpenAI/Anthropic/Gemini APIs, and progressive complexity — starting from react.Builder().Name().Model().Build().

Versus Python AgentScope

| Dimension | Python AgentScope | AgentScope.go | |---|---|---| | Deployment | Python environment | Single static binary | | Concurrency | GIL-limited | Native goroutines | | Memory | Basic | ReMe + vector + full-text hybrid search | | ONNX inference | Python libraries | Pure Go, zero CGO | | Gateway | Weaker | Multi-tenant + permissions + session persistence | | GEP evolution | None | Introduced in Phase 6 |

Conclusion

AgentScope.go is an ambitious attempt to replicate and exceed Python agent framework capabilities in Go. Its strengths: full-stack coverage, production readiness, zero-CGO multimodal inference, a standout ReMe memory system, and a long-term self-evolution vision. Risks: the 744-file codebase carries high maintenance costs, some features (e.g., GEP) are early-stage, and the ecosystem is thinner than Python's. For long-running, high-concurrency, service-oriented agent applications in Go, it is currently the most complete option.

---

*Reference: github.com/linkerlin/agentscope.go*