← Documentation Home

Agent Mesh API

gRPC service mesh for agent-to-agent communication with REST gateway.

Overview

Service: Phoenix Agent Mesh Port: 3040 Domain: mesh.local.bluefly.io Protocol: gRPC with REST gateway Version: 1.0.0 OpenAPI Spec: /technical-guide/openapi/agent-mesh/agent-mesh.openapi.yaml

What It Does

Agent Mesh provides a distributed service mesh for agent-to-agent communication with: - Direct messaging: Agent-to-agent communication - Swarm coordination: Byzantine fault-tolerant swarm management - ACAP protocol: Zero-knowledge capability attestation - Activity streams: Real-time observability - Service discovery: Dynamic agent registration

Architecture

graph TD
    A[Agent 1] -->|gRPC| M[Agent Mesh]
    B[Agent 2] -->|gRPC| M
    C[Agent 3] -->|gRPC| M
    M --> D[Service Registry]
    M --> E[Swarm Coordinator]
    M --> F[ACAP Attestation]
    M --> G[Activity Streams]

Core Services

1. Agent Communication

Direct agent-to-agent messaging and task execution.

Register Agent

POST /api/v1/agents/register

Request:

{
  "agentId": "agent-brain-001",
  "capabilities": ["reasoning", "planning", "code-generation"],
  "metadata": {
    "version": "1.0.0",
    "region": "us-west-2"
  },
  "endpoints": {
    "grpc": "agent-brain.local.bluefly.io:50051",
    "rest": "https://agent-brain.local.bluefly.io/api/v1"
  }
}

Response:

{
  "registrationId": "reg-12345",
  "agentId": "agent-brain-001",
  "status": "active",
  "registeredAt": "2025-01-15T10:30:00Z",
  "heartbeatInterval": 30
}

Discover Agents

POST /api/v1/agents/discover

Request:

{
  "capabilities": ["code-generation"],
  "filters": {
    "region": "us-west-2",
    "status": "active"
  }
}

Response:

{
  "agents": [
    {
      "agentId": "agent-brain-001",
      "capabilities": ["reasoning", "planning", "code-generation"],
      "endpoints": {
        "grpc": "agent-brain.local.bluefly.io:50051"
      },
      "load": 0.45,
      "status": "active"
    }
  ],
  "totalFound": 1
}

Execute Task

POST /api/v1/tasks/execute

Request:

{
  "targetAgent": "agent-brain-001",
  "task": {
    "type": "code-generation",
    "input": {
      "prompt": "Create TypeScript authentication service",
      "context": {
        "framework": "Express",
        "database": "PostgreSQL"
      }
    },
    "timeout": 30000,
    "priority": "normal"
  }
}

Response:

{
  "taskId": "task-67890",
  "status": "completed",
  "result": {
    "code": "...",
    "files": ["auth.service.ts", "auth.controller.ts"],
    "tests": ["auth.service.test.ts"]
  },
  "duration": 2500,
  "executedBy": "agent-brain-001"
}

2. Swarm Coordination

Byzantine fault-tolerant swarm coordination for multi-agent tasks.

Create Swarm

POST /api/v1/swarms

Request:

{
  "name": "code-review-swarm",
  "agents": [
    "agent-brain-001",
    "agent-brain-002",
    "agent-brain-003"
  ],
  "consensus": {
    "type": "byzantine-fault-tolerant",
    "threshold": 2,
    "timeout": 60000
  },
  "task": {
    "type": "code-review",
    "input": {
      "repository": "llm-platform",
      "pullRequest": 123
    }
  }
}

Response:

{
  "swarmId": "swarm-abc123",
  "status": "active",
  "agents": ["agent-brain-001", "agent-brain-002", "agent-brain-003"],
  "createdAt": "2025-01-15T10:35:00Z",
  "consensusReached": false
}

Get Swarm Status

GET /api/v1/swarms/{swarmId}/status

Response:

{
  "swarmId": "swarm-abc123",
  "status": "consensus-reached",
  "agentVotes": [
    {
      "agentId": "agent-brain-001",
      "vote": "approve",
      "confidence": 0.92,
      "timestamp": "2025-01-15T10:36:00Z"
    },
    {
      "agentId": "agent-brain-002",
      "vote": "approve",
      "confidence": 0.88,
      "timestamp": "2025-01-15T10:36:01Z"
    },
    {
      "agentId": "agent-brain-003",
      "vote": "approve",
      "confidence": 0.95,
      "timestamp": "2025-01-15T10:36:02Z"
    }
  ],
  "finalDecision": "approve",
  "consensusAt": "2025-01-15T10:36:02Z"
}

3. ACAP Protocol

Zero-knowledge capability attestation for secure agent verification.

Attest Capability

POST /api/v1/acap/attest

Request:

{
  "agentId": "agent-brain-001",
  "capability": "code-generation",
  "proof": {
    "type": "zero-knowledge",
    "commitment": "0x1234...",
    "challenge": "0xabcd...",
    "response": "0x5678..."
  }
}

Response:

{
  "attestationId": "att-xyz789",
  "agentId": "agent-brain-001",
  "capability": "code-generation",
  "verified": true,
  "validUntil": "2025-01-15T11:35:00Z",
  "signature": "0xdeadbeef..."
}

Verify Capability

POST /api/v1/acap/verify

Request:

{
  "attestationId": "att-xyz789",
  "agentId": "agent-brain-001",
  "capability": "code-generation"
}

Response:

{
  "valid": true,
  "agentId": "agent-brain-001",
  "capability": "code-generation",
  "verifiedAt": "2025-01-15T10:37:00Z",
  "expiresAt": "2025-01-15T11:35:00Z"
}

4. Activity Streams

Real-time activity streaming for observability.

Subscribe to Activity Stream

WebSocket: ws://mesh.local.bluefly.io/api/v1/activity/stream

Subscribe Message:

{
  "action": "subscribe",
  "filters": {
    "agentIds": ["agent-brain-001"],
    "eventTypes": ["task-executed", "capability-attested"]
  }
}

Stream Events:

{
  "eventId": "evt-123",
  "type": "task-executed",
  "agentId": "agent-brain-001",
  "timestamp": "2025-01-15T10:38:00Z",
  "data": {
    "taskId": "task-67890",
    "duration": 2500,
    "status": "completed"
  }
}

gRPC Services

For high-performance use cases, use direct gRPC connections:

Proto Definitions

service AgentCommunication {
  rpc RegisterAgent(AgentRegistration) returns (RegistrationResponse);
  rpc DiscoverAgents(DiscoveryQuery) returns (DiscoveryResponse);
  rpc ExecuteTask(TaskRequest) returns (TaskResponse);
  rpc Deregister(DeregistrationRequest) returns (DeregistrationResponse);
}

service SwarmCoordination {
  rpc CreateSwarm(CreateSwarmRequest) returns (SwarmResponse);
  rpc JoinSwarm(JoinSwarmRequest) returns (JoinSwarmResponse);
  rpc VoteOnTask(SwarmVote) returns (VoteResponse);
  rpc GetSwarmStatus(SwarmStatusRequest) returns (SwarmStatusResponse);
}

service ACAPProtocol {
  rpc AttestCapability(CapabilityAttestation) returns (AttestationResponse);
  rpc VerifyCapability(CapabilityVerification) returns (VerificationResponse);
  rpc RevokeAttestation(RevocationRequest) returns (RevocationResponse);
}

gRPC Endpoints

Agent Mesh gRPC Server: mesh.local.bluefly.io:50051

Authentication

Agent Mesh requires mTLS for gRPC and JWT for REST:

gRPC (mTLS): - Client certificate required - Server certificate verification - Automatic certificate rotation

REST (JWT):

curl -H "Authorization: Bearer <jwt-token>" \
  https://mesh.local.bluefly.io/api/v1/agents/discover

See JWT Authentication for details.

Health & Metrics

Health Check

GET /api/v1/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 86400,
  "services": {
    "grpc": "healthy",
    "registry": "healthy",
    "swarm": "healthy",
    "acap": "healthy"
  },
  "metrics": {
    "totalAgents": 12,
    "activeSwarms": 3,
    "messagesPerSecond": 150,
    "averageLatency": 45
  }
}

Metrics Endpoint

GET /api/v1/metrics

Response (Prometheus format):

# HELP agent_mesh_agents_total Total number of registered agents
# TYPE agent_mesh_agents_total gauge
agent_mesh_agents_total 12

# HELP agent_mesh_tasks_total Total tasks executed
# TYPE agent_mesh_tasks_total counter
agent_mesh_tasks_total 1523

# HELP agent_mesh_latency_seconds Task execution latency
# TYPE agent_mesh_latency_seconds histogram
agent_mesh_latency_seconds_bucket{le="0.1"} 500
agent_mesh_latency_seconds_bucket{le="0.5"} 1200
agent_mesh_latency_seconds_bucket{le="1.0"} 1450

Error Handling

Standard Error Response

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent with ID 'agent-brain-001' not found",
    "details": {
      "agentId": "agent-brain-001",
      "timestamp": "2025-01-15T10:40:00Z"
    },
    "requestId": "req-12345"
  }
}

Common Error Codes

Next Steps