Getting Started

• 1: Installation and Setup Tutorial
• 2: Running the A2A-Compliant AgentHub Demo

1 - Installation and Setup Tutorial

Installation and Setup Tutorial

This tutorial will guide you through installing AgentHub and setting up your development environment from scratch. By the end, you’ll have a working A2A-compliant AgentHub installation ready for building Agent2Agent protocol systems.

Prerequisites Check

Before we begin, let’s verify you have the required software installed.

Step 1: Verify Go Installation

Check if Go 1.24+ is installed:

go version

You should see output like:

go version go1.24.0 darwin/amd64

If Go is not installed or the version is older than 1.24:

macOS (using Homebrew):

brew install go

Linux (using package manager):

# Ubuntu/Debian
sudo apt update && sudo apt install golang-go

# CentOS/RHEL
sudo yum install golang

# Arch Linux
sudo pacman -S go

Windows: Download from https://golang.org/dl/ and run the installer.

Step 2: Verify Protocol Buffers Compiler

Check if protoc is installed:

protoc --version

You should see output like:

libprotoc 3.21.12

If protoc is not installed:

macOS (using Homebrew):

brew install protobuf

Linux:

# Ubuntu/Debian
sudo apt update && sudo apt install protobuf-compiler

# CentOS/RHEL
sudo yum install protobuf-compiler

# Arch Linux
sudo pacman -S protobuf

Windows: Download from Protocol Buffers releases and add to PATH.

Step 3: Install Go Protocol Buffer Plugins

Install the required Go plugins for Protocol Buffers:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Verify the plugins are in your PATH:

which protoc-gen-go
which protoc-gen-go-grpc

Both commands should return paths to the installed plugins.

Installing AgentHub

Step 4: Clone the Repository

Clone the AgentHub repository:

git clone https://github.com/owulveryck/agenthub.git
cd agenthub

Step 5: Verify Project Structure

Let’s explore what we have:

ls -la

You should see:

drwxr-xr-x agents/           # Sample A2A agent implementations
drwxr-xr-x broker/           # A2A-compliant AgentHub broker server
drwxr-xr-x documentation/    # Complete A2A documentation
drwxr-xr-x events/           # Generated A2A protocol code
drwxr-xr-x internal/         # Internal packages and abstractions
-rw-r--r-- go.mod            # Go module definition
-rw-r--r-- Makefile         # Build automation
drwxr-xr-x proto/           # A2A protocol definitions
-rw-r--r-- README.md        # Project overview

Step 6: Initialize Go Module

Ensure Go modules are properly initialized:

go mod tidy

This downloads all required dependencies. You should see output about downloading packages.

Step 7: Generate Protocol Buffer Code

Generate the Go code from Protocol Buffer definitions:

make proto

You should see:

Generating protobuf code for A2A protocol definitions...
Generating proto/eventbus.proto...
Generating proto/a2a.proto...
Protobuf code generated successfully.

Verify the generated files exist:

ls events/

You should see:

a2a/          # A2A protocol definitions
eventbus/     # AgentHub broker definitions

ls events/a2a/

You should see:

a2a.pb.go
a2a_grpc.pb.go

ls events/eventbus/

You should see:

eventbus.pb.go
eventbus_grpc.pb.go

Step 8: Build All Components

Build the AgentHub components:

make build

You should see:

Building A2A-compliant server binary...
Building A2A publisher binary...
Building A2A subscriber binary...
Build complete. A2A-compliant binaries are in the 'bin/' directory.

Verify the binaries were created:

ls bin/

You should see:

agenthub-server  # A2A-compliant AgentHub broker
publisher        # A2A message publisher
subscriber       # A2A message subscriber

Verification Test

Let’s verify everything works by running a quick test.

Step 9: Test the Installation

Start the A2A-compliant broker server in the background:

./bin/agenthub-server &

You should see:

2025/09/28 10:00:00 A2A-compliant AgentHub broker gRPC server listening on [::]:50051
2025/09/28 10:00:00 AgentHub service ready for A2A protocol communication

Start an A2A subscriber agent:

./bin/subscriber &

You should see:

A2A Agent started. Listening for A2A events and tasks. Press Enter to stop.
2025/09/28 10:00:05 A2A Agent agent_demo_subscriber subscribing to A2A tasks...
2025/09/28 10:00:05 Successfully subscribed to A2A tasks for agent agent_demo_subscriber. Waiting for A2A tasks...

Run the A2A publisher to send test tasks:

./bin/publisher

You should see A2A tasks being published and processed with conversation context and structured artifacts.

Clean up the test processes:

pkill -f agenthub-server
pkill -f subscriber

Development Environment Setup

Step 10: Configure Your Editor

For VS Code users:

Install the Go extension:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for “Go” and install the official Go extension
4. Open the AgentHub project folder

For other editors:

Ensure your editor has Go language support and Protocol Buffer syntax highlighting.

Step 11: Set Up Environment Variables (Recommended)

AgentHub uses environment variables for configuration. Create a .envrc file for local development:

cat > .envrc << EOF
# Core A2A AgentHub Configuration
export AGENTHUB_BROKER_ADDR="localhost"
export AGENTHUB_BROKER_PORT="50051"
export AGENTHUB_GRPC_PORT=":50051"

# A2A Protocol Configuration
export AGENTHUB_A2A_PROTOCOL_VERSION="1.0"
export AGENTHUB_MESSAGE_BUFFER_SIZE="100"
export AGENTHUB_CONTEXT_TIMEOUT="30s"
export AGENTHUB_ARTIFACT_MAX_SIZE="10MB"

# Health Check Ports
export AGENTHUB_HEALTH_PORT="8080"
export A2A_PUBLISHER_HEALTH_PORT="8081"
export A2A_SUBSCRIBER_HEALTH_PORT="8082"

# Observability (optional for development)
export JAEGER_ENDPOINT="http://localhost:14268/api/traces"
export SERVICE_NAME="agenthub-dev"
export SERVICE_VERSION="dev"
export ENVIRONMENT="development"
export LOG_LEVEL="DEBUG"
EOF

Install direnv for automatic loading (recommended):

# macOS
brew install direnv

# Ubuntu/Debian
sudo apt install direnv

# After installation, add to your shell
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc  # For bash
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc    # For zsh

Allow the environment file:

direnv allow

Alternative: Manual loading

source .envrc

📖 For complete environment variable reference, see Environment Variables Reference

Step 12: Verify Make Targets

Test all available make targets:

make help

You should see all available commands:

Makefile for gRPC Event Bus

Usage:
  make <target>

Targets:
  all              Builds all binaries (default).
  proto            Generates Go code from .proto files.
  build            Builds the server, publisher, and subscriber binaries.
  run-server       Runs the event bus gRPC server.
  run-publisher    Runs the publisher client.
  run-subscriber   Runs the subscriber client.
  clean            Removes generated Go files and build artifacts.
  help             Displays this help message.

Common Issues and Solutions

Issue: “protoc-gen-go: program not found”

Solution: Ensure Go bin directory is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

Issue: “go.mod not found”

Solution: Ensure you’re in the AgentHub project directory:

pwd  # Should show .../agenthub
ls go.mod  # Should exist

Issue: Port 50051 already in use

Solution: Kill existing processes or change the port:

lsof -ti:50051 | xargs kill -9

Issue: Permission denied on binaries

Solution: Make binaries executable:

chmod +x bin/*

Next Steps

Now that you have AgentHub installed and verified:

1. Learn the basics: Follow the Running the Demo tutorial
2. Build your first agent: Try Create a Subscriber
3. Understand the concepts: Read The Agent2Agent Principle

Getting Help

If you encounter issues:

1. Check the troubleshooting section above
2. Review the complete documentation
3. Open an issue on the GitHub repository

Congratulations! You now have a fully functional AgentHub development environment ready for building autonomous agent systems.

2 - Running the A2A-Compliant AgentHub Demo

Running the A2A-Compliant AgentHub Demo

This tutorial will walk you through setting up and running the complete Agent2Agent (A2A) protocol-compliant AgentHub Event-Driven Architecture (EDA) broker system. By the end of this tutorial, you’ll have agents communicating using standardized A2A messages through the scalable EDA broker.

Prerequisites

• Go 1.24 or later installed
• Protocol Buffers compiler (protoc) installed
• Basic understanding of gRPC and message brokers

Step 1: Build the A2A-Compliant Components

First, let’s build all the A2A-compliant components using the Makefile:

# Build all A2A-compliant binaries (generates protobuf files first)
make build

This will:

1. Generate A2A protocol files from proto/a2a_core.proto and proto/eventbus.proto
2. Build the A2A-compliant broker, publisher, and subscriber binaries
3. Place all binaries in the bin/ directory

You should see output like:

Building A2A-compliant server binary...
Building A2A-compliant publisher binary...
Building A2A-compliant subscriber binary...
Build complete. A2A-compliant binaries are in the 'bin/' directory.

Step 2: Start the AgentHub Broker Server

Open a terminal and start the AgentHub broker server:

./bin/broker

You should see output like:

time=2025-09-29T11:51:26.612+02:00 level=INFO msg="Starting health server" port=8080
time=2025-09-29T11:51:26.611+02:00 level=INFO msg="AgentHub gRPC server with observability listening" address=[::]:50051 health_endpoint=http://localhost:8080/health metrics_endpoint=http://localhost:8080/metrics component=broker

Keep this terminal open - the AgentHub broker needs to run continuously.

Step 3: Start an Agent (Subscriber)

Open a second terminal and start an agent that can receive and process tasks:

./bin/subscriber

You should see output indicating the agent has started:

time=2025-09-29T11:52:04.727+02:00 level=INFO msg="AgentHub client started with observability" broker_addr=localhost:50051 component=subscriber
time=2025-09-29T11:52:04.727+02:00 level=INFO msg="Starting health server" port=8082
time=2025-09-29T11:52:04.728+02:00 level=INFO msg="Agent started with observability. Listening for events and tasks."
time=2025-09-29T11:52:04.728+02:00 level=INFO msg="Subscribing to task results" agent_id=agent_demo_subscriber
time=2025-09-29T11:52:04.728+02:00 level=INFO msg="Subscribing to tasks" agent_id=agent_demo_subscriber

This agent can process several types of tasks:

• greeting: Simple greeting messages
• math_calculation: Basic arithmetic operations
• random_number: Random number generation
• Any unknown task type will be rejected

Step 4: Send A2A-Compliant Tasks

Open a third terminal and run the publisher to send A2A protocol-compliant task messages:

./bin/publisher

You’ll see the publisher send various A2A-compliant task messages through the AgentHub EDA broker:

time=2025-09-29T14:41:11.237+02:00 level=INFO msg="Starting publisher demo"
time=2025-09-29T14:41:11.237+02:00 level=INFO msg="Testing Agent2Agent Task Publishing via AgentHub with observability"
time=2025-09-29T14:41:11.237+02:00 level=INFO msg="Publishing A2A task" task_id=task_greeting_1759149671 task_type=greeting responder_agent_id=agent_demo_subscriber context_id=ctx_greeting_1759149671
time=2025-09-29T14:41:11.242+02:00 level=INFO msg="A2A task published successfully" task_id=task_greeting_1759149671 task_type=greeting event_id=evt_msg_greeting_1759149671_1759149671
time=2025-09-29T14:41:11.242+02:00 level=INFO msg="Published greeting task" task_id=task_greeting_1759149671
time=2025-09-29T14:41:14.243+02:00 level=INFO msg="Publishing A2A task" task_id=task_math_calculation_1759149674 task_type=math_calculation responder_agent_id=agent_demo_subscriber context_id=ctx_math_calculation_1759149674
time=2025-09-29T14:41:14.247+02:00 level=INFO msg="A2A task published successfully" task_id=task_math_calculation_1759149674 task_type=math_calculation event_id=evt_msg_math_calculation_1759149674_1759149674
time=2025-09-29T14:41:16.248+02:00 level=INFO msg="Publishing A2A task" task_id=task_random_number_1759149676 task_type=random_number responder_agent_id=agent_demo_subscriber context_id=ctx_random_number_1759149676
time=2025-09-29T14:41:16.249+02:00 level=INFO msg="Published random number task" task_id=task_random_number_1759149676

Notice how the A2A implementation includes:

• Context IDs: Each task is grouped in a conversation context (ctx_greeting_...)
• Event IDs: EDA wrapper events have unique identifiers for tracing
• A2A Task Structure: Tasks use A2A-compliant Message and Part formats

Step 5: Observe A2A Task Processing

Switch back to the subscriber terminal to see the agent processing A2A tasks in real-time:

time=2025-09-29T14:41:11.243+02:00 level=INFO msg="Task processing completed" task_id=task_greeting_1759149671 status=TASK_STATE_COMPLETED has_artifact=true
time=2025-09-29T14:41:14.253+02:00 level=INFO msg="Task processing completed" task_id=task_math_calculation_1759149674 status=TASK_STATE_COMPLETED has_artifact=true
time=2025-09-29T14:41:16.249+02:00 level=INFO msg="Task processing completed" task_id=task_random_number_1759149676 status=TASK_STATE_COMPLETED has_artifact=true

Notice the A2A-compliant processing:

• Task States: Using A2A standard states (TASK_STATE_COMPLETED)
• Artifacts: Each completed task generates A2A artifacts (has_artifact=true)
• Structured Processing: Tasks are processed using A2A Message and Part handlers

Step 6: Check the Broker Logs

In the first terminal (broker server), you’ll see logs showing message routing:

2025/09/27 16:34:33 Received task request: task_greeting_1758983673 (type: greeting) from agent: agent_demo_publisher
2025/09/27 16:34:35 Received task result for task: task_greeting_1758983673 from agent: agent_demo_subscriber
2025/09/27 16:34:35 Received task progress for task: task_greeting_1758983673 (100%) from agent: agent_demo_subscriber

Understanding What Happened

1. A2A Message Creation: The publisher created A2A-compliant messages with:

   • Message Structure: Using A2A Message format with Part content
   • Context Grouping: Each task belongs to a conversation context
   • Task Association: Messages are linked to specific A2A tasks
   • Role Definition: Messages specify USER (requester) or AGENT (responder) roles

2. EDA Event Routing: The AgentHub EDA broker:

   • Wrapped A2A Messages: A2A messages wrapped in AgentEvent for EDA transport
   • Event-Driven Routing: Used EDA patterns for scalable message delivery
   • Task Storage: Stored A2A tasks with full message history and artifacts
   • Status Tracking: Managed A2A task lifecycle (SUBMITTED → WORKING → COMPLETED)

3. A2A Task Processing: The subscriber agent:

   • A2A Task Reception: Received A2A tasks via EDA event streams
   • Message Processing: Processed A2A Message content using Part handlers
   • Artifact Generation: Generated structured A2A artifacts as task output
   • Status Updates: Published A2A-compliant status updates through EDA events

4. Hybrid Architecture Benefits:

   • A2A Compliance: Full interoperability with other A2A-compliant systems
   • EDA Scalability: Event-driven patterns for high-throughput scenarios
   • Standards-Based: Using industry-standard Agent2Agent protocol
   • Observable: Built-in tracing and metrics for production deployment

Next Steps

Now that you have the basic system working, you can:

1. Create Multiple Agents: Run multiple subscriber instances with different agent IDs to see task distribution
2. Add Custom Task Types: Modify the subscriber to handle new types of tasks
3. Build a Request-Response Flow: Create an agent that both requests and processes tasks
4. Monitor Task Progress: Build a dashboard that subscribes to task progress updates

Troubleshooting

Port Already in Use: If you see “bind: address already in use”, kill any existing processes:

lsof -ti:50051 | xargs kill -9

Agent Not Receiving Tasks: Ensure the agent ID in the publisher matches the subscriber’s agent ID (agent_demo_subscriber).

Build Errors: Regenerate A2A protocol buffer files and ensure all imports are correct:

# Clean old protobuf files
make clean

# Regenerate A2A protobuf files
make proto

# Rebuild everything
make build

A2A Compliance Issues: Verify A2A protocol structures are correctly generated:

# Check A2A core types
ls events/a2a/

# Should show: a2a_core.pb.go eventbus.pb.go eventbus_grpc.pb.go

You now have a working A2A-compliant AgentHub EDA broker system! The agents can exchange standardized A2A messages, maintain conversation contexts, generate structured artifacts, and track task lifecycles - all through your scalable Event-Driven Architecture broker with full Agent2Agent protocol compliance.