agenspy

Agenspy (Agentic DSPy) 🚀

Agenspy (Agentic DSPy) is a protocol-first AI agent framework built on top of DSPy, designed to create sophisticated, production-ready AI agents with support for multiple communication protocols including MCP (Model Context Protocol) and Agent2Agent.

🌟 Features

• Protocol-First Architecture: Built around communication protocols rather than individual tools
• Multi-Protocol Support: Native support for MCP, Agent2Agent, and extensible for future protocols
• DSPy Integration: Leverages DSPy's powerful optimization and module composition
• Comprehensive CLI: Full-featured command-line interface for managing agents and workflows
• Python & JavaScript Servers: Support for both Python and Node.js MCP servers
• Automatic Connection Management: Protocol-level session and capability handling

📦 Installation

Basic Installation

pip install agenspy

With MCP Support

For enhanced functionality with the Model Context Protocol, install with MCP support:

pip install "agenspy[mcp]"

Development Installation

To contribute to Agenspy or work with the latest development version:

git clone https://github.com/superagenticai/Agenspy.git
cd Agenspy
pip install -e ".[dev]"

🚀 Quick Start

Basic MCP Agent

Agenspy makes it easy to create AI agents that can interact with MCP servers. Here's a simple example of creating a pull request review agent:

import dspy
from agenspy import create_mcp_pr_review_agent

# Configure DSPy with your preferred language model
lm = dspy.LM('openai/gpt-4o-mini')
dspy.configure(lm=lm)

# Create an MCP agent connected to a GitHub server
agent = create_mcp_pr_review_agent("mcp://github-server:8080")

# Use the agent to review a pull request
result = agent(
    pr_url="https://github.com/org/repo/pull/123",
    review_focus="security"
)

print(f"Review: {result.review_comment}")
print(f"Status: {result.approval_status}")

Multi-Protocol Agent (Experimental)

Agenspy supports multiple communication protocols simultaneously. Here's how to create an agent that can use both MCP and Agent2Agent protocols:

from agenspy import MultiProtocolAgent, MCPClient, Agent2AgentClient

# Create a multi-protocol agent
agent = MultiProtocolAgent("my-agent")

# Add protocol clients
mcp_client = MCPClient("mcp://github-server:8080")
a2a_client = Agent2AgentClient("tcp://localhost:9090", "my-agent")

agent.add_protocol(mcp_client)
agent.add_protocol(a2a_client)

# The agent will automatically route to the best protocol
result = agent("Analyze this repository for security issues")

Custom Agent with Tools

You can create custom agents with specialized functionality. Here's an example of a code review agent:

import asyncio
import dspy
from agenspy import BaseAgent
from typing import Dict, Any

class CodeReviewAgent(BaseAgent):
    def __init__(self, name: str):
        super().__init__(name)
        
    async def review_code(self, code: str, language: str) -> Dict[str, Any]:
        """Review code for potential issues."""
        # Your custom review logic here
        return {
            "score": 0.85,
            "issues": ["Consider adding error handling", "Document this function"],
            "suggestions": ["Use list comprehension for better performance"]
        }
    
    async def forward(self, **kwargs) -> dspy.Prediction:
        """Process agent request."""
        code = kwargs.get("code", "")
        language = kwargs.get("language", "python")
        result = await self.review_code(code, language)
        return dspy.Prediction(**result)

async def main():
    # Configure DSPy with your preferred language model
    lm = dspy.LM('openai/gpt-4o-mini')
    dspy.configure(lm=lm)
    
    # Create and use the agent
    agent = CodeReviewAgent("code-reviewer")
    result = await agent(code="def add(a, b): return a + b", language="python")
    print("Review Results:", result)

# Run the async main function
if __name__ == "__main__":
    asyncio.run(main())

Python MCP Server

Launch a Python MCP server with custom tools:

from agentic_dspy.servers import GitHubMCPServer  
  
# Create and start Python MCP server 
server = GitHubMCPServer(port=8080)  
  
# Add custom tools 
async def custom_tool(param: str):  
    return f"Processed: {param}"  
  
server.register_tool(  
    "custom_tool",  
    "A custom tool",  
    {"param": "string"},  
    custom_tool  
)  
  
server.start()

🏗️ Architecture

Agenspy provides a protocol-first approach to building AI agents:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   DSPy Agent    │───>│  Protocol Layer  │───>│  MCP/A2A/etc    │
│                 │    │                  │    │                 │
│ • ChainOfThought│    │ • Connection Mgmt│    │ • GitHub Tools  │
│ • Predict       │    │ • Capabilities   │    │ • File Access   │
│ • ReAct         │    │ • Session State  │    │ • Web Search    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Core Components

1. DSPy Agent Layer

   • Implements the core agent logic
   • Handles tool registration and execution
   • Manages conversation state

2. Protocol Layer

   • Handles communication between agents
   • Manages protocol-specific details
   • Provides consistent interface to agents

3. Protocol Implementations

   • MCP (Model Context Protocol): For tool and model interactions
   • Agent2Agent Protocol: For direct agent-to-agent communication
   • Extensible architecture for custom protocol implementations

Advanced Usage

Custom MCP Server

Agenspy allows you to create custom MCP servers with specialized functionality. Here's an example of creating a custom MCP server with a custom operation:

from agenspy.servers.mcp_python_server import PythonMCPServer
import asyncio

class CustomMCPServer(PythonMCPServer):
    def __init__(self, port: int = 8080):
        super().__init__(name="custom-mcp-server", port=port)
        self.register_tool(
            name="custom_operation",
            description="A custom operation that processes parameters",
            parameters={
                "type": "object",
                "properties": {
                    "param1": {"type": "string", "description": "First parameter"},
                    "param2": {"type": "integer", "description": "Second parameter"}
                },
                "required": ["param1", "param2"]
            },
            handler=self.handle_custom_op
        )

    async def handle_custom_op(self, **kwargs):
        """Handle custom operation with parameters."""
        param1 = kwargs.get("param1")
        param2 = kwargs.get("param2")
        return f"Processed {param1} with {param2}"

# Start the server
if __name__ == "__main__":
    server = CustomMCPServer(port=8080)
    print("Starting MCP server on port 8080...")
    server.start()

🖥️ Command Line Interface

Agenspy provides a command-line interface for managing agents and protocols:

# Show help and available commands
agenspy --help

Some Useful CLI Commands

• Run agent PR Review Agent using Real MCP server:

agenspy agent run "Review PR https://github.com/stanfordnlp/dspy/pull/8277" --real-mcp

• Test protocol server:

agenspy protocol test mcp   

• Run example:

agenspy demo github-pr

📚 Documentation

For detailed documentation, including API reference, examples, and advanced usage, please visit our documentation site. (coming soon)

🧪 Testing

Run the test suite with:

pytest tests/

📚 Examples

See the examples/ directory for complete examples: Get your OpenAI API key OPENAI_API_KEY from here and optionally GITHUB_TOKEN from here and set as ENV variables. You might also need to install nodejs and npm to run the nodejs server.

• basic_mcp_demo.py - Simple MCP agent
• comprehensive_mcp_demo.py - Comprehensive MCP agent
• github_pr_review.py - GitHub PR review agent
• multi_protocol_demo.py - Multi-protocol agent (Experimental Mock)
• python_server_demo.py - Python MCP server

Run the examples with:

agenspy demo github-pr

Or Run manually using Python:

python examples/github_pr_review.py

🔗 Resources

• DSPy Documentation
• Model Context Protocol
• Agent2Agent Protocol
• GitHub Repository

🚀 Future Roadmap

Merge into DSPy

The end goal is to merge this tool in the dspy main repo and make it a first-class citizen of the DSPy ecosystem. However, if it doesn't fit there then it can be used independently as a protocol-first AI agent framework.

Get DSPy Listed in Google A2A Agent Directory

Implementations of A2A and Get DSPy Listed in A2A Agent Directory (here)[https://github.com/google/A2A/blob/main/samples/python/agents/README.md] by building DSPy agents that utilize the A2A protocol.

Future Work

Alternately, Agenspy can be developed independently as a protocol-first AI agent framework. Here are some food for thought for future work:

• Protocol Layer: WebSocket and gRPC support for real-time, high-performance agent communication
• Agent Framework: Enhanced orchestration, state management, and network discovery
• Production Readiness: Monitoring, load balancing, and fault tolerance features
• Developer Tools: Improved CLI, web dashboard, and debugging utilities
• Ecosystem: Cloud integrations and database adapters for popular services

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to contribute to the project.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📬 Contact

For questions and support, please open an issue on our GitHub repository.

🙏 Acknowledgments

• The DSPy team for their amazing framework