# akki0511/agentconnect architecture

> Architecture diagram of the GitHub repository akki0511/agentconnect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akki0511/agentconnect
- Repository: https://github.com/akki0511/agentconnect

## Overview

##### Project type and purpose
- AgentConnect is primarily a decentralized multi-agent framework/library written in Python, augmented with a command-line interface and accompanied by demo full-stack apps (FastAPI backend + React frontend).
- Its goal is to let independent AI “agents” discover peers, exchange messages and payments securely, and coordinate complex workflows without a central brain.

##### File structure
- Top-level:
- `agentconnect/` – core library.
- `cli.py` – entry point for CLI.
- `demos/` – demo applications (FastAPI API + React UI).
- `examples/` – standalone example scripts.
- `docs/` – Sphinx docs.
- Inside `agentconnect/`:
- `agents/` – agent implementations (AI, human, Telegram, plus hooks/handlers).
- `communication/` – registry & hub protocols.
- `core/` – abstract agent, messaging, exceptions, registry base.
- `prompts/` – prompt templates, chain factory, custom tools.
- `providers/` – LLM integrations (OpenAI, Anthropic, etc.) + provider factory.
- `utils/` – callbacks, logging, payment, wallet.
- The demo backend (`demos/api/`) uses FastAPI routers, models, middleware, WebSockets. The UI (`demos/ui/frontend/`) is a React/Vite app using API + WebSocket services.

##### Extract architectural insights from the README
- Three core pillars:
1. Decentralized Agent Registry (capability discovery)
2. Communication Hub (secure, peer-to-peer messaging)
3. Independent Agent Systems (self-managed lifecycle, autonomy)
- External dependencies: LLM providers, Coinbase AgentKit for payments, LangSmith for observability.

##### Components & Interactions
a. Main components:
- **Client Layer**:
- CLI (`agentconnect --demo`, `agentconnect` commands)
- React Frontend (HTTP + WS)
- **Demo API Layer**:
- FastAPI servers (chat_server, routes, middleware)
- WebSocket endpoint for real-time chat
- **AgentConnect Core**:
- **Registry Service** (capability publishing & discovery)
- **Communication Hub** (message router)
- **Agent Runtime** (AI/Human/Telegram agents modules)
- **Prompts Engine** (templates, chain_factory, custom tools)
- **Provider Factory** (selects OpenAI/Anthropic/Groq/Google backends)
- **Payment & Trust** (wallet_manager, payment_helper, crypto verification)
- **Utilities** (logging_config, callbacks, interaction_control)
- **External Services**:
- LLM Providers (OpenAI, Anthropic, etc.)
- Coinbase CDP / AgentKit (on-chain payment)
- LangSmith (observability/tracing)

b. Relationships & data flows:
1. **Frontend → Backend**: HTTP requests (login, fetch sessions) and WebSocket streams of chat messages.
2. **Backend → Core Library**: FastAPI invokes `agentconnect` library functions (spin up agent sessions, call registry/hub).
3. **Agent Runtime**: Agents publish capabilities to the **Registry**, then subscribe/listen via the **Communication Hub**.
4. **Inter-Agent Messaging**: Hub routes signed messages directly between agent nodes (p2p).
5. **Agent Decision-Making**: Agents call into the **Provider Factory** → chosen LLM API → process “prompt” via the **Prompts Engine**.
6. **Payments**: Agents use **payment_helper** to trigger Coinbase CDP transactions.
7. **Observability**: All message exchanges and tool calls emit LangSmith traces/callbacks.

c. Architectural patterns & principles:
- **Decentralized, modular**: No single “controller”—each agent is a self-contained module.
- **Plug-in extensibility**: Providers, prompts, agents, and protocols are swappable via factory patterns.
- **Separation of concerns**: CLI/UI, API server, core library, external services.
- **Secure p2p messaging**: Cryptographic signing and verification at the hub.

d. Key technologies/frameworks:
- Python 3.11+, Poetry
- FastAPI for demo backend
- Vite + React + TypeScript for demo UI
- Sphinx for docs
- WebSockets for real-time chat
- External REST/gRPC APIs: OpenAI, Anthropic, Coinbase, LangSmith

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        CLI["CLI"]:::client
        ReactUI["React Frontend"]:::client
        Examples["Examples"]:::client
    end

    subgraph "Server/API Layer"
        APIRoutes["HTTP Routes\n(FastAPI)"]:::server
        WS["WebSocket Endpoint"]:::server
        Runner["Demo Orchestration\n(run_demo.py)"]:::server
    end

    subgraph "Core Library"
        subgraph "Decentralized Services"
            Registry["Registry Service"]:::core
            Hub["Communication Hub"]:::core
        end
        Agents["Agent Runtime"]:::core
        Prompts["Prompts Engine"]:::core
        ProviderFactory["Provider Factory"]:::core
        Payment["Payment & Trust"]:::core
        Utils["Utilities"]:::core
    end

    subgraph "External Services"
        LLM["LLM Providers"]:::external
        PaymentChain["Coinbase AgentKit"]:::external
        Observability["LangSmith"]:::external
    end

    CLI -->|HTTP/REST| APIRoutes
    ReactUI -->|HTTP/REST| APIRoutes
    ReactUI -->|WebSocket| WS

    Runner -->|orchestrates| APIRoutes
    Runner -->|orchestrates| WS

    APIRoutes -->|invokes| Agents
    WS -->|invokes| Agents

    Agents -->|publish/subscribe| Registry
    Agents -->|message routing| Hub
    Registry -.->|discover| Agents
    Hub -->|route messages| Agents

    Agents -->|calls| ProviderFactory
    ProviderFactory -->|LLM API| LLM

    Agents -->|use| Prompts
    Agents -->|trigger payments| Payment
    Payment -->|on-chain tx| PaymentChain

    Registry -.->|tracing| Observability
    Hub -.->|tracing| Observability
    Agents -.->|tracing| Observability
    Prompts -.->|tracing| Observability
    ProviderFactory -.->|tracing| Observability
    Payment -.->|tracing| Observability
    Utils -.->|tracing| Observability

    click CLI "https://github.com/akki0511/agentconnect/blob/main/agentconnect/cli.py"
    click ReactUI "https://github.com/akki0511/agentconnect/tree/main/demos/ui/frontend/"
    click APIRoutes "https://github.com/akki0511/agentconnect/tree/main/demos/api/routes/"
    click WS "https://github.com/akki0511/agentconnect/blob/main/demos/api/chat_server.py"
    click Runner "https://github.com/akki0511/agentconnect/blob/main/demos/run_demo.py"
    click Registry "https://github.com/akki0511/agentconnect/tree/main/agentconnect/core/registry/"
    click Hub "https://github.com/akki0511/agentconnect/blob/main/agentconnect/communication/hub.py"
    click Hub "https://github.com/akki0511/agentconnect/tree/main/agentconnect/communication/protocols/"
    click Agents "https://github.com/akki0511/agentconnect/tree/main/agentconnect/agents/"
    click Prompts "https://github.com/akki0511/agentconnect/tree/main/agentconnect/prompts/"
    click ProviderFactory "https://github.com/akki0511/agentconnect/blob/main/agentconnect/providers/provider_factory.py"
    click ProviderFactory "https://github.com/akki0511/agentconnect/tree/main/agentconnect/providers/"
    click Payment "https://github.com/akki0511/agentconnect/blob/main/agentconnect/utils/payment_helper.py"
    click Payment "https://github.com/akki0511/agentconnect/blob/main/agentconnect/utils/wallet_manager.py"
    click Payment "https://github.com/akki0511/agentconnect/blob/main/agentconnect/core/payment_constants.py"
    click Utils "https://github.com/akki0511/agentconnect/tree/main/agentconnect/utils/"
    click Examples "https://github.com/akki0511/agentconnect/tree/main/examples/"

    classDef client fill:#ccf,stroke:#036
    classDef server fill:#cfc,stroke:#063
    classDef core fill:#fcf,stroke:#630
    classDef external fill:#eee,stroke:#666,stroke-dasharray: 5 5
```
