# superagenticai/agenspy architecture

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

- Interactive diagram: https://gitdiagram.com/superagenticai/agenspy
- Repository: https://github.com/superagenticai/agenspy

## Overview

##### Project Type and Purpose
- Agenspy is an open-source Python framework and CLI tool for building “protocol-first” AI agents on top of DSPy.
- It provides:
- A Python library (agents, protocols, servers, utilities)
- A command-line interface (agenspy CLI)
- Reference implementations of MCP and Agent2Agent protocols (clients and servers)
- Example scripts and tests for demonstration and verification

##### File-Structure Analysis
Top-level:
- setup.py / pyproject.toml / requirements.txt → packaging & dependencies
- README.md, docs/, examples/, tests/ → documentation, usage examples, and test suite
Core package (agenspy/):
- agents/ → BaseAgent, GitHub-specific agent, MultiProtocolAgent
- cli/ → main entrypoint + subcommands (agent, server, workflow, status, etc.)
- protocols/ → protocol definitions and clients/servers for MCP and Agent2Agent
- servers/ → pre-built Python and GitHub MCP server implementations
- utils/ → protocol_registry (plugin for protocol implementations), server_manager

##### README Insights
- Three logical layers described in “🏗️ Architecture”: DSPy Agent Layer → Protocol Layer → Protocol Implementations (MCP/A2A)
- Emphasis on: session/capability management, chain-of-thought, tool registration, and extensibility

##### Components
1. User Interface
- CLI (agenspy commands)
- Python API (import agenspy in scripts)
2. DSPy Agent Layer
- BaseAgent (ChainOfThought, Predict, ReAct)
- Custom agents (GitHubAgent, CodeReviewAgent, MultiProtocolAgent)
3. Protocol Layer
- ProtocolManager / protocol_registry (handles sessions, capabilities, routing)
4. Protocol Implementations
- MCPClient (client.py)
- Agent2AgentClient (client.py)
- MCPServer / PythonMCPServer / GitHubMCPServer
5. External Services & Tools
- GitHub APIs (for PR review tools)
- Model providers (OpenAI via dspy.LM)
- Custom tools registered at MCP servers
- User → CLI / Python API → calls Agent Layer
- Agent Layer → ProtocolManager → selects appropriate Protocol Client
- Protocol Client → communicates over network (mcp:// or a2a://) → Protocol Server
- Protocol Server → executes registered tools or calls external services (e.g., GitHub API, local handler)
- Model calls (dspy.LM) occur inside Agent Layer or Protocol Layer as needed
c. Architectural Patterns & Principles
- Layered architecture (clear separation of concerns)
- Plugin/registry pattern (protocol_registry for dynamic protocol implementations)
- Extensibility (add new protocols, agents, tools via registration)
- Modular packaging (agents/, protocols/, servers/, cli/, utils/)
d. Key Technologies & Frameworks
- Python (packaging via setuptools/pyproject.toml)
- DSPy (dspy) for core agent logic and language-model interface
- Click or argparse (implicitly used in CLI main.py and commands)
- pytest for test suite under tests/
- Optional Node.js server for MCP (docs mention JavaScript server)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "User Interface" 
        direction TB
        CLI["CLI (agenspy commands)"]:::ui
        PYAPI["Python API (agenspy/__init__.py)"]:::ui
    end

    %% Agent Layer
    subgraph "DSPy Agent Layer"
        direction TB
        BaseAgent["BaseAgent"]:::agent
        GitHubAgent["GitHubAgent"]:::agent
        MultiProtocolAgent["MultiProtocolAgent"]:::agent
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        ProtBase["Protocol Base Definitions"]:::protocolLayer
        ProtocolMgr["ProtocolRegistry / ProtocolManager"]:::protocolLayer
    end

    %% Protocol Implementations - Clients
    subgraph "Protocol Clients" 
        direction TB
        MCPClient["MCPClient"]:::clientImpl
        A2AClient["Agent2AgentClient"]:::clientImpl
    end

    %% Protocol Implementations - Servers
    subgraph "Protocol Servers" 
        direction TB
        MCPServerProt["MCPServer"]:::serverImpl
        PyMCPServ["PythonMCPServer"]:::serverImpl
        GHMCPServ["GitHubMCPServer"]:::serverImpl
    end

    %% External & Tools
    subgraph "External Services & Tools"
        direction TB
        GitHubAPI["GitHub API"]:::external
        ModelProv["Model Providers (dspy.LM)"]:::external
        CustomTools["Registered Custom Tools"]:::external
    end

    %% Data Flow
    CLI -->|"invoke"| BaseAgent
    PYAPI -->|"call"| BaseAgent

    BaseAgent -->|"uses"| ProtocolMgr
    GitHubAgent -->|"extends"| BaseAgent
    MultiProtocolAgent -->|"extends"| BaseAgent

    ProtocolMgr -->|"selects"| ProtBase
    ProtocolMgr -->|"routes to"| MCPClient
    ProtocolMgr -->|"routes to"| A2AClient

    MCPClient -->|"mcp://"| MCPServerProt
    A2AClient -->|"a2a://"| MCPServerProt

    MCPServerProt -->|"manages sessions"| ProtBase
    MCPServerProt -->|"executes tools"| CustomTools
    MCPServerProt -->|"calls external"| GitHubAPI

    PyMCPServ -->|"variant of MCPServer"| MCPServerProt
    GHMCPServ -->|"variant of MCPServer"| MCPServerProt

    BaseAgent -->|"LM call"| ModelProv
    ProtocolMgr -->|"LM call"| ModelProv

    %% Click Events
    click CLI "https://github.com/superagenticai/agenspy/blob/main/agenspy/cli/main.py"
    click PYAPI "https://github.com/superagenticai/agenspy/blob/main/agenspy/__init__.py"
    click BaseAgent "https://github.com/superagenticai/agenspy/blob/main/agenspy/agents/base_agent.py"
    click GitHubAgent "https://github.com/superagenticai/agenspy/blob/main/agenspy/agents/github_agent.py"
    click MultiProtocolAgent "https://github.com/superagenticai/agenspy/blob/main/agenspy/agents/multi_protocol_agent.py"
    click ProtocolMgr "https://github.com/superagenticai/agenspy/blob/main/agenspy/utils/protocol_registry.py"
    click MCPClient "https://github.com/superagenticai/agenspy/blob/main/agenspy/protocols/mcp/client.py"
    click A2AClient "https://github.com/superagenticai/agenspy/blob/main/agenspy/protocols/agent2agent/client.py"
    click ProtBase "https://github.com/superagenticai/agenspy/blob/main/agenspy/protocols/base.py"
    click MCPServerProt "https://github.com/superagenticai/agenspy/blob/main/agenspy/protocols/mcp/server.py"
    click PyMCPServ "https://github.com/superagenticai/agenspy/blob/main/agenspy/servers/mcp_python_server.py"
    click GHMCPServ "https://github.com/superagenticai/agenspy/blob/main/agenspy/servers/github_mcp_server.py"

    %% Styles
    classDef ui fill:#BBEFFF,stroke:#333,stroke-width:1px;
    classDef agent fill:#CFFCCC,stroke:#333,stroke-width:1px;
    classDef protocolLayer fill:#FFF3B0,stroke:#333,stroke-width:1px;
    classDef clientImpl fill:#FFD1A4,stroke:#333,stroke-width:1px;
    classDef serverImpl fill:#FFB085,stroke:#333,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px;
```
