AgentScope Go: Catch-Up Plan to Reach Parity with the Python Reference Implementation

Forum topic · ✨步子哥 · 2026-06-11

Summary

This forum post presents a phased engineering roadmap for agentscope.go, a Go implementation of the AgentScope agent framework, aiming to reach production-level parity with the Python agentscope v2 reference implementation. The Go version already leads in several areas: event-driven V2 architecture with hooks and interrupt/resume, the ReMe long-term memory system, advanced multi-agent orchestration (pipeline, workflow, msghub, plan, MapReduce), A2A protocol support, a capable gateway (SSE, WebSocket, StreamableHTTP, AG-UI, tool offload, background tasks, scheduling, JWT auth, OTel/LangSmith), and strong test coverage. Key gaps identified include: a production-grade web UI/Studio (Python has a 60+ component React app; Go only has a minimal demo), a one-command high-level bootstrap API comparable to Python's create_app(), a typed credential abstraction with a schema endpoint for dynamic forms, a standalone embedding package, richer data models, multiple Dockerfile templates, and an end-to-end Agent Service + Studio example. The plan proposes five phases: (1) typed credentials and bootstrap hardening, (2) service lifecycle and default tool wiring, (3) Docker templates and an embedding package, (4) a lightweight HTMX-based Studio UI plus AG-UI compatibility, and (5) tracing, docs, and release polish. Strategy emphasizes incremental evolution, idiomatic Go, backward compatibility, and test-verifiable milestones (go test ./... -race).

AgentScope Go Catch-Up Plan: Reaching Parity with the Python Reference Implementation

Based on a comprehensive comparison dated 2026-06-11, this plan aims to bring agentscope.go to (or near) parity with the Python agentscope v2 reference in terms of production-grade agent service delivery and abstraction completeness — while preserving Go's strengths in memory (ReMe), event-driven design, orchestration (a2a/workflow), permissions, and testing.

Where Go Already Leads or Matches

Event-driven V2 architecture with fine-grained events, Hook/StreamHook, and interrupt/resume (AgentState)
ReMe long-term memory system (far beyond the currently visible Python implementation)
Advanced multi-agent orchestration: pipeline / workflow / msghub / reflection / plan / MapReduce
A2A protocol support (claimed ahead of Python v2)
Gateway: SSE / WebSocket / StreamableHTTP / AG-UI / Tool Offload / BackgroundTask / Schedule / MCP per-session & workspace, JWT authentication, OTel/LangSmith
gateway/app.go already has AppConfig + NewApp + RegisterAppRoutes (commented as mirroring Python's create_app())
service/ Storage (Memory + Redis) and entities (User / Session / AgentConfig / Credential encrypted / Schedule / StoredMessage / Snapshot)
CRUD endpoints for agents / sessions / credentials in gateway/service_handlers.go
gateway/agent_factory.go can build a ReActAgent from persisted AgentConfig + Credential
Task tools (tool/task/) already aligned with Python's four tools; HintBlock implemented; Tool Offload + hints injection done
Workspace (Local / Docker / E2B + MCP + Offloader), Schedule integration, production examples, extensive bench + e2e tests

Main Gaps to Close

1. Production-grade Web UI / Studio — the biggest user-visible gap. Python ships a full React/TS "new-studio" (60+ components, chat/credential/schedule/agent/skill/workspace management, i18n, tour, dynamic forms). Go has only a minimal static demo in examples/web_ui/. 2. Unified App/Service framework completeness — Python offers app.create_app(...) with lifespan auto-start of all managers, schedule restoration, full router registration, and rich storage records. Go has strong components but lacks a one-command bootstrap. 3. Credential abstraction — Python has a credential/ package (CredentialBase, per-provider subclasses, type discriminator, SecretStr, CredentialFactory with register / from_dict / list_schemas() for dynamic forms). Go's service.Credential is flat (provider + label + encrypted) with no typed models, schema endpoint, or factory. 4. Other abstraction gaps — no standalone top-level embedding/ package; single Docker template vs. Python's multiple Dockerfile.*.template files; less rich Agent/Session/Schedule data models (missing ContextConfig/ReActConfig, timezone/permission_mode/stateful ScheduleData fields, explicit credential_id on ChatModelConfig); tracing middleware organization. 5. End-to-end "Agent Service + Studio" example — Python pairs examples/agent_service with a full web UI; Go's production examples are strong but lack a rich companion UI.

Overall Strategy

Incremental evolution, not rewrite: map Python's good patterns (typed credentials + schemas, rich records, create_app-style API, startup lifecycle) onto idiomatic Go, reusing the existing gateway/service/session/workspace/agent_factory/schedule/tool_offload components.
Go philosophy: idiomatic structs/functions, interface abstractions (e.g., service.Storage), minimal external dependencies. UI should be self-contained Go (HTMX + templates or a minimal frontend), while keeping the AG-UI protocol complete so users can reuse the Python TS Studio.
Backward compatibility: new abstractions optional; existing production and multi_tenant_workspace examples keep working.
Verifiable: every phase passes go test ./... -race; new e2e tests; new examples start with one command and demonstrate CRUD + chat + schedule.
Priority: UI (user perception) + typed Credential + high-level App bootstrap (developer experience) > other polish.

Phased Roadmap

Phase 1: Core Abstraction Parity & Bootstrap

Build a new credential/ package mirroring Python: credential/base.go (CredentialBase), per-provider implementations (openai.go, anthropic.go, ... with Secret fields), credential/factory.go (register, from_map, list_schemas() returning JSON schemas, class lookup), Cipher integration for encryption.
Enrich service entities: AgentData with ContextConfig/ReActConfig, Credential.Data typed map, richer Schedule fields (timezone, permission_mode, stateful, chat_model_config), ChatModelConfig with credential_id; update memory/redis storage and handlers.
Strengthen gateway/app.go: convenience constructor (NewService / MustNew), auto-wiring of SessionManager / BackgroundTaskMgr / ToolOffload / WorkspaceManager, startup lifecycle (restore schedules, start scheduler, register default tools, defaults for permission and optional ReMe memory), new /credential/schemas route, improved AgentFactory for typed credentials.
Milestone: go test ./... -race green; typed OpenAI/Anthropic credentials round-trip; schemas endpoint returns usable JSON schemas.

Phase 2: Service Completeness & Lifecycle

Schedule restore at startup (mirroring Python's lifespan + scheduler.restore).
Convenient registration of a standard tool set (file + task + schedule + web + json + skillviewer + subagent) bound to workspace/permission.
Expose ToolOffloadMiddleware / hints via high-level AppConfig.
Align more Python schema/router fields; enhance agent_factory/session construction for dynamic injection of toolkit + memory + permission + workspace binding.
Milestone: persisted schedules auto-restore after restart; a new examples/full_service demonstrates end-to-end CRUD + scheduled tasks + background tool offload.

Phase 3: Workspace & Tool Polish + Embedding Package

Extend workspace/docker.go RenderDockerfile with multiple templates (install_pypi, install_src, node support, MCP sidecar); improve BuildImage / health checks.
Create a top-level embedding/ package: base interface, provider implementations (OpenAI, Ollama, Gemini), file embedding cache, dimension/modality support.
Add Meta-style tools (e.g., ResetTools) if useful; ensure SkillViewer + load_skill_tool register easily.
Milestone: varied Dockerfile rendering works; embedding package usable standalone for memory or RAG.

Phase 4: Rich Web UI / Studio (Closing the Biggest Gap)

Recommended main approach: a lightweight self-contained Studio in examples/studio or a studio/ package using Go html/template + HTMX (+ Tailwind Play CDN or templ). Covering: auth (register/login), Agents CRUD, Credentials with schema-driven dynamic forms, Sessions & Chat (integrating /v2/chat/stream or AG-UI SSE with multimodal, simple tool renderers, confirmation cards), Schedules (cron + timezone + permission_mode + stateful), Workspaces/MCP status, and model selection.
Auxiliary approach: polish AG-UI protocol support (gateway/agui.go) and document how to connect the Python TS Studio to the Go gateway (baseURL + auth headers); optional minimal TS/JS demo.
Not recommended now: a full 1:1 port of the 60+ component React app (high maintenance cost).
Milestone: after go run ./examples/production, a user can register, create credential + agent, chat, and create a working schedule in the browser.

Phase 5: Observability, Docs, Tests, Release

Wrap existing observability (OTel + LangSmith + hooks) into easy-to-use tracing middleware.
Update README/docs, migration guide, AGENTS.md; add unit/integration/e2e tests for new packages and bootstrap; keep -race green; CHANGELOG and release prep.
Optional forward-looking items (evaluation/finetune/voice) deferred.

Implementation Order & Parallelism

Phase 1 → Phase 2 → Phase 3 (partially parallelizable) → Phase 4 (depends on Phase 1 schemas and CRUD) → Phase 5. Embedding work and Docker templates can start early; UI design sketches can be prepared in advance.

Risks & Trade-offs

UI effort: lightweight HTMX UI estimated at 1–3 weeks for core features; a full React port is high-risk.
Credential refactor: must not break existing service.Credential + AgentFactory consumers — use a new package plus adapter layer.
Storage backward compatibility: new fields optional; old records migratable.
Dependencies: avoid heavy frontend frameworks; HTMX + minimal JS keeps deps low.
AG-UI compatibility: prioritize protocol stability so the Python UI becomes a "free" rich option.
Scope control: strict phase slicing, no gold-plating; each phase ends with demonstrable value.

Definition of Done (per phase)

go test ./... -race -count=1 passes
New features have unit / integration / e2e tests
Runnable examples demonstrating target flows (CRUD + chat + schedule + UI)
README / docs updated; no breaking public API changes (or a clear migration path)

Out of Scope (future evolution)

Agentic RL / finetuning
Full real-time voice multimodality (Go already has AudioModel + OpenAITTS + voice examples)
Distributed execution (early dist/ scaffolding exists)

Key File Mapping (Python → Go)

agentscope/app/create_app + lifespan + _manager/* + _router/* + storage/* → gateway/app.go + NewApp + service/Storage + gateway/*_handlers + session_manager + background_task + workspace_manager + schedule_* (goal: higher-level convenience constructor + auto-wiring)
agentscope/credential/* + CredentialFactory + list_schemas → new credential/ package + factory + /credential/schemas
agentscope/embedding/* → new embedding/ package
message/HintBlock + tool_offload_middleware → Go already has HintBlock + tool_offload.go (align usage)
workspace/_docker/ templates → extend workspace/docker.go + template files
examples/web_ui/frontend + examples/agent_service → Go examples/studio (lightweight) + AG-UI docs + upgraded production example
tool/_task/ → tool/task/ (already aligned)

Status: exploration complete; awaiting approval before implementation, starting with the credential package (the foundation for schemas and dynamic forms), tracked via a detailed todo list, with progress validated by tests and runnable examples.