@standardagents/client

Framework-agnostic client library for Standard Agents - provides HTTP/WebSocket communication, connection management, and shared utilities used by @standardagents/react and @standardagents/vue.

Installation

npm install @standardagents/client
# or
pnpm add @standardagents/client
# or
yarn add @standardagents/client

Note: Most users should use @standardagents/react or @standardagents/vue instead. This package is for advanced use cases or building custom framework integrations.

Quick Start

import { AgentBuilderClient, ThreadConnectionManager } from '@standardagents/client'

// Create a client
const client = new AgentBuilderClient('https://api.example.com')

// Fetch messages from a thread
const messages = await client.getMessages('thread-123')

// Send a message
await client.sendMessage('thread-123', {
  role: 'user',
  content: 'Hello!',
})

// Connect to live updates with automatic reconnection
const connection = new ThreadConnectionManager(client, 'thread-123', {
  onStatusChange: (status) => console.log('Status:', status),
  onMessage: (event) => console.log('New message:', event.data),
  onChunk: (event) => console.log('Streaming chunk:', event.chunk),
  onEvent: (event) => console.log('Custom event:', event.eventType, event.data),
})

connection.connect()

Authentication

The client reads the authentication token from localStorage using the key agentbuilder_auth_token:

// Set the token before making requests
localStorage.setItem('agentbuilder_auth_token', 'your-token-here')

All API requests and WebSocket connections will automatically include this token.

API Reference

AgentBuilderClient

HTTP client for the Standard Agents API.

Constructor

const client = new AgentBuilderClient(endpoint: string)

Methods

getEndpoint(): string

Returns the configured endpoint URL.

createThread(payload): Promise<Thread>

Create a new thread.

const thread = await client.createThread({
  agent_id: 'my-agent',
  user_id: 'user-123', // optional
})

getThread(threadId): Promise<Thread>

Get thread metadata.

const thread = await client.getThread('thread-123')

getMessages(threadId, options?): Promise<Message[]>

Fetch messages from a thread.

const messages = await client.getMessages('thread-123', {
  limit: 50,
  offset: 0,
  depth: 0,
  includeSilent: false,
})

Use getMessagesPage() when you need pagination metadata, or pass ids to hydrate specific messages. includeWorkblocks expands requested tool-call messages to the complete workblock they belong to.

sendMessage(threadId, payload): Promise<Message>

Send a message to a thread.

const message = await client.sendMessage('thread-123', {
  role: 'user',
  content: 'Hello!',
  silent: false, // optional
})

stopExecution(threadId): Promise<void>

Cancel an in-flight execution.

await client.stopExecution('thread-123')

connectMessageWebSocket(threadId, callbacks?, options?): WebSocket

Create a WebSocket connection for streaming messages.

const ws = client.connectMessageWebSocket('thread-123', {
  onOpen: () => console.log('Connected'),
  onMessage: (event) => console.log('Message:', event),
  onChunk: (event) => console.log('Chunk:', event),
  onError: (event) => console.error('Error:', event),
  onClose: (event) => console.log('Closed:', event),
}, {
  includeSilent: false,
  depth: 0,
})

connectLogWebSocket(threadId, callbacks?): WebSocket

Create a WebSocket connection for log events and custom events.

const ws = client.connectLogWebSocket('thread-123', {
  onOpen: () => console.log('Connected'),
  onLog: (event) => console.log('Log:', event),
  onCustom: (event) => console.log('Custom:', event),
  onStopped: (event) => console.log('Stopped:', event),
  onClose: (event) => console.log('Closed:', event),
})

ThreadConnectionManager

Manages WebSocket connections with automatic reconnection and heartbeat.

Constructor

const manager = new ThreadConnectionManager(
  client: AgentBuilderClient,
  threadId: string,
  callbacks?: ThreadConnectionCallbacks,
  options?: ThreadConnectionOptions
)

Callbacks:

• onStatusChange?: (status: ConnectionStatus) => void - Called when connection status changes
• onMessage?: (event: MessageDataEvent) => void - Called when a complete message is received
• onChunk?: (event: MessageChunkEvent) => void - Called when a streaming chunk is received
• onEvent?: (event: ThreadEvent) => void - Called when a custom event is received
• onError?: (error: Error | Event) => void - Called on connection errors

Options:

• depth?: number - Message depth level (default: 0)
• includeSilent?: boolean - Include silent messages (default: false)
• maxReconnectDelay?: number - Max reconnection delay in ms (default: 30000)
• heartbeatInterval?: number - Heartbeat interval in ms (default: 30000)

Methods

connect(): void

Establish the WebSocket connection.

disconnect(): void

Close the connection and stop reconnection attempts.

getStatus(): ConnectionStatus

Returns the current connection status: 'connecting' | 'connected' | 'reconnecting' | 'disconnected'

getThreadId(): string

Returns the thread ID.

updateCallbacks(callbacks): void

Update callbacks after construction.

updateOptions(options): void

Update options after construction.

Reconnection Behavior

The connection manager automatically reconnects on unexpected disconnections using exponential backoff:

• Initial delay: 1 second
• Doubles each attempt: 1s, 2s, 4s, 8s, 16s
• Maximum delay: 30 seconds (configurable)
• Resets to 1s after successful connection

transformToWorkblocks(messages): ThreadMessage[]

Groups tool calls with their results into workblock structures for easier UI rendering.

import { transformToWorkblocks } from '@standardagents/client'

const messages = await client.getMessages('thread-123')
const workblocks = transformToWorkblocks(messages)

// Each workblock contains:
// - type: 'workblock'
// - workItems: array of tool calls and results
// - log_ids: log IDs for LLM requests represented by the block
// - status: 'pending' | 'completed'

Types

import type {
  Message,
  WorkMessage,
  WorkItem,
  ThreadMessage,
  Thread,
  SendMessagePayload,
  GetMessagesOptions,
  CreateThreadPayload,
  ConnectionStatus,
  ThreadConnectionCallbacks,
  ThreadConnectionOptions,
} from '@standardagents/client'

Message Types

interface Message {
  id: string
  role: 'user' | 'assistant' | 'system' | 'tool'
  content: string | null
  created_at: number // microseconds
  reasoning_content?: string | null
  silent?: boolean
  depth?: number
  tool_calls?: string // JSON string
  tool_call_id?: string
}

interface WorkMessage {
  type: 'workblock'
  id: string
  content: string | null
  reasoning_content?: string | null
  status: 'pending' | 'completed'
  workItems: WorkItem[]
  log_ids?: string[]
  created_at: number
  depth?: number
}

interface WorkItem {
  id: string
  type: 'tool_call' | 'tool_result'
  name: string
  input?: string
  content?: string
  status: 'success' | 'error' | null
  tool_call_id?: string
  log_id?: string | null
}

type ThreadMessage = Message | WorkMessage

Local Development

# Install dependencies
pnpm install

# Build package
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm typecheck

# Run tests
pnpm test