← Documentation Home

Agent Mesh Developer Guide

Overview

Package: @bluefly/agent-mesh Version: Latest License: MIT

Backend coordination layer for distributed AI agents and microservices. Provides gRPC server, MCP integration, agent discovery, load balancing, and comprehensive observability.

Key Features

Installation

# Clone and install
git clone https://gitlab.bluefly.io/llm/npm/agent-mesh.git
cd agent-mesh
npm install
npm run build
npm link

Quick Start

# Start gRPC server
npm run grpc:start

# Start orchestrator
npm run orchestrator:start

# Check status
npm run orchestrator:status

# Health check
npm run orchestrator:health

# Full stack (backend + frontend)
npm run backend:dev      # Terminal 1
npm run frontend:dev     # Terminal 2

CLI Commands

Agent Orchestration

# Orchestrate agents
agent-mesh orchestrate --agents agent1,agent2 --task "task-description"

# Discover agents
agent-mesh discover --namespace llm-agents

# Health check
agent-mesh health --all

# Configure routing
agent-mesh route --from agent-a --to agent-b --strategy round-robin

MCP Operations

# List MCP servers
agent-mesh mcp list

# Register MCP server
agent-mesh mcp register --server mcp-server-url

# Invoke MCP tool
agent-mesh mcp invoke --tool tool-name --args '{"key":"value"}'

Observability

# Export metrics to Prometheus
agent-mesh metrics --export prometheus

# Trace specific agent
agent-mesh trace --agent-id agent-123

# Follow agent logs
agent-mesh logs --follow --agent agent-name

API Reference

Key Endpoints

POST /api/v1/agents/register

Register agent in mesh.

Request:

{
  "agentId": "agent-123",
  "name": "Worker Agent",
  "capabilities": ["data-processing", "analysis"],
  "endpoint": "http://agent-123:8080",
  "healthCheck": "/health"
}

GET /api/v1/agents

Discover available agents.

Response:

{
  "agents": [
    {
      "id": "agent-123",
      "name": "Worker Agent",
      "status": "healthy",
      "capabilities": ["data-processing"],
      "load": 0.45
    }
  ]
}

POST /api/v1/orchestrate

Orchestrate task across agents.

{
  "taskId": "task-456",
  "agents": ["agent-123", "agent-456"],
  "workflow": "parallel",
  "payload": { "data": "..." }
}

GET /api/v1/mcp/servers

List registered MCP servers.

POST /api/v1/mcp/invoke

Invoke MCP tool.

{
  "server": "filesystem-server",
  "tool": "read_file",
  "arguments": {
    "path": "/path/to/file"
  }
}

Configuration

Environment Variables

AGENT_MESH_PORT=3005
AGENT_MESH_GRPC_PORT=50051
AGENT_MESH_MCP_ENABLED=true
AGENT_MESH_NAMESPACE=llm-agents

# Observability
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
JAEGER_ENDPOINT=http://localhost:14268/api/traces
PROMETHEUS_PORT=9090

# Security
AGENT_MESH_MTLS_ENABLED=true
AGENT_MESH_CERT_PATH=/path/to/certs

gRPC Server Configuration

config/grpc.yaml:

server:
  host: 0.0.0.0
  port: 50051
  maxConcurrentStreams: 100

security:
  mtls:
    enabled: true
    certPath: /etc/certs/server.crt
    keyPath: /etc/certs/server.key

MCP Configuration

config/mcp.yaml:

mcp:
  enabled: true
  servers:
    - name: filesystem-server
      url: http://localhost:3001
    - name: postgres-server
      url: http://localhost:3002
  timeout: 30000

Examples

Register Agent

import { AgentMesh } from '@bluefly/agent-mesh';

const mesh = new AgentMesh({
  grpcPort: 50051,
  namespace: 'production'
});

// Register agent
await mesh.registerAgent({
  id: 'worker-1',
  name: 'Data Worker',
  capabilities: ['data-processing', 'transformation'],
  endpoint: 'http://worker-1:8080',
  metadata: {
    version: '1.0.0',
    region: 'us-east-1'
  }
});

Orchestrate Task

// Orchestrate across multiple agents
const result = await mesh.orchestrate({
  agents: ['worker-1', 'worker-2', 'worker-3'],
  task: {
    type: 'data-pipeline',
    payload: {
      source: 's3://bucket/data.json',
      destination: 'postgresql://db/table'
    }
  },
  strategy: 'round-robin',
  timeout: 60000
});

console.log('Task result:', result);

MCP Integration

import { MCPClient } from '@bluefly/agent-mesh';

// Connect to MCP server
const client = new MCPClient('http://localhost:3001');

// List available tools
const tools = await client.listTools();

// Invoke tool
const result = await client.invokeTool('read_file', {
  path: '/path/to/file'
});

Agent Discovery

// Discover agents by capability
const agents = await mesh.discoverAgents({
  capabilities: ['data-processing'],
  status: 'healthy',
  maxLoad: 0.8
});

console.log('Available agents:', agents);

gRPC Services

Defined in proto/agent-mesh.proto:

Observability Stack

Phoenix Arize

# Initialize
npm run phoenix:init

# View traces
open http://localhost:6006

Prometheus

# Export metrics
curl http://localhost:3005/metrics

# View in Grafana
open http://localhost:3000

Jaeger

# View distributed traces
open http://localhost:16686

Testing

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# E2E tests
npm run test:e2e

# Coverage
npm run test:coverage

Deployment

Kubernetes

# Deploy to dev
kubectl apply -f infrastructure/kubernetes/dev/

# Using Helm
helm upgrade --install agent-mesh ./helm/

Docker

# Build and run
docker-compose up -d

Documentation