SAALT Bridge

The Bridge package is the thin client SAALT Apps use to talk to the host SAALT instance. It wraps the admin API with a tiny fetch helper so custom App views can read and write configuration, call the platform LLM endpoints, and manage App-owned data without rebuilding clients by hand.

Installation

Code
 
npm install @open-agent-kit/bridge
# or
yarn add @open-agent-kit/bridge

Quick start

Code
 
import { createBridge } from "@open-agent-kit/bridge";

// In an App view route/handler SAALT forwards the auth token and server URL.
const token = request.headers.get("saalt_session_token")!;
const serverUrl =
  request.headers.get("saalt_server_url") ?? "https://oak.localhost";

// Standalone (agent-less) bridge — scope is per-plugin:
const bridge = createBridge({ token, serverUrl });

// …or an agent-scoped bridge — pass the agentId once at construction:
const agentBridge = createBridge({ token, serverUrl, agentId });

// Example: load persisted UI state
const { config } = await bridge.data.config.get();

Scope is bound once when you call createBridge and is fixed for the bridge's lifetime — provide agentId for an agent-scoped bridge, omit it for a standalone one.

The bridge builds a pre-authorized fetch client with the provided token and serverUrl and then exposes namespaced helpers:

• data.config – store small JSON configuration blobs per agentId (get/set).
• data.pluginData – CRUD helpers for App data records (find, create, update, delete, count). (SDK name retained for backwards compatibility.)
• llm – call the platform’s text, object, image, or conversation-generation endpoints.
• files – read/write files in SAALT storage and parse uploaded content.
• knowledge – list knowledge documents for an agent and enqueue syncs.
• conversation – read conversation records: a single one with its messages (findFirst) or a filtered, paginated list (findMany).
• user – retrieve information about the current user.
• agent – read Agent metadata (id, name, configured LLM model).
• decodeToken – inspect the forwarded session token when you need user metadata.

Use these helpers directly inside your custom React routes, API handlers, or background jobs that need to coordinate with the SAALT backend.

Bridge SDK reference

The bridge is a TypeScript SDK — every helper below wraps an admin REST endpoint (see the API category) so App code can call it with normal types instead of hand-constructing HTTP requests. The signatures here are pulled directly from the published @open-agent-kit/bridge package; refer to this page rather than the REST spec when writing App code.

Exported types

Code
 
import type {
  OAKBridge,            // ReturnType<typeof createBridge>
  BridgeScope,          // { type: "agent"; agentId: string } | { type: "standalone" }
  Tool,                 // Tool<TParams extends ZodType>
  ToolExecuteParams,    // params passed to your tool's execute()
  PluginMeta,           // shape used by host to describe an App (legacy type name)
  FilePart,             // re-exported from @ai-sdk/provider-utils
  ImagePart,
  TextPart,
} from "@open-agent-kit/bridge";

Tools (class) is the only value export from the package — see the tools section below. z is not re-exported; import it from zod directly (import { z } from "zod";).

createBridge

Code
 
createBridge({ token, serverUrl, agentId }: { token: string; serverUrl: string; agentId?: string }): OAKBridge;

Provide agentId for agent-scoped apps; omit it for a standalone bridge. Scope is bound once at construction and cannot change afterwards.

Agent-scoped vs standalone bridges

Passing agentId to createBridge yields an agent-scoped bridge; omitting it yields a standalone bridge. The chosen scope is fixed for the bridge's lifetime.

• config, pluginData, and files work on both kinds of bridge. On a standalone bridge they are scoped per-plugin instead of per-agent.
• The agent-only namespaces — knowledge.*, conversation.findFirst / conversation.findMany, agent.getAgent, and llm.getAvailableModels — require an agent-scoped bridge. Calling any of them on a standalone bridge throws a client-side error:

Scope is bound once at construction (rather than passed per call) since @open-agent-kit/[email protected].

bridge.data.config

Stores small JSON configuration blobs. Wraps PUT /data/config and GET /data/config; the scope is sent as an ?agentId query param (omitted for a standalone bridge, where config is scoped per-plugin).

Code
 
bridge.data.config.set(config: JsonValue): Promise<unknown>;               // PUT /data/config?agentId=…
bridge.data.config.get(): Promise<{ status: string; config: JsonValue }>;  // GET /data/config?agentId=…

bridge.data.pluginData

CRUD helpers for App-owned records. Records are keyed by the bridge's scope (agent or plugin) + identifier. (The namespace name pluginData is preserved from the original SDK API.)

Code
 
bridge.data.pluginData.findUnique(identifier: string)
  : Promise<{ status: string; data: JsonValue }>;

bridge.data.pluginData.findMany(filter?: PluginDataFilter)
  : Promise<{ status: string; data: JsonValue[] }>;

bridge.data.pluginData.create(data: JsonValue, identifier: string)
  : Promise<{ status: string; data: JsonValue }>;

bridge.data.pluginData.update(identifier: string, data: JsonValue)
  : Promise<{ status: string; data: JsonValue }>;

bridge.data.pluginData.deleteOne(identifier: string)
  : Promise<{ status: string }>;

bridge.data.pluginData.deleteMany(filter?: PluginDataDeleteFilter)
  : Promise<{ status: string; data: { count: number } }>;

bridge.data.pluginData.count(filter?: PluginDataFilter)
  : Promise<{ status: string; count: number }>;

PluginDataFilter accepts where, select, orderBy, skip, take, cursor. PluginDataDeleteFilter accepts where only.

bridge.llm

Code
 
bridge.llm.generateText(params: GenerateTextParams)
  : Promise<{ text: string }>;

bridge.llm.generateObject<T>(params: GenerateObjectParams)
  : Promise<T>;                                         // unwrapped; the SDK returns res.object

bridge.llm.generateImage(params: GenerateImageParams)
  : Promise<{ base64: string }>;

bridge.llm.getAvailableModels()
  : Promise<{ defaultModel: string; availableModels: string[]; models: ModelInfo[] }>;

bridge.llm.generateSpeech(params: GenerateSpeechParams)
  : Promise<{ base64: string; mimeType: string }>;

bridge.llm.generateConversationResponse(params: GenerateConversationResponseInputParams)
  : Promise<{ text: string }>;

bridge.llm.transcribe(params: TranscribeParams)
  : Promise<{ text: string }>;

transcribe runs speech-to-text over an audio or video clip via Gemini (available since @open-agent-kit/[email protected]). It works on both standalone and agent-scoped bridges:

Code
 
type TranscribeParams = {
  model: string;                        // Gemini model id, e.g. "gemini-2.5-flash"
  audioBase64: string;                  // base64 audio/video bytes (data-URL prefix optional)
  mimeType: string;                     // e.g. "audio/mpeg", "video/mp4"
  prompt?: string;                      // optional extra instruction for the transcription
};

generateSpeech synthesizes audio from text via Gemini TTS (available since @open-agent-kit/[email protected]):

Code
 
type GenerateSpeechParams = {
  agentId: string;
  model: string;                        // Gemini TTS model id, e.g. "gemini-2.5-flash-preview-tts"
  text: string;                         // the final script to speak
  voiceName?: string;                   // single prebuilt voice, e.g. "Kore"
  speakers?: { speaker: string; voiceName: string }[]; // multi-speaker (max 2); takes precedence over voiceName
};

GenerateImageParams accepts an optional imageConfig and inpainting mask (available since @open-agent-kit/[email protected]):

Code
 
type GenerateImageParams = {
  prompt: string;
  agentId: string;
  provider: "openai" | "gemini";
  model?: string;
  templateImages?: string[];           // base64 reference images
  imageConfig?: {
    aspectRatio?: "1:1" | "4:3" | "3:4" | "16:9" | "9:16";
    resolution?: "1K" | "2K" | "4K";
  };
  mask?: string;                        // inpainting mask as a data URL
};

getAvailableModels reports the Agent's default model plus the full set of models it is allowed to use, so a plugin can present only valid choices. availableModels is the list of model keys; models carries the full ModelInfo for each (added in @open-agent-kit/[email protected]) — key, modelId, displayName, provider, region, tags, description, pricing, and similar metadata — so a picker can show names and badges rather than raw keys. It requires an agent-scoped bridge and throws on a standalone one. Available since @open-agent-kit/[email protected].

bridge.files

Code
 
bridge.files.getFile(path: string)
  : Promise<{ status: string; base64: string }>;

bridge.files.putFile(data: string, path: string, generatePublicUrl?: boolean)
  : Promise<{ status: string; path: string; publicUrl: string }>;
  // generatePublicUrl defaults to false

bridge.files.parseFile(base64: string, path: string, config: ParseFileConfig)
  : Promise<{ status: string; parsedFile: { content: string; format: string } }>;

data and base64 are base64-encoded file contents — the SDK does not handle raw binary. Files work on both standalone and agent-scoped bridges; on an agent-scoped bridge they are additionally namespaced per agent.

bridge.knowledge

All knowledge.* helpers require an agent-scoped bridge and throw on a standalone one.

Code
 
// Documents
bridge.knowledge.enqueueSync()
  : Promise<{ status: string }>;

bridge.knowledge.listDocuments(filter?: KnowledgeDocumentFilter)
  : Promise<{ status: string; data: KnowledgeDocument[] }>;

// Tags
bridge.knowledge.createTag(tag: KnowledgeTagInput)
  : Promise<{ status: string; data: { id: string; name: string; color: string } }>;

bridge.knowledge.listTags()
  : Promise<{ status: string; data: { tags: KnowledgeTag[] } }>;

bridge.knowledge.updateTag(tagId: string, updates: KnowledgeTagUpdate)
  : Promise<{ status: string; data: { tag: { id: string; name: string; color: string; updatedAt: string } } }>;

bridge.knowledge.deleteTag(tagId: string)
  : Promise<{ status: string }>;

// Tag ↔ Document
bridge.knowledge.attachTagToDocument(documentId: string, tagId: string)
  : Promise<{ status: string }>;

bridge.knowledge.removeTagFromDocument(documentId: string, tagId: string)
  : Promise<{ status: string }>;

KnowledgeDocument.status is one of "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED".

bridge.conversation

Code
 
bridge.conversation.findFirst(where: Record<string, unknown>)
  : Promise<ConversationResponse>;      // one conversation, incl. its messages

bridge.conversation.findMany(filter?: ConversationFilter)
  : Promise<ConversationListResponse>;  // filtered list, without message bodies

Both require an agent-scoped bridge; they throw on a standalone one.

• findFirst returns a single conversation matching where, including its messages (each reduced to { id, content }) — use it to load one conversation's transcript.
• findMany returns a list of the agent's conversations for a Prisma-style filter, as a bare Conversation[] under data. It does not include message bodies (fetch those per conversation with findFirst — they can be large). incognito and private conversations (the latter captured while conversation tracking was off) are never returned, and archived ones are excluded by default (pass where: { archived: true } to opt in). The scope is fixed to the bridge's agent, so an agentId in your where is ignored.

ConversationFilter mirrors PluginDataFilter / KnowledgeDocumentFilter — it accepts where, select, orderBy, skip, take, cursor. A Conversation row (dates are ISO strings) is:

Code
 
type Conversation = {
  id: string;
  agentId: string;
  userId: string | null;
  tagline: string | null;
  customIdentifier: string | null;
  summary: string | null;
  archived: boolean;
  private: boolean;
  incognito: boolean;
  createdAt: string;
  updatedAt: string;
};

type ConversationListResponse = {
  status: "success" | "error";
  data?: Conversation[];
  error?: string;
};

bridge.user

Code
 
bridge.user.me()
  : Promise<{ email: string; name: string; createdAt: string; updatedAt: string }>;

bridge.agent

Code
 
bridge.agent.getAgent()
  : Promise<{ id: string; name: string; model: string }>;

Returns the Agent record so a plugin can surface the configured LLM model or the Agent's display name (useful for "powered by …" UI chips). The model field is the model ID stored on the Agent (e.g. gpt-4o, claude-3-5-sonnet); it may be an empty string when the Agent inherits the platform default.

The agent is fixed at construction, so getAgent requires an agent-scoped bridge and throws client-side on a standalone one.

Available since @open-agent-kit/[email protected].

decodeToken

Code
 
decodeToken(token: string): unknown;

Decodes the JWT payload via atob and returns the parsed object. Return shape isn't typed — treat it as the host's session claims.

Using tools inside Apps

The bridge exports a small Tools helper that lets you register executable tools with zod-validated params. Read more about tools in the tools section.

Code
 
import { Tools } from "@open-agent-kit/bridge";
import { z } from "zod";

const tools = new Tools();

await tools.registerTool({
  identifier: "publish-note",
  name: "Publish note",
  description:
    "Save a note to App storage and attach it to the conversation",
  params: z.object({ content: z.string().min(1) }),
  async execute({ input, bridge, agentId, conversationId }) {
    const note = await bridge.data.pluginData.create(input, "note");
    return { result: { note, conversationId } };
  },
});

The class exposes three methods:

Code
 
class Tools {
  registerTool<TParams extends ZodType>(tool: Tool<TParams>)
    : Promise<Map<string, Tool<ZodType>>>;

  getTools()
    : Promise<Array<{
        identifier: string;
        name: string;
        description: string;
        federatedToolComponentName?: string;
        params: JsonSchema;          // zod schema converted via z.toJSONSchema
      }>>;

  handleToolExecution(
    params: {
      toolIdentifier: string;
      agentId: string;
      input: unknown;
      messages: UIMessage[];
      conversationId?: string;
      meta?: object;
    },
    headers: Record<string, string>, // forwarded saalt_session_token + saalt_server_url
  ): Promise<{ result: unknown; error?: string }>;
}

• registerTool adds a tool definition with a zod schema for input validation. Throws if identifier is already registered.
• getTools returns the tool list in JSON Schema form — used by the host for federated tool discovery.
• handleToolExecution is invoked by the host: it validates input against the tool's params, builds a bridge from the forwarded headers, and runs your execute implementation. Apps normally don't call this themselves. It builds the bridge with the tool call's agentId, so pluginData, config, and knowledge calls inside a tool are automatically agent-scoped.

Use this when your App exposes server-side tools that the agent can call while a custom view provides the front-end experience.

Tips for custom views

• Keep the saalt_session_token secret; the bridge already sets the Authorization header.
• Prefer pluginData for user-generated or view-specific state and config for lightweight settings.
• Decode the token with decodeToken if you need to inspect the current user inside your view logic.
• Default serverUrl is https://oak.localhost; override it when the host provides a different origin.