triform-agent-client

TypeScript client for connecting to Triform AG-UI Bridge. Provides SSE-based real-time communication with AI agents.

Installation

npm install triform-agent-client

Quick Start

import { TriformClient } from 'triform-agent-client';

// Create a client instance
const client = new TriformClient({
  widgetId: 'beacon',  // Your agent/widget ID
  // sessionId: 'custom-session-id',  // Optional: provide your own session ID
  // baseUrl: 'https://custom-bridge-url.com',  // Optional: custom bridge URL
});

// Set up event listeners
client.on('connected', () => {
  console.log('Connected to Triform');
});

client.on('message_start', (messageId, role, character) => {
  console.log(`New message from ${role}`);
});

client.on('message_content', (messageId, delta) => {
  // Append delta to the message with the given ID
  console.log(delta);
});

client.on('message_end', (messageId) => {
  console.log('Message complete');
});

client.on('awaiting_input', (questionId, prompt) => {
  // Agent is waiting for user input
  console.log('Waiting for input:', prompt);
});

client.on('render_component', (component) => {
  // Render an interactive component (form, select, etc.)
  console.log('Render component:', component.type);
});

// Connect to SSE stream
client.connect();

// Load chat history
const history = await client.loadHistory();
console.log('Previous messages:', history.messages);

// Start a conversation
await client.start('User context information');

// Or send a message
await client.sendMessage('Hello!');

// Answer a pending question
await client.sendMessage('My answer', questionId);

// Submit a component response
await client.sendComponentResponse(componentId, value, questionId);

// Disconnect when done
client.disconnect();

API Reference

Constructor Options

interface TriformClientOptions {
  widgetId: string;       // Required: Agent/widget identifier
  sessionId?: string;     // Optional: Custom session ID (auto-generated if not provided)
  baseUrl?: string;       // Optional: Custom AG-UI Bridge URL
}

Events

| Event | Parameters | Description | |-------|------------|-------------| | connected | - | SSE connection established | | disconnected | - | SSE connection lost | | error | (error: string) | Error occurred | | message_start | (messageId, role, character?) | New message started | | message_content | (messageId, delta) | Message content chunk | | message_end | (messageId) | Message complete | | expression_change | (character) | Character expression changed | | render_component | (component) | Interactive component to render | | activity_start | (id, type, name) | Tool/step activity started | | activity_end | (id, status) | Tool/step activity ended | | run_started | (runId) | Agent run started | | run_finished | (runId) | Agent run finished | | awaiting_input | (questionId, prompt?) | Agent waiting for user input | | history_loaded | (messages) | Chat history loaded | | progress_update | (data) | Progress bar update | | feeling_update | (data) | Character feeling/emotion update | | project_submitted | (projectData) | Project submission complete |

Methods

| Method | Returns | Description | |--------|---------|-------------| | connect() | void | Connect to SSE stream | | disconnect() | void | Disconnect from SSE stream | | reconnect() | void | Force reconnection | | getSessionId() | string | Get current session ID | | getIsConnected() | boolean | Check connection status | | loadHistory() | Promise<LoadHistoryResult> | Load chat history | | start(context?) | Promise<void> | Start agent conversation | | startWithMessage(context, message) | Promise<void> | Start with trigger message | | sendMessage(content, questionId?) | Promise<SendMessageResult> | Send a message | | sendComponentResponse(componentId, value, questionId?) | Promise<void> | Submit component response | | on(event, callback) | () => void | Subscribe to events (returns unsubscribe fn) |

Types

import type {
  CharacterInfo,
  ComponentProps,
  ChatMessage,
  TriformClientEvents,
  TriformClientOptions,
  LoadHistoryResult,
  SendMessageResult,
  ProgressUpdate,
  FeelingUpdate
} from 'triform-agent-client';

License

MIT