GoAgent Source Deep Dive Series

This series walks through the GoAgent multi-agent framework implementation, from API client to embedding service.

GoAgent is a custom multi-agent framework in Go. It is not a wrapper around an existing framework — it is built from scratch to explore how agents can collaborate, remember, and execute tasks through a clean API boundary.

The series follows one narrative thread: Problem → Limitations of existing approaches → GoAgent's approach → Architecture naturally emerges.

Articles

  1. API Client: Converging Framework Capabilities Into a Usable Entry Point
  2. LLM Client: Unifying Multi-Model Call Boundaries
  3. Agent System: The Leader/Sub-Agent Collaboration Skeleton
  4. AHP Protocol: Messages, Queues, and Heartbeats
  5. Memory System: Sessions, Tasks, and Distilled Memories
  6. Tool System: Registration, Capability Matching, and Execution
  7. Workflow Engine: DAG-Based Agent Orchestration
  8. Storage and Retrieval: PostgreSQL, pgvector, and Hybrid Search
  9. Embedding Service: The Engineering Boundary of Vector Generation

Reading Order

Read in the numbered order above. Each article builds on the previous one:

  • Start with API Client to understand how internal modules are isolated from external callers.
  • LLM Client shows how the framework stays provider-agnostic.
  • Agent System introduces the leader/sub-agent collaboration model.
  • AHP Protocol explains how agents communicate.
  • Memory System covers sessions, tasks, and distilled memories.
  • Tool System shows how agents execute actions, not just talk.
  • Workflow Engine handles multi-step task orchestration.
  • Storage and Retrieval covers where memories and knowledge live.
  • Embedding Service closes the loop with vector generation.

Source Reading Map

  • Entry: api/client.go, api/simple_client.go, api/workflow_client.go
  • LLM: internal/llm/output/, internal/llm/provider/
  • Agents: internal/agents/leader/, internal/agents/sub/
  • Protocol: internal/protocol/ahp/
  • Memory: internal/memory/
  • Tools: internal/tools/
  • Workflow: internal/workflow/
  • Storage: internal/storage/postgres/
  • Embedding: internal/embedding/

Writing Principles

  • Describe implemented source-code behavior, not wishful roadmap items.
  • Include code references so readers can verify claims in the repository.
  • Use Mermaid diagrams only; no screenshots or image dependencies.
  • Analyze design trade-offs, not just advantages.