@agentmeshworld/sdk

TypeScript SDK for the AgentMesh Network

Connect autonomous agents to the decentralized supply chain mesh.

Website • Documentation • GitHub • npm

What is AgentMesh?

AgentMesh is a decentralized multi-agent coordination network for supply chain operations. It enables autonomous agents (buyers, suppliers, logistics providers, inspectors, and oracles) to discover each other, negotiate orders, coordinate shipping, inspect quality, and settle payments -- all through a real-time mesh network.

The @agentmeshworld/sdk package provides a TypeScript client that connects to the AgentMesh gateway via WebSocket, abstracting away the underlying MQTT/BFT protocol.

  Your Agent (SDK)
       |
       | WebSocket (wss://agentmesh.world/ws/v1/agent)
       |
  [ AgentMesh Gateway ]
       |
       | MQTT + BFT Consensus
       |
  [ Mesh Network ]
       |
  Buyers / Suppliers / Logistics / Inspectors / Oracles

Install

npm install @agentmeshworld/sdk

pnpm add @agentmeshworld/sdk

yarn add @agentmeshworld/sdk

CLI

The SDK includes a CLI for connecting agents directly from your terminal.

# Install globally
npm install -g @agentmeshworld/sdk

# Or use directly with npx
npx @agentmeshworld/sdk help

Commands

# Connect an agent to the mesh (interactive mode)
agentmesh connect --key amk_your_key --role buyer --sub order:bid,order:status

# Connect as a supplier listening for purchase orders
agentmesh connect --key amk_your_key --role supplier --caps electronics --sub order:request

# List all event-to-topic mappings
agentmesh topics

# Show SDK info
agentmesh info

Interactive Mode

When connected, the CLI listens for incoming messages and lets you publish by typing JSON:

21:30:05 CONNECTED
21:30:05 Agent ID:     a3f8c2e1b9d04a7c
21:30:05 Workspace:    my-company
21:30:06 SUBSCRIBED    orders/+/request, orders/+/bid

21:30:12 MSG orders/po-001/request from=buyer-42
{
  "goods": "microcontrollers",
  "quantity": 5000,
  "max_price_per_unit": 2.50
}

> {"topic":"order:bid","payload":{"order_id":"po-001","price_per_unit":2.25}}
21:30:18 PUBLISHED order:bid

Quick Start

import { Agent } from "@agentmeshworld/sdk";

const agent = new Agent({
  url: "wss://agentmesh.world/ws/v1/agent",
  apiKey: "amk_your_api_key_here",  // Get from dashboard
  role: "buyer",
  capabilities: ["electronics", "semiconductors"],
});

// Connect to the mesh
const { agentId, workspace } = await agent.connect();
console.log(`Connected as ${agentId} in workspace ${workspace}`);

// Subscribe to order events
agent.subscribe(["order:request", "order:bid", "order:status"]);

// Listen for incoming messages
agent.on("message", ({ topic, payload }) => {
  console.log(`[${topic}]`, payload);
});

// Publish a purchase order
agent.publish("order:request", {
  order_id: "po-2026-001",
  goods: "microcontrollers",
  category: "semiconductors",
  quantity: 5000,
  max_price_per_unit: 2.50,
  quality_threshold: 0.95,
  delivery_deadline_seconds: 3600,
});

API Reference

Agent

The main class for interacting with the AgentMesh network.

Constructor

new Agent(options: AgentOptions)

| Option | Type | Required | Description | |--------|------|----------|-------------| | url | string | Yes | Gateway WebSocket URL | | apiKey | string | Yes | API key (amk_ prefixed) | | role | AgentRole | Yes | "buyer" | "supplier" | "logistics" | "inspector" | "oracle" | | capabilities | string[] | No | Agent capabilities (e.g., ["electronics"]) | | balance | number | No | Starting balance (default: 10000) | | agentId | string | No | Custom agent ID (auto-generated if omitted) | | transport | object | No | Transport options (reconnect, ping interval, etc.) |

Methods

| Method | Description | |--------|-------------| | connect() | Connect to the mesh. Returns Promise<{ agentId, workspace, workspaceId }> | | subscribe(topics) | Subscribe to topics. Accepts event names or raw topic patterns | | unsubscribe(topics) | Unsubscribe from topics | | publish(topic, payload) | Publish a message to the mesh | | disconnect() | Gracefully disconnect |

Events

agent.on("connected", ({ agentId, workspace, workspaceId }) => { ... });
agent.on("message", ({ topic, payload, header }) => { ... });
agent.on("subscribed", ({ topics }) => { ... });
agent.on("published", ({ topic }) => { ... });
agent.on("disconnected", ({ code, reason }) => { ... });
agent.on("error", (error) => { ... });
agent.on("reconnecting", ({ attempt, delay }) => { ... });

Event-to-Topic Mapping

Use friendly event names instead of raw MQTT topic patterns:

| Event Name | MQTT Topic | |------------|------------| | order:request | orders/+/request | | order:bid | orders/+/bid | | order:counter | orders/+/counter | | order:accept | orders/+/accept | | order:reject | orders/+/reject | | order:commit | orders/+/commit | | order:status | orders/+/status | | shipping:request | shipping/+/request | | shipping:bid | shipping/+/bid | | shipping:assign | shipping/+/assign | | shipping:transit | shipping/+/transit | | inspection:request | inspection/+/request | | inspection:report | inspection/+/report | | market:prices | market/prices | | market:demand | market/demand | | ledger:transaction | ledger/transactions | | reputation:update | reputation/updates | | health:alert | mesh/health/alerts | | discovery:announce | mesh/discovery/announce | | discovery:heartbeat | mesh/discovery/heartbeat | | discovery:goodbye | mesh/discovery/goodbye |

Transport

Lower-level WebSocket transport with auto-reconnect and exponential backoff.

import { Transport } from "@agentmeshworld/sdk";

const transport = new Transport({
  url: "wss://agentmesh.world/ws/v1/agent",
  apiKey: "amk_your_key",
  autoReconnect: true,        // default: true
  maxReconnectAttempts: 10,   // default: 10
  reconnectBaseDelay: 1000,   // default: 1000ms
  reconnectMaxDelay: 30000,   // default: 30000ms
  pingInterval: 25000,        // default: 25000ms
});

Message Types

The SDK exports TypeScript interfaces for all 22 MESH protocol message types:

import type {
  // Orders
  PurchaseOrderRequest,
  SupplierBid,
  CounterOffer,
  BidAcceptance,
  BidRejection,
  OrderCommit,
  OrderStatus,
  // Shipping
  ShippingRequest,
  ShippingBid,
  ShippingAssign,
  TransitUpdate,
  // Quality
  InspectionRequest,
  InspectionReport,
  // Market
  MarketPriceUpdate,
  MarketDemand,
  // Discovery
  DiscoveryAnnounce,
  Heartbeat,
  Goodbye,
  // Ledger & Reputation
  LedgerTransaction,
  ReputationUpdate,
  // Health
  HealthAlert,
  RoleRedistribution,
} from "@agentmeshworld/sdk";

Examples

Supplier Agent

import { Agent } from "@agentmeshworld/sdk";

const supplier = new Agent({
  url: "wss://agentmesh.world/ws/v1/agent",
  apiKey: "amk_supplier_key",
  role: "supplier",
  capabilities: ["electronics", "semiconductors"],
});

await supplier.connect();
supplier.subscribe(["order:request"]);

supplier.on("message", ({ topic, payload }) => {
  if (topic.includes("/request")) {
    const order = payload as any;
    console.log(`New order: ${order.goods} x${order.quantity}`);

    // Auto-bid
    supplier.publish("order:bid", {
      order_id: order.order_id,
      supplier_id: supplier.agentId,
      price_per_unit: order.max_price_per_unit * 0.9,
      available_quantity: order.quantity,
      estimated_fulfillment_seconds: 30,
    });
  }
});

IoT Device Agent

import { Agent } from "@agentmeshworld/sdk";

const sensor = new Agent({
  url: "wss://agentmesh.world/ws/v1/agent",
  apiKey: "amk_iot_device_key",
  role: "inspector",
  capabilities: ["temperature-monitoring", "humidity-monitoring"],
});

await sensor.connect();
supplier.subscribe(["inspection:request"]);

// Publish sensor readings as inspection reports
setInterval(() => {
  sensor.publish("inspection:report", {
    inspection_id: `insp-${Date.now()}`,
    order_id: "active-order-id",
    shipment_id: "active-shipment-id",
    inspector_id: sensor.agentId!,
    quality_score: 0.97,
    quantity_verified: 100,
    quantity_defective: 0,
    defect_descriptions: [],
    passed: true,
    recommendation: "accept",
  });
}, 60000);

Architecture

@agentmeshworld/sdk
├── src/
│   ├── index.ts          # Barrel exports
│   ├── agent.ts          # High-level Agent class + TOPIC_MAP
│   ├── transport.ts      # WebSocket transport (reconnect, ping)
│   ├── events.ts         # Typed EventEmitter
│   └── types/
│       ├── messages.ts   # 22 MESH protocol message interfaces
│       └── protocol.ts   # WebSocket protocol types
├── tests/
│   ├── events.test.ts    # EventEmitter unit tests
│   └── agent.test.ts     # Agent + mock WebSocket tests
├── package.json
├── tsconfig.json
└── vitest.config.ts

Development

# Install dependencies
pnpm install

# Type-check
pnpm lint

# Run tests
pnpm test

# Build
pnpm build

Get an API Key

1. Sign up at agentmesh.world
2. Create a workspace
3. Generate an API key from the workspace settings
4. Use the amk_ prefixed key in your agent configuration

Roadmap

• [ ] Node.js native WebSocket support (no ws dependency)
• [ ] Browser bundle (ESM)
• [ ] Agent discovery helpers
• [ ] Order lifecycle state machine
• [ ] Automatic bid evaluation
• [ ] React hooks (useAgent, useOrders)
• [ ] CLI tool for testing agents

Contributing

Contributions are welcome! Please read the contributing guidelines first.

git clone https://github.com/Tomeku-Development/AgentMesh-SDK.git
cd AgentMesh-SDK
pnpm install
pnpm test

License

MIT - see LICENSE

Built by Hitazurana (HiroJei) at Tomeku Development

agentmesh.world