System Overview¶

Lango is organized into six architectural layers. Each layer has a clear responsibility boundary, and dependencies flow strictly downward: Presentation depends on Agent, Agent depends on Intelligence, and all layers depend on Infrastructure. The MCP Integration, Blockchain, and P2P Economy layers sit alongside Agent and Infrastructure as specialized subsystems.

Architecture Diagram¶

graph TB
    subgraph Presentation["Presentation Layer"]
        CLI["CLI (Cobra)"]
        TUI["TUI"]
        TG["Telegram"]
        DC["Discord"]
        SL["Slack"]
        GW["Gateway<br/>(HTTP/WebSocket)"]
    end

    subgraph AgentLayer["Agent Layer"]
        ADK["ADK Agent<br/>(Google ADK v0.5.0)"]
        ORCH["Orchestration<br/>(Multi-Agent)"]
        TOOLS["Tools<br/>(exec, fs, browser,<br/>crypto, payment)"]
        SKILL["Skills<br/>(User-defined)"]
        A2A["A2A Protocol<br/>(Remote Agents)"]
        TCAT["Tool Catalog<br/>+ Middleware Chain"]
    end

    subgraph MCPLayer["MCP Client Layer"]
        MCP["MCP Server Manager<br/>(stdio, HTTP, SSE)"]
        MCPT["MCP Tool Adapter<br/>(mcp__server__tool)"]
    end

    subgraph Intelligence["Intelligence Layer"]
        KS["Knowledge Store<br/>(8-layer context)"]
        LE["Learning Engine<br/>(Self-Learning Graph)"]
        MEM["Observational Memory<br/>(Observer + Reflector)"]
        EMB["Embedding / RAG<br/>(Vector Search)"]
        GR["Graph Store<br/>(BoltDB Triple Store)"]
        GRAM["Graph RAG<br/>(Hybrid Retrieval)"]
        LIB["Librarian<br/>(Proactive Extraction)"]
    end

    subgraph Blockchain["Blockchain Layer"]
        PAY["Payment<br/>(USDC, X402)"]
        SA["Smart Account<br/>(ERC-7579 / ERC-4337)"]
        CONT["Contract Caller<br/>(EVM Read/Write)"]
    end

    subgraph P2PEconomy["P2P Economy Layer"]
        PRICING["Dynamic Pricing"]
        NEGOT["Negotiation"]
        ESCROW["Escrow<br/>(Milestone-based)"]
        BUDGET["Budget Guard"]
        RISK["Risk Assessment"]
        PAYGATE["Payment Gate"]
    end

    subgraph P2PNet["P2P Network Layer"]
        NODE["P2P Node<br/>(libp2p)"]
        DISC["Discovery<br/>(DHT + Gossip)"]
        PROTO["Protocol Handler"]
        POOL["Agent Pool<br/>(Health + Selection)"]
        TEAM["Team Coordination"]
        SETTLE["Settlement<br/>(On-chain USDC)"]
    end

    subgraph Observ["Observability Layer"]
        METRICS["Metrics Collector"]
        HEALTH["Health Registry"]
        AUDIT["Audit Recorder"]
        TOKEN["Token Tracker"]
    end

    subgraph Infra["Infrastructure Layer"]
        CFG["Config"]
        SEC["Security<br/>(Crypto, Secrets, KMS)"]
        SESS["Session Store<br/>(Ent/SQLite)"]
        LOG["Logging (Zap)"]
        PROV["AI Providers<br/>(OpenAI, Gemini, Claude)"]
        AUTO["Automation<br/>(Cron, Background,<br/>Workflow)"]
        EBUS["Event Bus<br/>(Typed Pub/Sub)"]
    end

    CLI --> GW
    TUI --> GW
    TG --> GW
    DC --> GW
    SL --> GW
    GW --> ADK
    ADK --> ORCH
    ADK --> TOOLS
    ADK --> SKILL
    ADK --> TCAT
    ORCH --> A2A
    TCAT --> MCP
    MCP --> MCPT
    ADK --> PROV
    ADK --> KS
    ADK --> MEM
    ADK --> EMB
    KS --> LE
    EMB --> GR
    GR --> GRAM
    KS --> LIB
    MEM --> LIB
    ADK --> SESS
    TOOLS --> SEC
    PAY --> SEC
    SA --> CONT
    AUTO --> ADK
    PROTO --> PAYGATE
    PAYGATE --> PRICING
    PRICING --> NEGOT
    ESCROW --> SETTLE
    BUDGET --> RISK
    POOL --> DISC
    TEAM --> PROTO
    NODE --> DISC
    METRICS --> EBUS
    AUDIT --> EBUS
    TOKEN --> EBUS

Layer Descriptions¶

Presentation Layer¶

The presentation layer handles all user-facing interactions. It contains no business logic -- each component is a thin adapter that accepts input, forwards it to the Agent layer via the Gateway, and formats the response for output.

Agent Layer¶

The agent layer is the core runtime. It manages the AI agent lifecycle, tool execution, prompt assembly, and multi-agent orchestration.

MCP Client Layer¶

The MCP client layer connects Lango to external tool servers via the Model Context Protocol. It discovers tools from configured MCP servers and adapts them into the agent's tool catalog.

Intelligence Layer¶

The intelligence layer provides the agent with persistent knowledge, learning capabilities, and semantic retrieval. All components are optional and enabled via configuration flags.

Blockchain Layer¶

The blockchain layer provides on-chain capabilities for payments, smart contract interaction, and account abstraction.

P2P Economy Layer¶

The P2P economy layer enables autonomous economic interactions between agents, including dynamic pricing, negotiation, escrow, and risk management.

P2P Network Layer¶

The P2P network layer provides decentralized agent communication, discovery, and coordination.

Observability Layer¶

The observability layer provides metrics collection, health monitoring, audit logging, and token usage tracking.

Infrastructure Layer¶

The infrastructure layer provides foundational services that all other layers depend on.

Key Design Decisions¶

Callback pattern for async processing. Stores expose SetEmbedCallback and SetGraphCallback methods. When a knowledge entry or memory observation is saved, the callback enqueues an async request to the corresponding buffer (EmbeddingBuffer or GraphBuffer). This avoids import cycles between the intelligence subsystems.

Optional subsystems with graceful degradation. Every intelligence component checks a config flag during initialization. If a component fails to initialize (missing dependency, database error), the application continues without it. The initKnowledge, initMemory, initEmbedding, initGraphStore functions all return nil on failure rather than terminating the application.

Context-aware prompt assembly. The ContextAwareModelAdapter wraps the base LLM and intercepts every GenerateContent call. It runs knowledge retrieval, RAG search, and memory lookup in parallel using errgroup, then assembles the results into an augmented system prompt before forwarding to the AI provider.

Tool adaptation layer. Internal tools use a simple agent.Tool struct with a map-based parameter definition. The adk.AdaptTool() function converts these to the ADK's tool.Tool interface with proper JSON Schema, allowing tools to be defined without depending on ADK types directly. MCP tools follow the same pattern through mcp.AdaptTool().

Event-driven observability. The observability layer uses the event bus for decoupled data collection. Tool execution events and token usage events are published by the toolchain middleware and model adapter respectively, then consumed by the metrics collector, audit recorder, and token tracker without direct dependencies.

Domain-specific wiring files. Application initialization is split across wiring_*.go files in internal/app/, each responsible for a single subsystem (e.g., wiring_mcp.go, wiring_payment.go, wiring_economy.go). This keeps the bootstrap code organized as the number of subsystems grows.