Axiom Lattice Client SDK

A TypeScript client for the Axiom Lattice Agent Service API.

Overview

The Client SDK provides a simple interface for interacting with the Axiom Lattice Agent Service API. It handles authentication, request/response formatting, and error handling.

Runtime and scope

This package is runtime-neutral: it targets browser, Node 18+, Deno, Bun and similar modern JS runtimes. It contains HTTP/SSE client and protocol types only; React hooks, UI components and server-side business logic live in other packages.

Public APIs use cross-runtime Web standard types. File/archive inputs use Blob (browser File is a Blob subclass); the SDK does not require DOM-only File or Node-only node:* types. Node types in the build are for tests/tooling, not the public contract. See docs/architecture/decisions/ADR-260-client-sdk-runtime-neutral.md.

Features

• Create and manage threads
• Send messages and receive responses
• Stream responses with event-based callbacks
• Register client-side tools
• Handle tool calls and responses
• Process streaming message chunks with ChunkMessageMerger
• Standardized HTTP client using axios for all API calls
• Authenticated Agent Web App publication management through client.webApps

Agent Web App Management

client.webApps is the authenticated Console management API, not the anonymous external runtime client. It provides list, get, create, update, enable, disable, and delete.

import { Client, type CreateAgentWebAppInput } from "@axiom-lattice/client-sdk";

const client = new Client({
  baseURL: "http://localhost:4001",
  apiKey: "console-session-token",
  assistantId: "support-agent",
  transport: "sse",
});

const input: CreateAgentWebAppInput = {
  assistantId: "support-agent",
  name: "Support",
  integration: { type: "react_sdk" },
  scope: { defaultProjectId: "support", allowedProjectIds: ["support"] },
  features: {
    projectSelector: false,
    modelSelector: false,
    threadManagement: true,
    attachments: false,
    hitl: false,
    genUI: false,
  },
  appearance: { title: "Support assistant" },
};

const publication = await client.webApps.create(input);
await client.webApps.enable(publication.id);

Use @axiom-lattice/react-sdk/web-app in the external React application. The default/local SQLite setup currently uses an in-memory Web App store, so publication definitions do not survive gateway restart; configure the PostgreSQL store for persistence. See the management guide.

Installation

npm install @axiom-lattice/client-sdk

Usage

import { Client, createSimpleMessageMerger } from "@axiom-lattice/client-sdk";

// Create a client
const client = new Client({
  baseURL: "https://api.example.com",
  apiKey: "your-api-key",
  assistantId: "your-assistant-id",
  transport: "sse",
  environment: "web", // Optional: "web" (default) or "wechat-miniprogram"
});

// Create a thread
const threadId = await client.createThread({
  metadata: { user: "user123" },
});

// Send a message
const response = await client.chat.send({
  threadId,
  messages: [
    {
      role: "user",
      content: "Hello, how can you help me?",
      id: "msg-1",
    },
  ],
});

// Stream a message
const stopStreaming = client.chat.stream(
  {
    threadId,
    messages: [
      {
        role: "user",
        content: "Tell me a story",
        id: "msg-2",
      },
    ],
  },
  (event) => {
    console.log("Event:", event);
  },
  () => {
    console.log("Stream completed");
  },
  (error) => {
    console.error("Stream error:", error);
  }
);

// Stop streaming if needed
// stopStreaming();

// Use ChunkMessageMerger to process streaming chunks
const merger = createSimpleMessageMerger();

// Process user message
merger.push({
  type: "human",
  data: {
    id: "user-1",
    content: "Hello",
  },
});

// Process AI message with tool calls
merger.push({
  type: "ai",
  data: {
    id: "ai-1",
    content: "I need to search for that.",
    tool_calls: [
      {
        name: "search",
        args: { query: "typescript" },
        id: "search-1",
      },
    ],
  },
});

// Process tool response
merger.push({
  type: "tool",
  data: {
    id: "tool-1",
    content: "Search results: ...",
    tool_call_id: "search-1",
  },
});

// Get merged messages
const messages = merger.getMessages();

Migration Notes

Runtime Environment Support

As of version 1.0.13, the client SDK now supports different runtime environments through the environment configuration option. Currently supported environments are:

• "web" (default): Uses axios for all HTTP requests, including streaming responses
• "wechat-miniprogram": Uses a custom WeChat Mini Program HTTP client implementation for compatibility with WeChat Mini Programs

To specify the environment:

const client = new Client({
  // ... other options
  environment: "wechat-miniprogram", // For WeChat Mini Program environments
});

The WeChat Mini Program environment uses a different approach for streaming responses since true streaming is not supported in that environment. It uses a polling mechanism instead.

HTTP Client Standardization

As of version 1.0.12, the client SDK now uses axios exclusively for all HTTP requests, including streaming responses. Previously, the SDK used a combination of axios for regular requests and the native fetch API for streaming. This change standardizes the HTTP client implementation across the SDK.

Benefits:

• Consistent error handling
• Unified request/response interceptors
• Simplified maintenance and debugging
• Better compatibility with different JavaScript environments

ChunkMessageMerger

The ChunkMessageMerger module has been moved from the web project to the client-sdk package. It provides functionality for processing streaming message chunks and merging them into complete messages.

To use it:

import { createSimpleMessageMerger } from "@axiom-lattice/client-sdk";

const merger = createSimpleMessageMerger();
// Use merger methods: push, getMessages, reset, etc.

Future Migration Plans

The current web project uses its own implementation of useChat that is tightly integrated with the web app's API and message format. In the future, we plan to migrate the web project to use the react-sdk's useChat hook, which provides a more standardized interface for chat interactions.

Steps for future migration:

1. Update the web project's message types to align with the react-sdk's message format
2. Replace direct API calls with client-sdk methods
3. Integrate the react-sdk's useChat hook
4. Update UI components to work with the new message format

API Reference

Client

The main client class for interacting with the Axiom Lattice Agent Service API.

WeChatClient

A specialized client implementation for WeChat Mini Programs that uses the native wx API for network requests.

import { WeChatClient } from "@axiom-lattice/client-sdk";

// Create a WeChat client
const client = new WeChatClient({
  baseURL: "https://api.example.com",
  apiKey: "your-api-key",
  assistantId: "your-assistant-id",
  transport: "sse",
});

// Use the same API methods as the standard Client
const threadId = await client.createThread({
  metadata: { user: "user123" },
});

// Send a message
const response = await client.chat.send({
  threadId,
  messages: [
    {
      role: "user",
      content: "Hello, how can you help me?",
      id: "msg-1",
    },
  ],
});

ChunkMessageMerger

A utility for processing streaming message chunks and merging them into complete messages.

• createSimpleMessageMerger(): Creates a new message merger instance
  • push(chunk): Processes a message chunk
  • getMessages(): Gets all messages with tool calls merged
  • getMessagesWithoutToolCalls(): Gets messages without tool calls
  • initialMessages(msgs): Initializes with existing messages
  • reset(): Resets the merger state