Client Libraries

The platform ships TypeScript packages that handle the repetitive parts of integration — types, API calls, stream parsing, and pre-built UI. Use as much or as little as your project needs.

Available packages

Package	Purpose	Use when…
`@rfsmart/ai-agent-types`	TypeScript types and utilities	You're writing any TypeScript against the API
`@rfsmart/ai-chat-client`	API service class with streaming and tools	You want a ready-made client instead of raw fetch
`@rfsmart/conversation-stream`	Stream parsing for Bedrock responses	You need typed stream event handling
`@rfsmart/ai-chat-components`	React UI components for chat	You're building a React chat interface

Installation

All packages are hosted on GitHub Packages. You need a GitHub personal access token with read:packages scope.

1. Configure your registry

Create or update .npmrc in your project root:

@rfsmart:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

2. Set your token

export GITHUB_TOKEN=ghp_your_token_here

Tip

Add GITHUB_TOKEN to your shell profile or CI secrets. The .npmrc references it as an env var so you never commit it.

3. Install

npm install @rfsmart/ai-agent-types
# or install multiple
npm install @rfsmart/ai-agent-types @rfsmart/ai-chat-client @rfsmart/conversation-stream

@rfsmart/ai-agent-types

Types and utilities for the platform's data model. Install this if you're writing any TypeScript against the API — it covers messages, sessions, tools, and streaming events.

Key exports

import type {
  AgentChatMessage,
  AgentChatSession,
  ExtendedContentBlock,
  ToolRequestPayload,
} from "@rfsmart/ai-agent-types";
 
import {
  ToolClassification,
  ToolCallProcessingState,
  ToolResponseState,
  getToolClassification,
  hasToolUse,
  hasTextContent,
} from "@rfsmart/ai-agent-types";

Tool classification

The getToolClassification utility categorizes tool names by their prefix:

Classification	Tool prefix	Meaning
`STANDARD`	(none)	Normal tool — client handles execution
`SERVER_SIDE`	`_`	Internal tool — server handles automatically
`MCP`	`mcp_`	MCP provider tool — server routes to gateway
`PRIVATE_MCP`	`priv_`	Private MCP tool — requires TOTP auth

Use this to decide which tool calls your client needs to handle vs. which the server manages:

import { getToolClassification, ToolClassification } from "@rfsmart/ai-agent-types";
 
const classification = getToolClassification(toolName);
if (classification === ToolClassification.STANDARD) {
  // Your client executes this tool
} else {
  // Server handles it — skip
}

Peer dependency

This package has a peer dependency on @aws-sdk/client-bedrock-runtime for Bedrock streaming event types. Install it alongside:

npm install @aws-sdk/client-bedrock-runtime

@rfsmart/ai-chat-client

A full API service class that handles sessions, messages, streaming, and tool lifecycle. Extend it to add your own tool execution logic.

Basic usage

import { ApiService } from "@rfsmart/ai-chat-client";
 
const api = new ApiService(configService);
 
// Sessions
const sessionId = await api.createSession({ product: "my-app" });
const sessions = await api.getSessions();
 
// Messages (non-streaming)
const messages = await api.getMessages(sessionId);
 
// Streaming
const stream = api.streamMessage(sessionId, "Hello!");
for await (const event of stream) {
  // Typed Bedrock events
}
 
// Tools
await api.sendHeartbeat(sessionId, requestId);
await api.sendToolResponse(sessionId, requestId, result);

Extending for custom tools

Override executeToolCall to wire in your own tool backend:

import { ApiService } from "@rfsmart/ai-chat-client";
 
class MyApiService extends ApiService {
  override async executeToolCall(functionName: string, input: unknown) {
    // Route to your backend
    return await myBackend.execute(functionName, input);
  }
}

@rfsmart/conversation-stream

Wraps @streamparser/json with typed event handling for Bedrock conversation streams. Use this if you want structured callbacks instead of manual JSON parsing.

import { ConversationStream } from "@rfsmart/conversation-stream";
 
const stream = new ConversationStream(response.body);
 
stream.on("text", (chunk) => {
  // Append to UI
});
 
stream.on("toolUse", (toolCall) => {
  // Handle tool request
});
 
stream.on("done", (messages) => {
  // Stream complete
});

@rfsmart/ai-chat-components

Pre-built React components for chat interfaces. Includes message lists, input fields, tool call displays, and streaming indicators. Built with Radix UI primitives and Tailwind CSS.

Note

This package is designed for React 19+. It's most useful when you want a polished chat UI quickly and are comfortable with Tailwind for styling overrides.

Choosing what to use

Building a custom client from scratch? → Install @rfsmart/ai-agent-types for types, write your own fetch calls following the API reference.

Want streaming handled for you? → Add @rfsmart/conversation-stream or @rfsmart/ai-chat-client.

Building a React chat UI? → Use @rfsmart/ai-chat-components + @rfsmart/ai-chat-client for the fastest path. See the warehouse agent client for a production example.

Just exploring the API? → The demo app uses only @rfsmart/ai-agent-types with raw fetch — no framework, no abstractions. Good for learning the protocol.

Edit this page on GitHub