Skip to content
/ a2a-go Public

a2a‑go is a reference Go implementation of the Agent‑to‑Agent (A2A) protocol by Google, including the proposed interoperability with the Model Context Protocol (MCP) from Anthropic.

License

Unlicense license
3 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

TheApeMachine/a2a-go

BranchesTags

Repository files navigation

🌈 A2A‑Go

"Combine A2A and MCP to create advanced, distributed agentic systems!"

A2A-Go is a comprehensive framework for building scalable, distributed agentic AI systems with built-in VPN capabilities. It promotes a microservice architecture where agents and tools operate as independent services, deployable locally or across a network. The framework implements the Agent-to-Agent (A2A) protocol and utilizes the Model Context Protocol (MCP) for standardized tool interaction and data exchange.

Go CI/CD Go Report Card GoDoc License: UNLICENSE Bugs Code Smells Duplicated Lines (%) Lines of Code Reliability Rating Security Rating Technical Debt Maintainability Rating Vulnerabilities

A2A‑Go

a2a‑go is a reference Go implementation of the Agent‑to‑Agent (A2A) protocol by Google, including the proposed interoperability with the Model Context Protocol (MCP).

🚧 Work in progress 🚧 Consider this project a proof of concept at best, and subject to sudden changes.

📋 Table of Contents

✨ Features

🔌 Agent‑to‑Agent (A2A) Protocol Implementation

  • Task Management

    • Send Task to send a new task to an agent
    • Get Task to retrieve a task by ID
    • Cancel Task to cancel a task
    • Stream Task to stream the task results
    • Set Push Notification to configure push notifications for a task
    • Get Push Notification to retrieve the push notification configuration for a task

  • Advanced AI Capabilities

    • Structured Outputs to return structured data from an agent
    • Fine‑tuning to fine‑tune an agent on a dataset
    • Image Generation to generate images with an agent
    • Audio Transcription to transcribe audio
    • Text‑to‑Speech to convert text to speech

🛠️ Model Context Protocol (MCP) Interoperability

  • Prompt Management

    • List Prompts to retrieve a list of prompts from an agent
    • Get Prompt to retrieve a prompt by ID
    • Set Prompt to create or update a prompt
    • Delete Prompt to delete a prompt by ID

  • Resource Management

    • List Resources to retrieve a list of resources from an agent
    • Get Resource to retrieve a resource by ID
    • Set Resource to create or update a resource
    • Delete Resource to delete a resource by ID

  • Tool Calling & Sampling

    • Tool Calling to call tools and receive the results
    • Sampling to sample a task from an agent
    • Roots to get the root task for a task

🔐 VPN & Networking

  • WireGuard VPN Integration
    • Built-in VPN client using WireGuard protocol
    • SOCKS5 proxy support for browser tool
    • Network stack integration with gVisor
    • Browser network context switching

🏗️ Infrastructure & Deployment

  • Containerized Architecture

    • Docker Compose orchestration
    • Kubernetes deployment manifests
    • MinIO object storage integration
    • Service discovery and registration

  • Enterprise Integration

    • Azure DevOps complete integration suite
    • GitHub API integration
    • Slack notifications and webhooks
    • OAuth2 authentication system

🏛️ Architecture

A2A-Go implements a distributed microservice architecture where each component runs independently:

graph TB
    subgraph "A2A-Go Distributed Architecture"
        subgraph "Service Layer"
            Catalog["🗂️ Catalog Service<br/>:3210<br/>(Registry)"]
            Manager["🤖 Manager Agent<br/>:8080<br/>(Orchestrator)"]
            Planner["📋 Planner Agent<br/>:8081<br/>(Strategy)"]
            Researcher["🔍 Researcher Agent<br/>:8082<br/>(Intel)"]
            Developer["💻 Developer Agent<br/>:8083<br/>(Code)"]
        end
        
        subgraph "Tool Layer"
            Browser["🌐 Browser Tool<br/>:9001<br/>(Web Automation)"]
            Docker["🐳 Docker Tool<br/>:9002<br/>(Containers)"]
            Azure["☁️ Azure DevOps<br/>:9003<br/>(Enterprise)"]
            GitHub["🐙 GitHub Tool<br/>:9004<br/>(Source Control)"]
        end
        
        subgraph "Infrastructure Layer"
            MinIO["📦 MinIO Storage<br/>:9000<br/>(Object Store)"]
            VPN["🔐 VPN Layer<br/>(WireGuard + SOCKS5)<br/>Browser Network Context"]
            UI["💻 Terminal UI<br/>(Interactive Client)"]
        end
    end
    
    %% Service Discovery
    Catalog -.-> Manager
    Catalog -.-> Planner
    Catalog -.-> Researcher
    Catalog -.-> Developer
    
    %% Agent Coordination
    Manager --> Planner
    Manager --> Researcher
    Manager --> Developer
    Planner --> Developer
    Researcher --> Developer
    
    %% Tool Usage
    Manager -.-> Browser
    Manager -.-> Docker
    Manager -.-> Azure
    Manager -.-> GitHub
    
    Developer -.-> Browser
    Developer -.-> Docker
    Developer -.-> GitHub
    
    Researcher -.-> Browser
    Researcher -.-> GitHub
    
    %% Infrastructure
    Manager --> MinIO
    Planner --> MinIO
    Researcher --> MinIO
    Developer --> MinIO
    
    UI --> Catalog
    UI --> Manager
    
    %% VPN for Browser Tool Only
    Browser --> VPN
    
    style Catalog fill:#e1f5fe
    style Manager fill:#f3e5f5
    style Planner fill:#f3e5f5
    style Researcher fill:#f3e5f5
    style Developer fill:#f3e5f5
    style Browser fill:#fff3e0
    style Docker fill:#fff3e0
    style Azure fill:#fff3e0
    style GitHub fill:#fff3e0
    style MinIO fill:#e8f5e8
    style VPN fill:#ffebee
    style UI fill:#f1f8e9
Loading

Core Components

  • Catalog Service: Central registry for agent and tool discovery
  • Agent Services: Specialized AI agents (Manager, Planner, Researcher, Developer, etc.)
  • Tool Services: Standalone tools exposing specific capabilities
  • VPN Layer: Network context switching for browser tool using WireGuard protocol
  • Storage Layer: MinIO for object storage and task persistence
  • UI Layer: Terminal UI for interaction and testing

📋 Prerequisites

  • Go 1.24.2 or later
  • Docker and Docker Compose
  • Make (for build automation)

Optional Dependencies

  • Kubernetes (for K8s deployment)
  • WireGuard (for VPN functionality)
  • MinIO client (for storage management)

🚀 Quick Start

The fastest way to get started is using the provided Makefile to run a full containerized distributed system:

1. Start the Server Infrastructure

# Build and start all services
make server

This will:

  • Build the Docker image
  • Start the catalog service on port 3210
  • Launch all agent and tool services
  • Initialize MinIO storage
  • Set up the VPN infrastructure

2. Connect with the Client

# Run the Terminal UI client
make client

The Terminal UI will connect to the distributed system and provide an interactive interface for:

  • Browsing available agents and tools
  • Sending tasks to agents
  • Streaming real-time results
  • Managing agent workflows

3. Test the System

# Run automated tests
make test

📦 Installation

From Source

# Clone the repository
git clone https://github.com/theapemachine/a2a-go.git
cd a2a-go

# Build the binary
go build -o a2a-go main.go

# Run a specific command
./a2a-go --help

Using Docker

# Build the Docker image
docker build -t theapemachine/a2a-go:latest .

# Run a specific agent
docker run -it --rm theapemachine/a2a-go:latest ui

🎯 Usage

Basic Agent Communication

# Send a task to an agent via JSON-RPC
curl -s -X POST localhost:8080/rpc \
  -d '{"jsonrpc":"2.0","id":1,"method":"tasks/send","params":{"id":"t1","message":{"role":"user","parts":[{"type":"text","text":"Hello"}]}}}' \
  | jq .artifacts[0].parts[0].text

Streaming Events

# Connect to Server-Sent Events stream
curl -sN localhost:3210/events | jq -c

Using Tools

# List available prompts
curl -s -X POST localhost:3210/rpc \
  -d '{"jsonrpc":"2.0","id":2,"method":"prompts/list"}' \
  | jq .prompts

# Fetch specific prompt content
curl -s -X POST localhost:3210/rpc \
  -d '{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"Greeting"}}' \
  | jq .messages[0].content.text

🔐 VPN Capabilities

A2A-Go includes a VPN solution built on WireGuard specifically for the browser tool:

Features

  • WireGuard Integration: Native WireGuard protocol support
  • SOCKS5 Proxy: Built-in SOCKS5 proxy server for browser traffic
  • Network Stack: Custom network stack using gVisor
  • Network Context Switching: Allows browser tool to operate from different network endpoints

Configuration

VPN settings are managed through the a2a.conf file:

[Interface]
PrivateKey = your_private_key_here
Address = 10.0.0.1/24

[Peer]
PublicKey = peer_public_key_here
Endpoint = vpn.example.com:51820
AllowedIPs = 10.0.0.0/24

🛠️ Built-in Tools

A2A-Go comes with an extensive set of pre-built tools:

Web & Browser Tools

  • Browser: Headless browser automation with Rod
  • Fetch: Web content extraction and screenshot capture
  • GitHub: Repository search and content retrieval

Development Tools

  • Docker: Container management and deployment
  • Azure DevOps: Complete sprint and work item management
  • Catalog: Agent and service discovery

Data & Storage Tools

  • Memory: Persistent memory storage for agents
  • Qdrant: Vector database integration
  • Neo4j: Graph database operations

Communication Tools

  • Slack: Notification and webhook integration
  • Editor: File editing and manipulation

🤖 Agent Ecosystem

The framework includes several specialized agents:

  • Manager: Orchestrates tasks and coordinates other agents
  • Planner: Creates and manages project plans
  • Researcher: Gathers information and conducts research
  • Developer: Handles code generation and development tasks
  • Evaluator: Assesses and validates agent outputs
  • UI: Provides terminal-based user interface

Each agent is containerized and can be deployed independently or as part of the complete ecosystem.

⚙️ Configuration

Environment Variables

Create a .env file based on env.example:

# MinIO Configuration
MINIO_USER=minioadmin
MINIO_PASSWORD=minioadmin
AWS_ACCESS_KEY_ID=a2a-access-key
AWS_SECRET_ACCESS_KEY=a2a-secret-key

# API Keys
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
COHERE_API_KEY=your_cohere_key

# Azure DevOps
AZURE_DEVOPS_ORGANIZATION=your_org
AZURE_DEVOPS_TOKEN=your_token

Agent Configuration

The system uses a hierarchical configuration approach:

  1. Embedded Defaults: Built into the binary
  2. User Config: ~/.a2a-go/config.yml
  3. Environment Variables: Override specific settings

🔧 Development

Project Structure

a2a-go/
├── cmd/              # CLI commands and entry points
├── pkg/              # Core packages
│   ├── a2a/          # A2A protocol implementation
│   ├── vpn/          # VPN and networking
│   ├── tools/        # Built-in tools
│   ├── ui/           # Terminal UI
│   └── ...
├── docs/             # Documentation
├── specs/            # Protocol specifications
└── docker-compose.yml

Running Tests

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific test suite
go test ./pkg/tools/...

Code Style

  • Use GoDoc comments above all methods and types
  • Follow the /**/ format for documentation
  • Use GoConvey for tests with one test function per code function
  • Maintain clean, well-organized code structure

🤝 Contributing

  1. Read the Specifications: Check the specs/ directory for protocol details
  2. Follow Code Style: Maintain consistency with existing patterns
  3. Write Tests: Use GoConvey and mirror code structure in tests
  4. Update Documentation: Keep docs current with changes
  5. Test the TUI: Ensure Terminal UI works with your changes

Development Workflow

# Start development environment
make server

# Make your changes
# ...

# Test your changes
make test

# Test with client
make client

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

Protocol Specifications

The specs/ directory contains detailed protocol specifications:

  • A2A Protocol: Complete Agent-to-Agent specification
  • MCP Integration: Model Context Protocol implementation details
  • Tool Definitions: Comprehensive tool capability specifications

📄 License

This project is released under the UNLICENSE, placing it in the public domain.

🔗 Links

Note: This is an active development project implementing cutting-edge agent protocols. The API and features may change as the specifications evolve.

About

a2a‑go is a reference Go implementation of the Agent‑to‑Agent (A2A) protocol by Google, including the proposed interoperability with the Model Context Protocol (MCP) from Anthropic.

Topics

mcp a2a modelcontextprotocol a2a-protocol

Resources

Readme

License

Unlicense license
Activity

Stars

3 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages