Agent Exchange - Quick Start Guide

Get up and running with Agent Exchange in minutes!

Prerequisites

Go 1.22+ - Install Go
Docker & Docker Compose - Install Docker
Make (optional but recommended)

Quick Start (5 minutes)

Option 1: Using Make (Recommended)

# Clone the repository
git clone <repo-url>
cd agent-exchange

# Build and start everything
make quickstart

# Check service health
make health

That's it! All services are now running.

Option 2: Manual Setup

# 1. Build all services
make build

# 2. Build Docker images
make docker-build

# 3. Start services
make docker-up

# 4. View logs
make docker-logs

Option 3: Local Development (without Docker)

# 1. Start MongoDB
make mongo-up

# 2. Initialize database
mongosh mongodb://root:root@localhost:27017 < hack/mongo-init.js

# 3. Run a service locally
make dev-work-publisher
# or
make dev-settlement

Service URLs

Once running, services are available at:

Core Services

Service	URL	Status
Gateway	http://localhost:8080	✅ Ready
Work Publisher	http://localhost:8081	✅ Ready
Bid Gateway	http://localhost:8082	✅ Ready
Bid Evaluator	http://localhost:8083	✅ Ready
Contract Engine	http://localhost:8084	✅ Ready
Provider Registry	http://localhost:8085	✅ Ready
Trust Broker	http://localhost:8086	✅ Ready
Identity	http://localhost:8087	✅ Ready
Settlement	http://localhost:8088	✅ Ready
Telemetry	http://localhost:8089	⚠️ MVP
Credentials Provider (AP2)	http://localhost:8090	✅ NEW

Demo Components

Component	URL	Description
NiceGUI UI (Recommended)	http://localhost:8502	Real-time demo dashboard
Budget Legal Agent	http://localhost:8100	$5 + $2/page
Standard Legal Agent	http://localhost:8101	$15 + $0.50/page
Premium Legal Agent	http://localhost:8102	$30 + $0.20/page
Orchestrator	http://localhost:8103	Consumer agent
LegalPay	http://localhost:8200	Payment processor
ContractPay	http://localhost:8201	Payment processor
CompliancePay	http://localhost:8202	Payment processor

MongoDB: mongodb://root:root@localhost:27017

Test the System

1. Submit Work

curl -X POST http://localhost:8081/v1/work \
  -H "Content-Type: application/json" \
  -d '{
    "category": "general",
    "description": "Test work request",
    "budget": {
      "max_price": 100.0,
      "bid_strategy": "balanced"
    },
    "success_criteria": [
      {
        "metric": "accuracy",
        "threshold": 0.95,
        "comparison": ">=",
        "bonus": 10.0
      }
    ]
  }'

Response:

{
  "work_id": "work_abc123",
  "status": "open",
  "bid_window_ends_at": "2025-12-23T12:30:00Z",
  "providers_notified": 5,
  "created_at": "2025-12-23T12:00:00Z"
}

2. Check Balance

curl http://localhost:8088/v1/balance?tenant_id=tenant_test001

Response:

{
  "tenant_id": "tenant_test001",
  "balance": "1000.00",
  "currency": "USD"
}

3. Process Deposit

curl -X POST http://localhost:8088/v1/deposits \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant_test001",
    "amount": "500.00"
  }'

4. Get Usage Data

curl "http://localhost:8088/v1/usage?tenant_id=tenant_test001&limit=10"

5. Health Checks

# Check all services
make health

# Or individually
curl http://localhost:8081/health  # work-publisher
curl http://localhost:8088/health  # settlement

Common Commands

# Build specific service
make build-aex-work-publisher

# Test specific service
make test-aex-settlement

# View logs for specific service
make docker-logs-aex-work-publisher

# Rebuild Docker image
make docker-build-aex-settlement

# Stop all services
make docker-down

# Clean and restart
make docker-clean && make quickstart

# Format code
make fmt

# Run linters
make lint

# Tidy dependencies
make tidy

Development Workflow

Working on a Service

# 1. Start dependencies (MongoDB)
make mongo-up

# 2. Run service locally
cd src/aex-work-publisher
ENVIRONMENT=development \
STORE_TYPE=memory \
PORT=8081 \
go run ./src

# 3. Make changes and test
# 4. Build and test
go build -o bin/aex-work-publisher ./src
./bin/aex-work-publisher

# 5. Run tests
go test ./... -v

Adding a New HTTP Client

// Example: Create client in internal/clients/
package clients

import (
    "context"
    "time"
    "github.com/parlakisik/agent-exchange/internal/httpclient"
)

type MyServiceClient struct {
    baseURL string
    client  *httpclient.Client
}

func NewMyServiceClient(baseURL string) *MyServiceClient {
    return &MyServiceClient{
        baseURL: baseURL,
        client:  httpclient.NewClient("my-service", 10*time.Second),
    }
}

func (c *MyServiceClient) GetData(ctx context.Context, id string) (*Data, error) {
    var result Data
    err := httpclient.NewRequest("GET", c.baseURL).
        Path("/v1/data/" + id).
        Context(ctx).
        ExecuteJSON(c.client, &result)
    return &result, err
}

Troubleshooting

Services won't start

# Check if ports are already in use
lsof -i :8080-8089

# Check Docker logs
make docker-logs

# Restart with fresh state
make docker-clean && make quickstart

MongoDB connection issues

# Check MongoDB is running
docker ps | grep mongo

# Test connection
mongosh mongodb://root:root@localhost:27017

# Restart MongoDB
docker restart aex-mongo

Build failures

# Clean and rebuild
make clean
make tidy
make build

Service-specific issues

# Check service logs
make docker-logs-aex-work-publisher

# Restart specific service
docker-compose -f hack/docker-compose.yml restart aex-work-publisher

# Check service health
curl http://localhost:8081/health -v

Environment Variables

Copy .env.example to .env and customize:

cp .env.example .env
# Edit .env with your values

Key variables:

MONGO_URI - MongoDB connection string
ENVIRONMENT - development | production
WORK_PUBLISHER_STORE_TYPE - mongo | firestore | memory
PLATFORM_FEE_RATE - Settlement platform fee (default: 0.15)

Run the Demo

The demo showcases the complete AEX + A2A + AP2 integration with legal agents and payment processors.

Quick Demo Start

cd demo
docker-compose up -d
open http://localhost:8502

Step-by-Step Demo (for presentations)

cd demo

# Clean start
docker-compose down -v

# Start AEX only (no agents)
docker-compose up -d mongo aex-identity aex-provider-registry aex-trust-broker \
  aex-bid-gateway aex-bid-evaluator aex-contract-engine aex-work-publisher \
  aex-settlement aex-credentials-provider aex-telemetry aex-gateway

# Start UI
docker-compose up -d --no-deps demo-ui-nicegui
open http://localhost:8502

# Add agents one by one (agents auto-appear in UI)
docker-compose up -d legal-agent-a
docker-compose up -d legal-agent-b
docker-compose up -d legal-agent-c
docker-compose up -d payment-legalpay payment-contractpay payment-compliancepay
docker-compose up -d orchestrator

Demo Flow

Submit Work - Enter contract text in UI
Watch Bids - See legal agents compete
Award Contract - Best bid wins based on strategy
A2A Execution - Direct agent-to-agent communication
AP2 Payment - Payment agents bid for transaction
Settlement - Platform fee + provider payout

Next Steps

Run the Demo - See instructions above or demo/README.md
Run Integration Tests - make test
Explore the Code - Start with src/aex-work-publisher
Check the Roadmap - See src/development-roadmap.md for gaps and next steps
Read Phase A Specs - See phase-a/readme.md for architecture details
AP2 Integration - See AP2_INTEGRATION.md for payment protocol details
Presentation Materials - See PRESENTATION.md and PRESENTATION_SLIDES.md

Architecture

                    ┌─────────────────┐
                    │   aex-gateway   │ (8080) - API Gateway
                    └────────┬────────┘
                             │
    ┌────────────────────────┼────────────────────────┐
    │                        │                        │
┌───▼──────────┐    ┌────────▼────────┐    ┌─────────▼────────┐
│work-publisher│    │  bid-gateway    │    │provider-registry │
│   (8081)     │    │    (8082)       │    │     (8085)       │
└───┬──────────┘    └────────┬────────┘    └──────────────────┘
    │                        │
    │               ┌────────▼────────┐
    └──────────────►│ bid-evaluator   │
                    │    (8083)       │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │contract-engine  │
                    │    (8084)       │
                    └────────┬────────┘
                             │
    ┌────────────────────────┼────────────────────────┐
    │                        │                        │
┌───▼──────────┐    ┌────────▼────────┐    ┌─────────▼────────┐
│ trust-broker │    │   settlement    │    │credentials-prov. │
│   (8086)     │    │(8088) + AP2     │    │(8090) - AP2 NEW  │
└──────────────┘    └─────────────────┘    └──────────────────┘

Demo Architecture (A2A + AP2)

┌─────────────┐         ┌─────────────────────────────────────┐
│   Consumer  │         │         AEX Marketplace             │
│ Orchestrator│◄───────►│  (Discovery, Bidding, Settlement)   │
│   (8103)    │         └─────────────────────────────────────┘
└──────┬──────┘                         │
       │ A2A                            │ AP2
       │ JSON-RPC                       │
       ▼                                ▼
┌─────────────────────┐    ┌─────────────────────────────┐
│   Legal Agents      │    │    Payment Agents (AP2)     │
│ Budget    (8100)    │    │ LegalPay      (8200)        │
│ Standard  (8101)    │    │ ContractPay   (8201)        │
│ Premium   (8102)    │    │ CompliancePay (8202)        │
└─────────────────────┘    └─────────────────────────────┘

Getting Help

Issues: Report bugs in GitHub Issues
Documentation: See docs/ folder and phase-a/specs/
Roadmap: Check src/development-roadmap.md for current status and gaps

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Agent Exchange - Quick Start Guide

Prerequisites

Quick Start (5 minutes)

Option 1: Using Make (Recommended)

Option 2: Manual Setup

Option 3: Local Development (without Docker)

Service URLs

Core Services

Demo Components

Test the System

1. Submit Work

2. Check Balance

3. Process Deposit

4. Get Usage Data

5. Health Checks

Common Commands

Development Workflow

Working on a Service

Adding a New HTTP Client

Troubleshooting

Services won't start

MongoDB connection issues

Build failures

Service-specific issues

Environment Variables

Run the Demo

Quick Demo Start

Step-by-Step Demo (for presentations)

Demo Flow

Next Steps

Architecture

Demo Architecture (A2A + AP2)

Getting Help

FilesExpand file tree

QUICKSTART.md

Latest commit

History

QUICKSTART.md

File metadata and controls

Agent Exchange - Quick Start Guide

Prerequisites

Quick Start (5 minutes)

Option 1: Using Make (Recommended)

Option 2: Manual Setup

Option 3: Local Development (without Docker)

Service URLs

Core Services

Demo Components

Test the System

1. Submit Work

2. Check Balance

3. Process Deposit

4. Get Usage Data

5. Health Checks

Common Commands

Development Workflow

Working on a Service

Adding a New HTTP Client

Troubleshooting

Services won't start

MongoDB connection issues

Build failures

Service-specific issues

Environment Variables

Run the Demo

Quick Demo Start

Step-by-Step Demo (for presentations)

Demo Flow

Next Steps

Architecture

Demo Architecture (A2A + AP2)

Getting Help