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