How superagenticai/agenspy works
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)