"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.

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.

• Features
• Architecture
• Prerequisites
• Quick Start
• Installation
• Usage
• VPN Capabilities
• Built-in Tools
• Agent Ecosystem
• Configuration
• Development
• Contributing
• Documentation

• 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

• 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

• 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

• 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

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 

• 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

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

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

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

# 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

# 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

# Run automated tests make test

# 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

# Build the Docker image docker build -t theapemachine/a2a-go:latest . # Run a specific agent docker run -it --rm theapemachine/a2a-go:latest ui

# 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

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

# 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

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

• 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

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

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

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

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

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

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

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.

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

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

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 

# Run all tests go test ./... # Run with coverage go test -cover ./... # Run specific test suite go test ./pkg/tools/...

• 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

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

# Start development environment make server # Make your changes # ... # Test your changes make test # Test with client make client

Comprehensive documentation is available in the docs/ directory:

• Quick Start Guide: Get up and running quickly
• Architecture Overview: System design and components
• Tools Documentation: Built-in tools and capabilities
• Memory Architecture: Agent memory systems
• Prompts Guide: Prompt management and usage
• Sampling Documentation: Task sampling strategies
• Resources Guide: Resource management

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

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

• Agent-to-Agent Protocol
• Model Context Protocol
• Go Documentation
• Docker Hub

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