@collabrachain/orchestrator

Compose paid AI agents (x402 + ACP) under a budget. One call returns a composed answer plus a per-agent payment trace.

Install

npm install @collabrachain/orchestrator

Use

import { runSwarm, createX402Executor, llmAggregator } from "@collabrachain/orchestrator";

const result = await runSwarm({
  objective: "Is SOL liquidation cascading?",
  budget: 0.20,
  agents: [
    { id: "helius",   fqn: "helius/rpc/health",         executor: "x402", endpoint: "https://api.helius.xyz/...", pricing: { amount: 0.01, currency: "USDC" } },
    { id: "dune",     fqn: "dune/query/liquidations",   executor: "x402", endpoint: "https://api.dune.com/...",   pricing: { amount: 0.05, currency: "USDC" } },
    { id: "sentinel", fqn: "collabrachain/sentinel",    executor: "x402", endpoint: "https://agent.collabrachain.fun/api/percolator/snapshot", pricing: { amount: 0.01, currency: "USDC" } },
  ],
  aggregator: llmAggregator,
  executors: { x402: createX402Executor() },
});

console.log(result.result);    // composed answer
console.log(result.trace);     // per-agent: txHash, costUsdc, latencyMs, status
console.log(result.traceUrl);  // public, signed

What it does

• Selects agents from your pool against the objective (relevance + provider-dedup + price fallback).
• Enforces a per-call budget ceiling. Agents that don't fit get a skipped trace entry, not silent omission.
• Runs every selected agent in parallel through a per-protocol executor (x402 over @faremeter/fetch, ACP via the bundled adapter).
• Aggregates the traces through an LLM (default) or a caller-supplied function and returns a single composed string.
• Records every payment — tx hash, cost in USDC, latency, status — in the trace returned alongside the result.

Compose Pay.sh providers in 4 lines

import { runSwarm, createX402Executor, llmAggregator } from "@collabrachain/orchestrator";

const { result, trace } = await runSwarm({
  objective: "Best L1 to launch a memecoin on this week?",
  budget: 0.30,
  agents: paySh,                                 // any Pay.sh-shaped agent[]
  aggregator: llmAggregator,
  executors: { x402: createX402Executor() },
});

Why

Paying multiple agents reliably is incomplete without orchestration. You can call any one of them by hand. Calling four of them, under a budget, with a trace that proves you paid, is what runSwarm does in one line.

Manifests

If your service exposes paid HTTP endpoints, the package can also generate the four well-known manifests Pay.sh and MCP clients expect:

import { generateApiCatalog, generateMcpServerCard, generateAgentSkillsIndex, generateX402Manifest } from "@collabrachain/orchestrator";

app.get("/.well-known/api-catalog", (_, res) => res.json(generateApiCatalog(OPENAPI_SPEC)));
app.get("/.well-known/mcp/server-card.json", (_, res) => res.json(generateMcpServerCard(OPENAPI_SPEC)));
app.get("/.well-known/agent-skills/index.json", (_, res) => res.json(generateAgentSkillsIndex(OPENAPI_SPEC)));
app.get("/.well-known/x402", (_, res) => res.json(generateX402Manifest(OPENAPI_SPEC)));

OpenAPI paths annotated with x-payment-info and x-fqn are picked up automatically.

Demo

Live composed-answer demo: https://agent.collabrachain.fun/demo

Status

v0.1 — bundles x402 + ACP adapters. Stable surface: runSwarm, the executor types, the manifest generators. Aggregator + scorer are pluggable.

License

MIT