Skip to content

HTTP Backend

createHttpAgentBackend creates an AgentBackend that communicates with the agent server via standard HTTP POST requests. The backend sends the execute request and waits for the complete response. It does not support streaming.

Import

import { createHttpAgentBackend } from "@modernpath/agent-ui-react";

Options

interface CreateHttpAgentBackendOptions {
  /**
   * Base URL for the agent API.
   * @default ""
   */
  baseUrl?: string;

  /**
   * Custom path builder. Receives the auditing ID and returns the
   * request path (appended to baseUrl).
   * @default (auditingId) => `/api/agents/${auditingId}/execute`
   */
  buildPath?: (auditingId: number) => string;

  /**
   * Function that returns headers to include in every request.
   * Called on each request to support token refresh.
   */
  getHeaders?: () => Record<string, string>;
}

Return Value

Returns an AgentBackend object with an execute method:

interface AgentBackend {
  /**
   * Send an execute request and return the complete response.
   */
  execute: (
    request: AgentExecuteRequest,
    signal?: AbortSignal
  ) => Promise<AgentExecuteResponse<any>>;

  /**
   * Optional streaming method. Not provided by the HTTP backend.
   */
  executeStream?: (
    request: AgentExecuteRequest,
    onEvent: (event: AgentStreamEvent) => void,
    signal?: AbortSignal
  ) => Promise<void>;
}

No streaming support

The HTTP backend does not implement executeStream. If you need streaming, use createSseAgentBackend instead.

Default Path

POST {baseUrl}/api/agents/{auditingId}/execute

The request body is JSON conforming to AgentExecuteRequest:

interface AgentExecuteRequest {
  agentType: string;
  prompt: string;
  history?: ChatHistoryMessage[];
  parameters?: Record<string, unknown>;
}

Usage

Basic HTTP Backend

import {
  createHttpAgentBackend,
  AgentChat,
} from "@modernpath/agent-ui-react";

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

function App() {
  return (
    <AgentChat
      backend={backend}
      auditingId={1}
      agentType="qa-chat"
      title="Support Chat"
    />
  );
}

Custom Path

const backend = createHttpAgentBackend({
  baseUrl: "https://api.example.com",
  buildPath: (auditingId) => `/v2/agents/${auditingId}/run`,
  getHeaders: () => ({
    Authorization: `Bearer ${getToken()}`,
  }),
});

With useAgentChat Hook

import {
  createHttpAgentBackend,
  useAgentChat,
} from "@modernpath/agent-ui-react";

const backend = createHttpAgentBackend({ baseUrl: "/api" });

function CustomChat() {
  const { messages, input, setInput, send, isLoading } = useAgentChat({
    backend,
    auditingId: 1,
    agentType: "qa-chat",
    // stream: false is the default -- works with HTTP backend
  });

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i}>{msg.content}</div>
      ))}
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyDown={(e) => e.key === "Enter" && send()}
      />
    </div>
  );
}

Relative URLs (Same Origin)

// When UI and API are served from the same origin
const backend = createHttpAgentBackend({
  // baseUrl defaults to "" (same origin)
  getHeaders: () => ({
    Authorization: `Bearer ${getToken()}`,
  }),
});