octoflow-adapters

Platform and chat adapters for delivering OctoFlow agents across existing product surfaces. Use it to connect one bridge or agent transport to CLI, Telegram, Discord, Slack, WhatsApp, Teams, Matrix, LINE, Twitch, and Mattermost.

Install

npm install octoflow-core octoflow-adapters

Node.js >=20 is required. Most platform SDKs are optional peer dependencies; install only the adapters you use.

Use It When

• You want an agent inside an existing chat surface without rewriting the agent runtime.
• You need one runtime that can fan out to multiple platforms.
• You want consistent inbound message normalization, conversation keys, send/edit capability handling, and shutdown.
• You need a local CLI adapter for development and smoke testing.

30-Second Start

import { createAgent } from 'octoflow-core';
import { createAdapterRuntime, createTelegramAdapter } from 'octoflow-adapters';

const agent = await createAgent({
  priority: ['anthropic-api', 'openai-api'],
  context: { identity: 'You are a helpful assistant.' },
});

const telegram = createTelegramAdapter({
  botToken: process.env.TELEGRAM_TOKEN!,
  allowedChatIds: process.env.TELEGRAM_CHAT_ID?.split(',').map(Number),
});

const runtime = createAdapterRuntime({
  transport: { kind: 'bridge', bridge: agent.bridge },
  adapters: [telegram],
});

await runtime.start();

Close both runtime and bridge during shutdown:

await runtime.close();
await agent.close();

Adapter Catalog

| Adapter | Factory | Dependency | Conversation key shape | | ---------- | --------------------------- | --------------------------------- | ------------------------------------------ | | CLI | createCliAdapter() | none | cli:terminal | | Discord | createDiscordAdapter() | discord.js | discord:<guild\|dm>:<channel>[:<thread>] | | LINE | createLineAdapter() | @line/bot-sdk | line:<type>:<sourceId> | | Matrix | createMatrixAdapter() | matrix-js-sdk | matrix:<roomId> | | Mattermost | createMattermostAdapter() | native fetch + WebSocket | mattermost:<team>:<channel>[:<rootId>] | | Slack | createSlackAdapter() | @slack/bolt | slack:<team>:<channel>[:<threadTs>] | | Teams | createTeamsAdapter() | botbuilder | teams:<channelId>:<convId> | | Telegram | createTelegramAdapter() | grammy | telegram:<chatId>[:<threadId>] | | Twitch | createTwitchAdapter() | @twurple/auth + @twurple/chat | twitch:<channel> | | WhatsApp | createWhatsAppAdapter() | @whiskeysockets/baileys | whatsapp:<jid> |

Local CLI Smoke Test

import { createAgent } from 'octoflow-core';
import { createAdapterRuntime, createCliAdapter } from 'octoflow-adapters';

const agent = await createAgent({ priority: ['ollama'] });
const runtime = createAdapterRuntime({
  transport: { kind: 'bridge', bridge: agent.bridge },
  adapters: [createCliAdapter({ prompt: '> ' })],
});

await runtime.start();

Extension Points

• BaseAdapter handles lifecycle boilerplate for custom adapters.
• ChannelAdapter is the direct adapter contract.
• createPlatformGateway() runs multiple adapters behind one transport.
• ConversationBindingStore can be replaced with Redis, SQL, or your app store.
• BridgeTransport can point at a local bridge or remote A2A endpoint.

Learn More

• ../../docs/adapters.md - platform setup and gateway behavior.
• ../octoflow-examples/src/adapters - runnable platform examples.
• ../octoflow-core - runtime these adapters connect to.

Validate

npm run -w octoflow-adapters lint
npm run -w octoflow-adapters typecheck
npm run -w octoflow-adapters test

Status

Preview. Pin versions and read ../../CHANGELOG.md before depending on it in production.