# trpc-group/trpc-agent-go architecture

> Architecture diagram of the GitHub repository trpc-group/trpc-agent-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trpc-group/trpc-agent-go
- Repository: https://github.com/trpc-group/trpc-agent-go

## Overview

##### Project Type & Purpose
- This is an open-source Go framework (library + CLI/HTTP servers) for building intelligent agent systems.
- It exposes a modular, layered API (packages) that you compose into “Runners” and “Agents,” integrates LLMs, tools, memory, knowledge, and telemetry.

##### High-Level Architecture & Main Components
A. Core Library
1. Runner
- Orchestrates end-to-end execution: session, telemetry, agent invocation, streaming events
2. Agent
- Interface implementations: LLMAgent, ChainAgent, ParallelAgent, CycleAgent, GraphAgent
3. Planner
- Decides strategy, tool selection, branching (chain/graph/cycle)
4. Executor
- Executes plan steps, invokes Tools or sub-Agents
5. Model Interface
- LLM wrappers (OpenAI, DeepSeek, etc.)
6. Tool Interface
- Tools: function, file ops, DuckDuckGo, MCP, code executor, etc.
B. Services & Stores
7. Session Service
- Manages per-user, per-session context and event streams (in-memory, Redis)
8. Memory Service
- Long-term storage of conversation state (in-memory, Redis)
9. Knowledge Service
- RAG: loaders, chunking, embedders, retrievers, vector stores (in-memory, elasticsearch, pgvector, tcvector)
10. Telemetry
- Tracing & metrics, hooks into runner/agent/model/tool layers, exporters (Langfuse, OpenTelemetry)
C. HTTP Servers & Examples
11. AGUI Server
- SSE endpoints for web UIs, adapter layer
12. A2A Server
- Agent-to-agent tunnel
13. Debug Server
- HTTP + OpenAPI, event replay

##### Component Relationships & Data Flows
- Runner → Agent
- Runner invokes Agent.Run(…) → returns a stream of events
- Agent → Planner → Model / Knowledge / Memory
- Planner generates a plan (sequence or graph of steps)
- May consult Knowledge Service for RAG retrieval
- May fetch Memory context
- Executor → Tools / Sub-Agents
- Steps that call Tools (e.g., function tool calls local function)
- Or delegate to sub-Agents (ChainAgent, ParallelAgent, GraphAgent)
- Model ↔ External LLM API
- Model interface sends chat prompts, receives streamed responses
- Session / Memory → Storage
- Reads/Writes session state or memory entries to in-memory store or Redis/DB
- Telemetry wraps all calls, emits traces/metrics to exporters
- HTTP Servers expose Runner/Agent as REST/SSE endpoints, adapt requests into Runner.Run calls and stream events over HTTP

##### Architectural Patterns & Design Principles
- Layered Modular Architecture: clear separation between orchestration (Runner), decision logic (Planner), execution (Executor), and I/O (Model, Tool, Services)
- Plugin/Interface-Driven: each core concept (Agent, Model, Tool, Session, Memory, Knowledge) is defined by an interface, enabling multiple implementations
- Adapter Pattern: Server packages adapt the core Runner/Agent API to HTTP/SSE or other protocols
- Composite Pattern: Multi-agent types (Chain, Parallel, Graph, Cycle) nest or parallelize sub-agents
- Dependency Injection: Users supply tools, memory services, telemetry configurations via functional options

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Library
    subgraph "Core Library"
        direction TB
        Runner["Runner"]:::core
        Agent["Agent"]:::core
        subgraph "Agent Types"
            direction TB
            LLMAgent["LLMAgent"]:::core
            ChainAgent["ChainAgent"]:::core
            ParallelAgent["ParallelAgent"]:::core
            CycleAgent["CycleAgent"]:::core
            GraphAgent["GraphAgent"]:::core
            A2AAgent["A2AAgent"]:::core
        end
        Planner["Planner"]:::core
        Executor["Executor"]:::core
        ModelInterface["Model Interface"]:::core
        ToolInterface["Tool Interface"]:::core
    end

    %% Services & Stores
    subgraph "Services & Stores"
        direction TB
        SessionService["Session Service"]:::service
        MemoryService["Memory Service"]:::service
        KnowledgeService["Knowledge Service"]:::service
        Telemetry["Telemetry"]:::service
    end

    %% External Systems
    subgraph "External"
        direction TB
        LLMAPI["LLM API"]:::external
        RedisExt["Redis"]:::external
        Postgres["PostgreSQL"]:::external
        Elasticsearch["Elasticsearch"]:::external
    end

    %% HTTP Servers & UIs
    subgraph "HTTP Servers & UI"
        direction TB
        AGUIServer["AGUI Server"]:::http
        A2AServer["A2A Server"]:::http
        DebugServer["Debug Server"]:::http
    end

    %% Relationships
    Runner -->|"invokes"| Agent
    Agent -->|"plans via"| Planner
    Planner -->|"uses"| ModelInterface
    Planner -->|"fetches"| KnowledgeService
    Planner -->|"reads"| MemoryService
    Agent -->|"executes"| Executor
    Executor -->|"calls"| ToolInterface
    Executor -->|"delegates to"| LLMAgent
    Executor -->|"delegates to"| ChainAgent
    Executor -->|"delegates to"| ParallelAgent
    Executor -->|"delegates to"| CycleAgent
    Executor -->|"delegates to"| GraphAgent
    Executor -->|"delegates to"| A2AAgent
    ModelInterface -->|"↔ stream"| LLMAPI
    Runner -.->|"session context"| SessionService
    Agent -.->|"memory context"| MemoryService
    SessionService -->| reads/writes | RedisExt
    MemoryService -->| reads/writes | RedisExt
    KnowledgeService -->|stores→| Elasticsearch
    KnowledgeService -->|stores→| Postgres
    Telemetry -->|hooks into| Runner
    Telemetry -->|hooks into| Agent
    Telemetry -->|hooks into| Planner
    Telemetry -->|hooks into| Executor
    Telemetry -->|hooks into| ModelInterface
    Telemetry -->|hooks into| ToolInterface
    AGUIServer -->|"calls"| Runner
    A2AServer -->|"calls"| Runner
    DebugServer -->|"calls"| Runner
    AGUIServer -->|"streams SSE"| Runner
    DebugServer -->|"streams replay"| Runner

    %% Click Events
    click Runner "https://github.com/trpc-group/trpc-agent-go/blob/main/runner/runner.go"
    click Agent "https://github.com/trpc-group/trpc-agent-go/blob/main/agent/agent.go"
    click LLMAgent "https://github.com/trpc-group/trpc-agent-go/blob/main/agent/llmagent/llm_agent.go"
    click ChainAgent "https://github.com/trpc-group/trpc-agent-go/blob/main/agent/chainagent/chain_agent.go"
    click ParallelAgent "https://github.com/trpc-group/trpc-agent-go/blob/main/agent/parallelagent/parallel_agent.go"
    click CycleAgent "https://github.com/trpc-group/trpc-agent-go/blob/main/agent/cycleagent/cycle_agent.go"
    click GraphAgent "https://github.com/trpc-group/trpc-agent-go/blob/main/agent/graphagent/graph_agent.go"
    click A2AAgent "https://github.com/trpc-group/trpc-agent-go/blob/main/agent/a2aagent/a2a_agent.go"
    click Planner "https://github.com/trpc-group/trpc-agent-go/blob/main/planner/planner.go"
    click BuiltinPlanner "https://github.com/trpc-group/trpc-agent-go/blob/main/planner/builtin/builtin_planner.go"
    click ReactPlanner "https://github.com/trpc-group/trpc-agent-go/blob/main/planner/react/react_planner.go"
    click Executor "https://github.com/trpc-group/trpc-agent-go/blob/main/graph/executor.go"
    click ModelInterface "https://github.com/trpc-group/trpc-agent-go/blob/main/model/model.go"
    click OpenAIModel "https://github.com/trpc-group/trpc-agent-go/blob/main/model/openai/openai.go"
    click ModelRegistry "https://github.com/trpc-group/trpc-agent-go/blob/main/model/registry.go"
    click ToolInterface "https://github.com/trpc-group/trpc-agent-go/blob/main/tool/tool.go"
    click FunctionTool "https://github.com/trpc-group/trpc-agent-go/blob/main/tool/function/function_tool.go"
    click FileTool "https://github.com/trpc-group/trpc-agent-go/blob/main/tool/file/file.go"
    click DuckDuckGoTool "https://github.com/trpc-group/trpc-agent-go/blob/main/tool/duckduckgo/duckduckgo.go"
    click MCPTool "https://github.com/trpc-group/trpc-agent-go/blob/main/tool/mcp/tool.go"
    click TransferTool "https://github.com/trpc-group/trpc-agent-go/blob/main/tool/transfer/transfer_tool.go"
    click SessionService "https://github.com/trpc-group/trpc-agent-go/blob/main/session/session.go"
    click InMemorySession "https://github.com/trpc-group/trpc-agent-go/blob/main/session/inmemory/service.go"
    click RedisSession "https://github.com/trpc-group/trpc-agent-go/blob/main/session/redis/service.go"
    click MemoryService "https://github.com/trpc-group/trpc-agent-go/blob/main/memory/memory.go"
    click InMemoryMemory "https://github.com/trpc-group/trpc-agent-go/blob/main/memory/inmemory/service.go"
    click RedisMemory "https://github.com/trpc-group/trpc-agent-go/blob/main/memory/redis/service.go"
    click KnowledgeService "https://github.com/trpc-group/trpc-agent-go/blob/main/knowledge/knowledge.go"
    click Chunking "https://github.com/trpc-group/trpc-agent-go/blob/main/knowledge/chunking/chunking.go"
    click DocumentLoaders "https://github.com/trpc-group/trpc-agent-go/blob/main/knowledge/document/document.go"
    click Embedders "https://github.com/trpc-group/trpc-agent-go/blob/main/knowledge/embedder/openai/openai.go"
    click Embedders2 "https://github.com/trpc-group/trpc-agent-go/blob/main/knowledge/embedder/gemini/gemini.go"
    click Retriever "https://github.com/trpc-group/trpc-agent-go/blob/main/knowledge/retriever/retriever.go"
    click VectorStores "https://github.com/trpc-group/trpc-agent-go/tree/main/knowledge/vectorstore/"
    click Telemetry "https://github.com/trpc-group/trpc-agent-go/blob/main/internal/telemetry/telemetry.go"
    click LangfuseExporter "https://github.com/trpc-group/trpc-agent-go/blob/main/telemetry/langfuse/exporter.go"
    click Metrics "https://github.com/trpc-group/trpc-agent-go/blob/main/telemetry/metric/metric.go"
    click Tracing "https://github.com/trpc-group/trpc-agent-go/blob/main/telemetry/trace/trace.go"
    click AGUIServer "https://github.com/trpc-group/trpc-agent-go/tree/main/server/agui/"
    click A2AServer "https://github.com/trpc-group/trpc-agent-go/blob/main/server/a2a/server.go"
    click DebugServer "https://github.com/trpc-group/trpc-agent-go/blob/main/server/debug/server.go"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef service fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef http fill:#FFD580,stroke:#000,stroke-width:1pxstart
```
