@woflowinc/agent-chat

TypeScript SDK for connecting to Woflow agents over WebSocket. Enables real-time chat with agents from any Node.js or browser environment.

Status: WIP — The SDK is functional but still under active development. APIs may change.

Install

npm install @woflowinc/agent-chat
# or
pnpm add @woflowinc/agent-chat

Quick Start

import { WoflowClient } from "@woflowinc/agent-chat";

const client = new WoflowClient({
  apiKey: "your-api-key",
  agentId: "your-agent-id",
});

// Connect to the agent
await client.connect();

// Listen for events
client.on((event) => {
  switch (event.type) {
    case "text":
      // Streaming text chunk
      process.stdout.write(event.content);
      break;
    case "complete":
      // Full response ready
      console.log(event.response.text);
      break;
    case "error":
      console.error(event.error.message);
      break;
  }
});

// Send a message
await client.send("Hello!");

// Disconnect when done
client.disconnect();

Configuration

const client = new WoflowClient({
  apiKey: string;    // Organization API key
  agentId: string;   // Agent ID to connect to
  baseUrl?: string;  // Defaults to https://app.woflow.com
});

Events

The on() callback receives events with a type discriminator:

| Type | Description | |------|-------------| | text | Streaming text chunk (event.content) | | complete | Final response (event.response) | | error | Error occurred (event.error) | | disconnected | WebSocket disconnected (event.reason) | | state_change | Execution state changed | | surface_action | Agent-triggered UI action |

CLI

The package includes a CLI tool for testing agent conversations:

npx @woflowinc/agent-chat \
  --api-key YOUR_API_KEY \
  --agent-id YOUR_AGENT_ID \
  --base-url http://localhost:7777  # optional

Or with environment variables:

export WOFLOW_API_KEY=your-key
export WOFLOW_AGENT_ID=your-agent-id
npx @woflowinc/agent-chat

Publishing

Publishing is automated via GitHub Actions using an npm access token (NPM_TOKEN repo secret). To release a new version:

1. Bump the version in packages/sdk/package.json in the same PR as your changes — don't merge SDK changes without a version bump, it just creates an extra PR
2. After merge, tag the commit: git tag -a agent-chat-v<version> -m "Release @woflowinc/agent-chat v<version>"
3. Push the tag: git push origin agent-chat-v<version>

The version in package.json and the tag must match. The publish-agent-chat workflow builds, tests, and publishes to npm.

Token rotation

The NPM_TOKEN secret is a granular npm access token scoped to @woflowinc/agent-chat with a 90-day expiry (npm's max for write tokens). When it expires, create a new one at npmjs.com/settings/tokens and update the repo secret.

Why not OIDC? npm's OIDC trusted publishing requires --provenance, which requires a public source repo. Since nueve is private, we use a token instead.

Version bumps

This package follows semver. While the version is 0.x.y, the public API is not yet stable:

• Patch (0.1.0 → 0.1.1) — Bug fixes, internal refactors, no API changes
• Minor (0.1.1 → 0.2.0) — New features, new exports, non-breaking additions
• Major (0.x.y → 1.0.0) — Reserved for the first stable release

Once 1.0.0 is released:

• Patch (1.0.0 → 1.0.1) — Bug fixes only
• Minor (1.0.0 → 1.1.0) — New features, backward-compatible additions
• Major (1.0.0 → 2.0.0) — Breaking changes (removed/renamed exports, changed behavior)