@proteus-ai/sdk

A realtime, streaming-first JavaScript/TypeScript SDK for messaging with ProteusAI. It focuses on the messaging surface of ProteusAI — agents, chats, messages, and repositories — and keeps a live socket connection so that agent responses can be streamed back to your app token-by-token.

It talks to the ProteusAI messaging service (proteusai-rest-api-service):

• REST for managing agents, creating chats, reading message history, and repositories.
• Realtime (socket.io) for sending messages and receiving streamed responses.

Installation

npm install @proteus-ai/sdk
# or
yarn add @proteus-ai/sdk

Quick start

import ProteusAI from '@proteus-ai/sdk';

const proteus = new ProteusAI({
  apiKey: 'user-xxxxx', // a Proteus access token ("user-..." or "inst-...")
  // baseUrl: 'http://localhost:3000', // defaults to the hosted messaging service
});

await proteus.connect(); // resolves once the realtime connection is authenticated

// 1. Start a chat with an agent (you are added as a participant automatically)
const chat = await proteus.chats.create({
  participants: [{ id: '<agentId>', type: 'AGENT' }],
});

// 2. Join the chat's realtime room to receive the response stream
await proteus.chats.join(chat.id);

// 3. Listen for streamed chunks and the final message
proteus.messages.onDelta(({ contentDelta }) => {
  process.stdout.write(contentDelta ?? ''); // each new chunk
});
proteus.messages.onDone((message) => {
  console.log('\nFinal answer:', message.content);
});

// 4. Send a message
await proteus.chats.send(chat.id, 'In one sentence, what is the web?');

Configuration

new ProteusAI({
  apiKey: string;        // access token, sent as `Authorization: Bearer <apiKey>` and the socket auth token
  authToken?: string;    // optional Proteus auth (JWT) token, sent as `x-proteus-auth-token`
  apiUrl?: string;       // the API URL to connect to (REST + realtime); alias: baseUrl
  baseUrl?: string;      // alias of apiUrl
  autoConnect?: boolean; // connect the socket on construction (default: true)
});

Specifying the API URL

By default the SDK connects to the hosted service (https://messaging-api.useproteus.ai). To point it at a local or self-hosted deployment, set apiUrl (used for both REST and the realtime connection):

const proteus = new ProteusAI({ apiKey, apiUrl: 'http://localhost:3000' });

The URL is resolved in this order (highest precedence first):

1. apiUrl
2. baseUrl (alias of apiUrl)
3. PROTEUS_API_URL / PROTEUS_BASE_URL environment variable (Node)
4. the hosted default

So you can also configure it without code changes:

PROTEUS_API_URL=http://localhost:3000 node your-app.js

Connection management

await proteus.connect();          // connect + wait for authentication
proteus.connected(() => { ... }); // callback fired once authenticated
proteus.isConnected;              // boolean
proteus.isConnecting;             // boolean
proteus.disconnect();             // close the socket

Agents (proteus.agents)

const agent = await proteus.agents.create({
  name: 'Support Bot',
  goal: 'Help users with billing questions',
  orgId: '<orgId>',
  isPublic: true,
});

await proteus.agents.getById(agent.id);
await proteus.agents.update(agent.id, { description: 'Updated' });
await proteus.agents.getMcps(agent.id);
await proteus.agents.delete(agent.id);

Chats (proteus.chats)

// Create a chat
const chat = await proteus.chats.create({
  participants: [{ id: '<agentId>', type: 'AGENT' }],
  // key: 'my-stable-chat-key', // optional: reuse the same logical chat
  // title: 'Billing help',
});

// Read message history (supports pagination)
const messages = await proteus.chats.getMessages(chat.id, { limit: 50 });

// Realtime room membership
await proteus.chats.join(chat.id);
await proteus.chats.leave(chat.id);

// Send a message (string shorthand or full payload)
await proteus.chats.send(chat.id, 'Hello!');
await proteus.chats.send(chat.id, { content: 'Hello!', type: 'TEXT' });

// Listen to events scoped to a single chat (returns an unsubscribe fn)
const off = proteus.chats.on(chat.id, 'message', (message) => console.log(message));
off();

Messages (proteus.messages)

Messages are sent and received over the realtime connection.

// Send (you can also use proteus.chats.send for a known chat)
const { message, chatId } = await proteus.messages.send({
  chatId: '<chatId>',
  content: 'Hello!',
  // or omit chatId and pass chatKey + recipients to start/locate a chat
});

The value returned by send is your outgoing message (now persisted with an id), not the agent's reply. Replies arrive asynchronously via the listeners below.

Listening & streaming

// Every complete message added to a joined chat
proteus.messages.onMessage((message) => { ... });

// Streaming chunks of an agent response
proteus.messages.onDelta((delta) => {
  // delta.contentDelta -> the new chunk
  // delta.content      -> the message so far
  // delta.streamId     -> groups chunks of the same response
});

// The final message that closes a streamed response
proteus.messages.onDone((message) => { ... });

// Low-level: any realtime event (e.g. 'CHAT_STATE_UPDATED')
const off = proteus.messages.on('CHAT_STATE_UPDATED', (evt) => { ... });

All listener methods return an unsubscribe function.

How streaming works: agents respond by posting messages back to the service. While streaming, each chunk is a message with isStreaming: true and an incremental contentDelta sharing a streamId; the service relays these to you as message:delta events and emits message:done for the final message. Non-streamed replies arrive as a single message event.

Repositories (proteus.repositories)

const repo = await proteus.repositories.create({ name: 'Docs', orgId: '<orgId>' });
await proteus.repositories.getById(repo.id);
await proteus.repositories.getFiles(repo.id);

Notes

• Ensure the connection is established before sending; either await proteus.connect() first, or send inside proteus.connected(() => { ... }).
• You can only join and stream chats that you (the authenticated entity) participate in.

License

MIT