TypeScript Channel Client

@swarmd.ai/channel-client is the recommended way to connect a website, bot, or backend service to an agent through a Swarmd channel. It wraps the Conversation REST API and handles:

OAuth2 client-credentials exchange, token caching, and refresh
deriving channelId from the standard channel-{channelId} client ID
conversation creation and follow-up message continuity
the send fast path and background polling
typed lifecycle events for working, hitl-held, and terminal outcomes
cancellation with AbortSignal
text and artifact reply extraction
structured authentication, API, and polling errors

clientSecret is a server credential. Use this library in a Node.js server, API route, server action, worker, or other trusted backend. The client refuses to initialize when it detects a browser. Never put the secret in a NEXT_PUBLIC_*, VITE_*, or other client-exposed environment variable.

Install

npm install @swarmd.ai/channel-client

Node.js 18 or later is supported. The package has no runtime dependencies and uses the built-in Fetch API.

Before You Start

In the Swarmd dashboard:

Create a channel for the website or service.
Save the returned clientId and clientSecret. The secret is shown only when the channel is created.
Subscribe the channel to the agent it should invoke.
Copy the subscribed agent’s agentId.

Prefer to script it? The same four steps are POST /registry/v1/channels and POST /registry/v1/channels/{channelId}/subscriptions — see the API reference. Configure server-only environment variables:

SWARMD_CHANNEL_CLIENT_ID=channel-d4ac7a03-e833-434f-badc-c2833e0b10af
SWARMD_CHANNEL_CLIENT_SECRET=replace-me
SWARMD_AGENT_ID=4a411d26-dec0-4553-a164-96ccecf0ecb9

The client derives channelId from clientId. If your OAuth client does not use the standard channel-{channelId} form, also pass the channel UUID as channelId.

Quick Start

Create one reusable client on the server:

// lib/swarmd.ts — server-only module
import { SwarmdChannelClient } from '@swarmd.ai/channel-client';

export const swarmd = new SwarmdChannelClient({
  clientId: process.env.SWARMD_CHANNEL_CLIENT_ID!,
  clientSecret: process.env.SWARMD_CHANNEL_CLIENT_SECRET!,
});

Start a conversation and wait for the first reply:

import { extractReply } from '@swarmd.ai/channel-client';
import { swarmd } from './lib/swarmd';

const state = await swarmd.startAndSend(
  process.env.SWARMD_AGENT_ID!,
  'Shortlist the top three candidates for JR-1007.',
);

console.log(state.contextId);       // persist for follow-up turns
console.log(state.aggregateState); // COMPLETED, REJECTED, FAILED, or CANCELED
console.log(extractReply(state));   // agent prose, including artifact output

startAndSend creates a conversation, sends the message, and polls if the relay has not completed during its early-return window.

Complete Next.js Example

This example starts with a standard TypeScript Next.js application and ends with a browser chat connected to a Swarmd channel.

1. Create the project

npx create-next-app@latest swarmd-chat --typescript --app
cd swarmd-chat
npm install @swarmd.ai/channel-client

The example uses this structure:

swarmd-chat/
├── app/
│   ├── api/chat/route.ts
│   └── page.tsx
├── lib/
│   └── swarmd.ts
└── .env.local

2. Connect the channel

Create a channel in Swarmd, subscribe it to the agent your website should invoke, and copy:

the channel clientId
the channel clientSecret
the subscribed agent’s agentId

Add them to .env.local. These variables deliberately have no NEXT_PUBLIC_ prefix, so Next.js keeps them on the server:

SWARMD_CHANNEL_CLIENT_ID=channel-d4ac7a03-e833-434f-badc-c2833e0b10af
SWARMD_CHANNEL_CLIENT_SECRET=replace-me
SWARMD_AGENT_ID=4a411d26-dec0-4553-a164-96ccecf0ecb9

3. Create the server-side client

// lib/swarmd.ts
import 'server-only';
import { SwarmdChannelClient } from '@swarmd.ai/channel-client';

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

export const swarmd = new SwarmdChannelClient({
  clientId: required('SWARMD_CHANNEL_CLIENT_ID'),
  clientSecret: required('SWARMD_CHANNEL_CLIENT_SECRET'),
});

export const swarmdAgentId = required('SWARMD_AGENT_ID');

Exporting one client lets every request share the OAuth token cache.

4. Add the server route

The browser sends only the user’s message and its current contextId. The route creates the conversation on the first turn and reuses it on later turns.

// app/api/chat/route.ts
import { extractReply, SwarmdApiError } from '@swarmd.ai/channel-client';
import { NextResponse } from 'next/server';
import { swarmd, swarmdAgentId } from '@/lib/swarmd';

export const runtime = 'nodejs';

export async function POST(request: Request) {
  const body = await request.json() as {
    message?: string;
    contextId?: string;
  };
  const message = body.message?.trim();

  if (!message) {
    return NextResponse.json(
      { error: 'message is required' },
      { status: 400 },
    );
  }

  try {
    const contextId = body.contextId ?? (
      await swarmd.createConversation(swarmdAgentId, {
        signal: request.signal,
      })
    ).contextId;

    const state = await swarmd.sendAndWait(contextId, message, {
      signal: request.signal,
      timeoutMs: 5 * 60_000,
    });

    return NextResponse.json({
      contextId,
      aggregateState: state.aggregateState,
      reply: extractReply(state),
      relayReason: state.latestTask?.metadata?.relay_reason,
    });
  } catch (error) {
    if (error instanceof SwarmdApiError) {
      return NextResponse.json(
        {
          error: 'Swarmd rejected the request',
          status: error.status,
          details: error.body,
        },
        { status: error.status },
      );
    }
    throw error;
  }
}

5. Call the route from the browser

// app/page.tsx
'use client';

import { FormEvent, useState } from 'react';

interface ChatReply {
  contextId: string;
  aggregateState: string;
  reply?: string;
  relayReason?: string;
}

export default function Home() {
  const [contextId, setContextId] = useState<string>();
  const [message, setMessage] = useState('');
  const [reply, setReply] = useState('');
  const [status, setStatus] = useState('Ready');

  async function send(event: FormEvent) {
    event.preventDefault();
    setStatus('Agent is working');

    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message, contextId }),
    });
    const result = await response.json() as ChatReply & { error?: string };

    if (!response.ok) {
      setStatus(result.error ?? 'Request failed');
      return;
    }

    setContextId(result.contextId);
    setReply(result.reply ?? 'No text reply');
    setStatus(result.aggregateState);
    setMessage('');
  }

  return (
    <main>
      <form onSubmit={send}>
        <input
          value={message}
          onChange={event => setMessage(event.target.value)}
          placeholder="Ask the agent..."
        />
        <button disabled={!message.trim()}>Send</button>
      </form>

      <p>Status: {status}</p>
      {reply && <p>{reply}</p>}
    </main>
  );
}

Run the project:

npm run dev

The first message creates a durable conversation. The response returns its contextId, and the component includes that ID in subsequent messages so the agent retains the conversation history.

This compact example keeps the /api/chat request open while the SDK polls. That is suitable for ordinary flows. If an approval may take minutes or hours, return the initial sendMessage state to the browser and expose a separate state endpoint, as shown in the split send-and-poll flow below.

Handle Lifecycle Events

For most integrations, onEvent is the idiomatic way to react to progress. Events are a discriminated union, so TypeScript narrows the available fields inside each case.

import type { ConversationEvent } from '@swarmd.ai/channel-client';

function handleEvent(event: ConversationEvent) {
  switch (event.type) {
    case 'working':
      console.log('The agent is working');
      break;

    case 'hitl-held':
      console.log('Waiting for human review:', event.reason);
      break;

    case 'completed':
      console.log('Agent reply:', event.reply);
      break;

    case 'rejected':
      console.log('The reviewer rejected the action:', event.reason);
      break;

    case 'failed':
      console.error('The agent flow failed:', event.reason);
      break;

    case 'canceled':
      console.log('The conversation was canceled');
      break;

    default: {
      // Makes this switch fail type-checking if a future SDK version adds
      // an event and the application has not handled it.
      const exhaustive: never = event;
      return exhaustive;
    }
  }
}

const finalState = await swarmd.sendAndWait(contextId, message, {
  onEvent: handleEvent,
});

The callback fires for the initial send response and whenever the lifecycle event changes. Repeated polls in the same state are de-duplicated. Applications do not need to interpret HTTP 200 versus 202, inspect task status, or decide when polling should stop. Use the lower-level onState callback if you need every state snapshot instead.

Event	Useful fields	Meaning
`working`	`state`, `contextId`	The conversation is starting or executing
`hitl-held`	`reason`, `state`	A reviewer or caller must provide input
`completed`	`reply`, `state`	The flow completed and the reply was extracted
`rejected`	`reason`, `state`	A reviewer declined the held action
`failed`	`reason`, `state`	A policy or upstream error ended the flow
`canceled`	`state`	The caller canceled the flow

Every event includes the original ConversationState as event.state, so uncommon metadata and per-task progress remain available without weakening the common API.

Async event stream

Use sendEvents when events fit more naturally into an async pipeline or an SSE/WebSocket handler:

for await (const event of swarmd.sendEvents(contextId, message, {
  pollIntervalMs: 2_000,
  timeoutMs: 30 * 60_000,
})) {
  switch (event.type) {
    case 'working':
    case 'hitl-held':
      await publishProgressToBrowser(event);
      break;
    case 'completed':
      await publishReplyToBrowser(event.reply);
      break;
    case 'rejected':
    case 'failed':
    case 'canceled':
      await publishTerminalOutcomeToBrowser(event);
      break;
  }
}

The iterable ends automatically after a terminal event. watchConversation(contextId) provides the same event stream without sending a new message, which is useful when resuming a persisted conversation.

The package deliberately does not expose a React hook that talks directly to Swarmd: doing so would place the channel secret in the browser bundle. A React application should consume its own API route, SSE stream, or WebSocket and map these server-side lifecycle events into component state.

What the SDK is doing for you

Worth understanding once, because it explains why pending and waitForTerminal exist at all. A conversation send is not a request that blocks until the agent answers. The relay runs the chain on a background thread and hands your socket back early:

Response	Meaning	What the SDK does
`200 OK`	The chain settled inside the early-return window	`pending: false` — the state you get back is already terminal
`202 Accepted`	Still running; body carries `aggregateState: 'WORKING'`	`pending: true` — poll `GET /state` until the aggregate goes terminal

The window is swarmd.agent-relay.early-return-timeout-ms, 100 seconds by default — chosen to match Cloudflare’s origin cutoff, since a browser’s call cannot outlive it anyway. Typical cross-tenant chains (a couple of LLM turns plus MCP calls) land in the 40–60 second range, so most sends come back 200 and never touch the polling path.

Build for 202 regardless. It is the same body shape, and a slow sink is the case you do not control. sendAndWait handles both for you; the split methods below let you show WORKING in the UI while it happens.

The response body is a ConversationState in both cases — one shape, no polymorphism. Your code reads aggregateState rather than branching on the HTTP status.

Why a stable contextId rather than a long-lived call

The older JSON-RPC path held one HTTP call open for an entire run. That breaks on everything real: CDN idle cutoffs, mobile network churn, a browser suspending a background tab.The conversation model replaces it with one stable contextId and a state URL you can poll from anywhere, any number of times. A dropped socket costs you nothing — the work continues server-side and the next poll picks it up. That is also why SwarmdPollingTimeoutError carries contextId: the work is durable, so you can resume polling later rather than losing the turn.

Split Send and Poll Flow

Use the low-level methods when your frontend needs to show WORKING or HITL_HELD immediately.

const created = await swarmd.createConversation(agentId);

const { state, pending } = await swarmd.sendMessage(
  created.contextId,
  'Apply the shortlist decision.',
);

if (!pending) {
  // state is already terminal
  return state;
}

const final = await swarmd.waitForTerminal(created.contextId, {
  pollIntervalMs: 2_000,
  maxPollIntervalMs: 10_000,
  timeoutMs: 30 * 60_000,
  onState(state) {
    if (state.aggregateState === 'HITL_HELD') {
      // Notify your UI, log progress, or persist resumable state.
      console.log(state.latestTask?.metadata?.relay_reason);
    }
  },
});

sendMessage uses aggregateState, not only the HTTP status, to decide whether work is pending. waitForTerminal stops on COMPLETED, REJECTED, FAILED, or CANCELED.

Handling UI States

`aggregateState`	Terminal	Suggested UI
`UNKNOWN`	No	Starting
`WORKING`	No	Agent is working
`HITL_HELD`	No	Waiting for human review
`COMPLETED`	Yes	Render `extractReply(state)`
`REJECTED`	Yes	Review was declined
`FAILED`	Yes	Request failed; inspect `latestTask.metadata`
`CANCELED`	Yes	Request was canceled

CANCELED is in the SDK’s terminal set for safety, but the relay’s rollup does not currently emit it — a cancelled task is folded into the aggregate as settled. In practice a turn ends on COMPLETED, REJECTED, or FAILED.

For HITL_HELD, inspect state.latestTask?.metadata?.relay_reason:

HITL_HELD means a policy or action needs reviewer approval.
HITL_HELD_AGENT_INPUT_REQUIRED means the agent requested human input.

Approval happens in the Swarmd dashboard, or through the approvals API with a user token — GET /relay/v1/approvals to list pending requests, GET /relay/v1/approvals/{id} to read one, and POST /relay/v1/approvals/{id}/resolve with { "action": "APPROVED" | "REJECTED", "message": "..." } to settle it. A channel token cannot resolve an approval; the endpoints require HITL_REQUESTS:READ / HITL_REQUESTS:WRITE. The channel client keeps polling either way and observes the result. Approval normally leads to COMPLETED; rejection leads to REJECTED.

Conversation Continuity

Create a conversation once per chat session and reuse its contextId:

const conversation = await swarmd.createConversation(agentId);

await swarmd.sendAndWait(conversation.contextId, 'Show open roles.');
await swarmd.sendAndWait(conversation.contextId, 'Only roles in London.');

The conversation remains durable on the relay. Store the contextId if polling must resume after a tab closes or a process restarts:

const state = await swarmd.getConversationState(savedContextId);
const final = state.aggregateState === 'WORKING'
  ? await swarmd.waitForTerminal(savedContextId)
  : state;

For long histories:

const page = await swarmd.listMessages(contextId, { page: 0, size: 50 });

Custom Messages and Cancellation

Send structured A2A parts instead of plain text:

await swarmd.sendMessage(contextId, '', {
  parts: [
    { kind: 'text', text: 'Review this application' },
    { kind: 'data', data: { applicationId: 'APP-001' } },
  ],
});

Cancel local waiting with an AbortSignal:

const controller = new AbortController();

const result = swarmd.waitForTerminal(contextId, {
  signal: controller.signal,
});

controller.abort(new Error('User left the page'));
await result;

This stops the local request or poll loop; it does not cancel server-side agent work.

Errors

import {
  SwarmdApiError,
  SwarmdAuthenticationError,
  SwarmdConfigurationError,
  SwarmdPollingTimeoutError,
} from '@swarmd.ai/channel-client';

try {
  await swarmd.sendAndWait(contextId, message);
} catch (error) {
  if (error instanceof SwarmdAuthenticationError) {
    // Invalid client ID/secret or token endpoint configuration.
  } else if (error instanceof SwarmdPollingTimeoutError) {
    // Work is durable. Save error.contextId and resume polling later.
  } else if (error instanceof SwarmdApiError) {
    console.error(error.status, error.method, error.path, error.body);
  }
}

Every error extends SwarmdError. SwarmdConfigurationError is thrown up front for bad construction — a missing clientId or clientSecret, a non-standard clientId with no channelId alongside it, no Fetch implementation, or a browser environment — so it will not appear inside a send. SwarmdApiError carries status, method, path, and the parsed body; SwarmdAuthenticationError extends it and is what a 401 becomes after the retry below fails.

A policy block does not surface as an exception. The relay absorbs it into the conversation state, so the call resolves with aggregateState: 'FAILED' and state.latestTask?.metadata?.relay_reason === 'POLICY_BLOCKED'. Check the terminal state, not just the catch.

Reading `relay_reason`

On a FAILED (or REJECTED) terminal state, latestTask.metadata.relay_reason says why:

Value	Cause
`POLICY_BLOCKED`	A policy rule blocked the message
`HITL_REJECTED`	A reviewer declined a held message — a human decision, render it distinctly from a failure
`SINK_UNAVAILABLE`	The target agent could not be reached
`AGENT_TIMEOUT`	The target agent did not answer in time
`AGENT_HTTP_<status>`	The target agent returned that HTTP status, e.g. `AGENT_HTTP_500`
`AUTH_DENIED`	The caller is not authorised to reach that agent
`MCP_BAD_RESPONSE`	An MCP server returned something unusable
`FROZEN_<scope>`	The agent or its tenant is frozen
`SSRF_<reason>`	The target URL failed the relay’s SSRF checks
`INTERNAL_ERROR`	Anything else

Surface a generic message to end users and log the reason — most of these are operator problems, not something the person typing can fix. The client caches OAuth tokens until 30 seconds before expiry. If an API request returns 401, it clears the cached token, obtains a fresh token, and retries that request once.

Configuration

const swarmd = new SwarmdChannelClient({
  clientId: 'channel-d4ac7a03-e833-434f-badc-c2833e0b10af',
  clientSecret: '...',

  // Optional (defaults shown):
  channelId: 'd4ac7a03-e833-434f-badc-c2833e0b10af', // derived from clientId
  baseUrl: 'https://api.dev.swarmd.ai',
  tokenUrl: 'https://auth.dev.swarmd.ai/realms/swarmd/protocol/openid-connect/token',
  scope: 'mcp:call',
  fetch: globalThis.fetch,          // supply your own Fetch implementation
  dangerouslyAllowBrowser: false,   // see the warning at the top of this page
});

Only override URLs or scope for a Swarmd environment whose operator supplied different values, and always override baseUrl and tokenUrl together — a base URL and token URL from different environments mints tokens the gateway rejects on audience. fetch exists so you can inject an instrumented or proxied implementation; dangerouslyAllowBrowser lifts the browser guard and should stay false outside a controlled runtime that merely exposes browser globals. Polling defaults, applied by waitForTerminal, sendAndWait, sendEvents, and watchConversation:

Option	Default
`pollIntervalMs`	`2000`
`maxPollIntervalMs`	the value of `pollIntervalMs`, i.e. no backoff unless you raise it
`timeoutMs`	`300000` (5 minutes)

Raise maxPollIntervalMs above pollIntervalMs to get exponential backoff — the interval grows by 1.5x per poll up to that ceiling. Raise timeoutMs for HITL flows, where an approval can take hours.

Method Reference

Method	Purpose
`createConversation(agentId)`	Start a durable conversation
`sendMessage(contextId, text, options?)`	Send one turn; return `{ state, pending }`
`getConversationState(contextId)`	Read the current state once
`waitForTerminal(contextId, options?)`	Poll until a terminal aggregate
`sendAndWait(contextId, text, options?)`	Send a turn and poll when needed
`startAndSend(agentId, text, options?)`	Create, send, and poll in one call
`sendEvents(contextId, text, options?)`	Send and stream typed lifecycle events
`watchConversation(contextId, options?)`	Stream events for existing work
`listMessages(contextId, options?)`	Read paginated history
`clearToken()`	Force a fresh OAuth token on the next request

Python

Build your agent

Migrating an existing agent

Python reference

TypeScript

Channel Client

TypeScript Channel Client

Install

Before You Start

Quick Start

Complete Next.js Example

1. Create the project

2. Connect the channel

3. Create the server-side client

4. Add the server route

5. Call the route from the browser

Handle Lifecycle Events

Async event stream

What the SDK is doing for you

Split Send and Poll Flow

Handling UI States

Conversation Continuity

Custom Messages and Cancellation

Errors

Reading `relay_reason`

Configuration

Method Reference

​TypeScript Channel Client

​Install

​Before You Start

​Quick Start

​Complete Next.js Example

​1. Create the project

​2. Connect the channel

​3. Create the server-side client

​4. Add the server route

​5. Call the route from the browser

​Handle Lifecycle Events

​Async event stream

​What the SDK is doing for you

​Split Send and Poll Flow

​Handling UI States

​Conversation Continuity

​Custom Messages and Cancellation

​Errors

​Reading relay_reason

​Configuration

​Method Reference

TypeScript Channel Client

Install

Before You Start

Quick Start

Complete Next.js Example

1. Create the project

2. Connect the channel

3. Create the server-side client

4. Add the server route

5. Call the route from the browser

Handle Lifecycle Events

Async event stream

What the SDK is doing for you

Split Send and Poll Flow

Handling UI States

Conversation Continuity

Custom Messages and Cancellation

Errors

Reading `relay_reason`

Configuration

Method Reference