Skip to content

Backend Factories

Backend factories create the backend objects that UI components and hooks use to communicate with your server. This abstraction decouples UI components from specific HTTP endpoints, making them reusable across different server configurations.

Available Factories

Factory Returns Description
createHttpAgentBackend AgentBackend HTTP request/response agent backend (no streaming)
createSseAgentBackend AgentBackend SSE streaming agent backend
createHttpTraceBackend TraceBackend HTTP backend for trace list and detail operations
createHttpConversationBackend ConversationBackend HTTP backend for conversation CRUD and messaging

Pattern

All factories follow the same pattern:

  1. Call the factory with an options object containing baseUrl, getHeaders, and optional path configuration.
  2. Receive a backend object that implements the required interface.
  3. Pass the backend to a component or hook via the backend prop.
import {
  createSseAgentBackend,
  AgentChat,
} from "@modernpath/agent-ui-react";

// 1. Create the backend
const backend = createSseAgentBackend({
  baseUrl: "https://api.example.com",
  getHeaders: () => ({
    Authorization: `Bearer ${getToken()}`,
  }),
});

// 2. Pass to component
<AgentChat backend={backend} auditingId={1} agentType="qa-chat" stream />

Authentication

All factories accept a getHeaders function that returns a headers object. This function is called on every request, allowing you to include fresh authentication tokens:

const backend = createHttpAgentBackend({
  baseUrl: "/api",
  getHeaders: () => ({
    Authorization: `Bearer ${localStorage.getItem("token")}`,
    "X-Tenant-Id": "tenant-123",
  }),
});

Token Refresh

Since getHeaders is called on every request, you can implement token refresh logic outside the backend and the latest token will always be used.

Custom Paths

Agent backends support custom path builders for cases where your server uses non-default URL patterns:

POST /api/agents/:auditingId/execute          (HTTP)
POST /api/agents/:auditingId/execute/stream    (SSE)

const backend = createSseAgentBackend({
  baseUrl: "https://api.example.com",
  buildPath: (auditingId) => `/v2/run/${auditingId}/stream`,
});

Backend Interfaces

Each backend factory returns an object conforming to a specific interface. See the TypeScript Types page for the complete interface definitions:

  • AgentBackend -- execute() and optionally executeStream()
  • TraceBackend -- listTraces(), getTrace(), and related methods
  • ConversationBackend -- listConversations(), createConversation(), sendMessage(), etc.