Multi-agent workflows you can replay, audit, and trust.

import { graph } from '../../src/graph/definition.js'

export const research = graph('research-swarm')
  .node('plan',      { agent: 'supervisor', llm: 'sarmalink' })
  .node('search',    { agent: 'pipeline',   tools: ['web_search'] })
  .node('analyse',   { agent: 'swarm',      llm: 'sarmalink', concurrency: 3 })
  .node('summarise', { agent: 'pipeline',   llm: 'sarmalink' })
  .edge('plan', 'search')
  .edge('search', 'analyse')
  .edge('analyse', 'summarise')
  .budget({
    tokens: 50000,
    tools: 100,
    wallClockSec: 300,
    perTool: { web_search: 20 },
  })

import { tool } from '../../src/tools/registry.js'
import { z } from 'zod'

export const stripeRefund = tool('stripe_refund', {
  description: 'Refund a Stripe charge by ID',
  schema: z.object({
    chargeId: z.string(),
    amountPence: z.number().int(),
  }),
  handler: async ({ chargeId, amountPence }) => ({
    refundId: `re_${chargeId}`,
    amountPence,
  }),
})

// Reference it by name from any node's tools array.
// Tool calls are validated against the schema and charged
// against the run's tool budget BEFORE the handler runs.

// Edges may carry a 'when' predicate for routing.
.edge('a', 'b')                                          // unconditional
.edge('a', 'b', (ctx) => ctx.input?.confidence > 0.8)    // conditional

// supervisor agents expose their decision on the run context,
// so conditional edges can branch on it.

import { z } from 'zod'
import { registerMcpTool } from '../../src/tools/mcp.js'

registerMcpTool({
  name: 'mcp_lookup',
  description: 'Look up a record on the MCP server',
  schema: z.object({ id: z.string() }),
  serverUrl: 'https://mcp.internal/rpc',
})

// MCP tools share the registry, so they are charged against the
// same tool budget as built-in tools. An agent cannot dodge the
// cap by routing through MCP.

curl -X POST http://localhost:4000/runs \
  -H "Content-Type: application/json" \
  -d '{"graph":"research-swarm","input":{"topic":"deterministic replay"}}'

# Returns { id: "<uuid>", status: "queued" }
# Open the run id in the Inspector to watch the graph light up.

Every node writes a checkpoint after it runs. A replay rehydrates context from the latest checkpoint at or before the requested step and resumes the walk from that cut. Earlier nodes are not re-executed and their outputs are read from the checkpoint, not regenerated. The state machine that walks the graph is pure given the checkpoint, so the same fromStep produces the same continuation.

Through a single RunBudget that owns an AbortController. Every LLM call charges its token usage and every tool call charges one before the handler runs. The wall-clock budget is checked at the start of each node. A breach aborts the AbortSignal, which cancels in-flight LLM and tool calls, throws BudgetExceededError, and lands the run in budget_exceeded.

pipeline runs one LLM pass when an llm is set, then invokes each declared tool in order, useful for "do A then B then C". supervisor runs one LLM pass whose decision is exposed on the run context so conditional edges can branch on it, useful for routing nodes. swarm runs concurrency parallel LLM passes and merges the results, useful for parallel research, though it costs roughly that multiple of the tokens.

No. Leave DATABASE_URL, REDIS_URL, and SARMALINK_API_KEY unset and the API falls back to an in-memory store, runs in-process, and the LLM adapter returns deterministic offline output. This is the same path the test suite uses. For real runs you bring up Postgres and Redis via docker compose.

They register through registerMcpTool and live in the same registry as built-in tools. Because they share the registry and the same callTool path, MCP tools are charged against the same tool budget. An agent cannot dodge the per-tool or global cap by routing through MCP, and a budget breach aborts before the call leaves the box.

BullMQ provides backoff and dead-letter queues. enqueueRun applies the configured retry policy. Failed jobs are retried with exponential backoff; persistent failures land in the DLQ. Without Redis, the orchestrator runs in-process and tests use that mode.

Two places, deliberately. Trace events (enter, exit, error, replay) are rows in the traces table for after-the-fact debugging and the Inspector reads from there. OpenTelemetry spans flow over OTLP/HTTP into your existing collector for live distributed tracing. The first is your durable audit trail; the second plugs into your observability stack.

Yes. The LLM adapter is an interface; SarmaLink is one implementation. OpenAI-compatible providers slot in, and the LLM provider key in node options selects which adapter the executor calls.