@hugex/ai

HugeX Agent runtime — a React client hook (useAgent) plus optional server handlers for hosting the agent backend on Cloudflare Workers.

Flows are designed in the HugeX platform (Agent Design) and saved to HX Core. Most integrations only need the client half: install @hugex/ai, point useAgent at an already-deployed WebSocket endpoint, and render chat UI from the agent store.

Two parts

| Part | Import | Runs in | When you need it | |---|---|---|---| | Client | @hugex/ai/client | Your React app (browser) | Always — connect UI to an agent session | | Server | @hugex/ai | Cloudflare Worker | Only if you host the agent runtime (tenant Worker deployment) | | Shared types | @hugex/ai/common | Either | Wire-protocol and flow types |

You do not run useAgent on Cloudflare Workers. The hook is frontend-only. It opens a WebSocket to a session endpoint; that endpoint is usually served by a HugeX tenant Worker you or HugeX already deployed. Your SPA can run anywhere — same origin, a separate frontend host, or a local dev server — as long as it can reach the WebSocket URL.

Install

pnpm add @hugex/ai

Peer dependencies are declared in the package — align versions with your app.

Integration paths

Frontend only (most common)

Use @hugex/ai/client in your React app. You need:

1. flowId — the agent graph id from Agent Design
2. sessionId — a stable id for this chat session (UUID recommended)
3. WebSocket endpoint — URL of a deployed agent server (see WebSocket paths)

No Worker code, wrangler config, or server imports required in your frontend repo.

| Scenario | host | Notes | |---|---|---| | App and agent server share a domain | omit | basePath is relative to the page origin | | App on a different host (SPA, mobile web, local dev) | set to agent server host | e.g. tenant.data.ora.socketServer | | Multiple agents on one screen | + storeKey | Isolates chat state per agent |

Self-hosted runtime (tenant Worker)

Only needed when your Cloudflare Worker must serve agent WebSocket routes (/api/agent/flow/..., /api/ora/connect/...) and run AgentDO sessions. See Cloudflare Workers (optional).

HugeX-managed tenant deployments already include this — frontend teams typically skip this section.

Flow IDs and agent configuration

A flow is the graph you edit in Agent Design (/ai/agents/:id). The URL param id is the flowId (e.g. 1rShqGMrANRGmXTN1mjTJB).

| Concept | Value | Notes | |---|---|---| | flowId | Agent Design :id | Identifies which flow graph to run | | sessionId | UUID (or stable string) | One chat session; server maps this to session state | | Session key | `${flowId}::${sessionId}` | Server-side identifier (used when hosting the runtime) |

Flow metadata (tenant, visibility, status) lives in HX Core. The runtime loads flow state (nodes/edges) from HX Core on WebSocket connect.

Node types (flow graph)

Design-time node data (configured in Agent Design panels):

| Node | Key data | |---|---| | Start | greeting, allow_images, allow_documents, memory_* toggles | | LLM | template, model, tools, varMapping, outVars | | Memo | rag_id, query_key, topk | | Classifier | input_variable, items[] | | API | url, method, headers, body, varMapping | | Answer | Required flow terminus |

Rules: exactly one Start, at least one Answer, all paths connected.

useAgent — client integration

useAgent opens a WebSocket to the agent session, decodes the TYPE::CONTENT wire protocol, and writes conversation state into the agent store. UI components subscribe to the store and call send, clearHistory, etc.

Options

useAgent({
  host?: string;       // WS host; omit when same origin as the page
  basePath?: string;   // path segment under host (see below)
  agent?: string;      // flowId
  name?: string;       // sessionId
  query?: Record<string, string | null> | (() => Promise<Record<string, string | null>>);
  user?: string;       // anonymous session label; sent as UID on connect
  storeKey?: string;   // isolate store when multiple agents on one screen
});

Returns { connection, store, send, clearHistory, sendAuth, setIdentity, approve, reject, ... }.

WebSocket paths

These routes are served by the agent backend (typically a deployed tenant Worker). Your frontend connects to them; it does not implement them.

| Route | Auth | Typical use | |---|---|---| | /api/agent/flow/{flowId}/{sessionId} | JWT / access_token query | Tenant chat UIs, Run panel | | /api/ora/connect/{flowId}/{sessionId} | Agent API key (authorization query/header) | Design assistant, tooling |

Pattern 1 — same-origin chat

Frontend and agent server share a domain. No host needed. Uses the global store (useAgentStore).

import { useAgent, useAgentStore } from '@hugex/ai/client';

function Chat({ flowId, sessionId }: { flowId: string; sessionId: string }) {
  const { messages, typingMessage } = useAgentStore();

  const { send, clearHistory } = useAgent({
    basePath: `api/agent/flow/${flowId}/${sessionId}`,
    agent: flowId,
    name: sessionId,
  });

  // render messages, call send(text) on submit
}

Pattern 2 — cross-origin chat

Frontend runs on a different host (SPA, local dev, separate deployment). Set host to the deployed agent server.

import { useAgent, useAgentStore } from '@hugex/ai/client';

const flowId = '…'; // from your route or config
const sessionId = '…'; // from session store
const socketHost = '…'; // deployed agent server host (no path)

const { send, sendAuth, clearHistory } = useAgent({
  host: socketHost,
  basePath: `api/agent/flow/${flowId}/${sessionId}`,
  agent: flowId,
  name: sessionId,
  query: async () => ({ access_token: await readAccessToken() }),
});

const messages = useAgentStore((s) => s.messages);

Start-node flags (allow_images, allow_documents, memory_enabled) can be read from flow config (flowConfig in the store) or from your design metadata to drive the UI.

Pattern 3 — multiple agents on one screen (storeKey)

When two agents mount together, pass a stable storeKey so their chat state does not collide:

const { send, sendAuth, store } = useAgent({
  host: AGENT_SERVER_HOST,
  basePath: `api/ora/connect/${FLOW_ID}/${sessionId}`,
  agent: FLOW_ID,
  name: sessionId,
  query: { authorization: AGENT_API_KEY },
  user: email ?? undefined,
  storeKey: 'my-panel', // stable for this component's lifetime
});

const messages = store((s) => s.messages);
const status = store((s) => s.status);

Child components that need the same isolated state must use the same storeKey via getAgentStore('my-panel').

Rule: storeKey must be constant for the component lifetime (do not derive from per-render state).

Runtime credentials (sendAuth)

Tools may reference {{ auth.NAME }} placeholders. Push credentials with sendAuth(name, value) — they never appear in chat history.

Important: re-push credentials before every send, not once on connect. Server-side session hibernation can clear in-memory auth mid-connection without disconnecting the WebSocket.

const sendTurn = async (text: string) => {
  const token = await readAccessToken();
  if (token) sendAuth('ACCESS_TOKEN', token);
  send(text);
};

clearHistory() wipes server auth too — re-push after clearing.

Store fields (reactive UI)

Subscribe via useAgentStore (global) or store (isolated):

| Field | Use | |---|---| | messages | Chat history (replayed on connect via HIS::) | | typingMessage | Streaming assistant text (TS / TSC) | | reasoningMessage | Streaming reasoning (RS / RSC) | | status | 'connecting' \| 'connected' \| 'disconnected' — gate input on 'connected' | | flowConfig | Start-node config from server (CFG::: greeting, attachments) | | events | Tool/info events from SE:: stream | | composioAuth | OAuth redirect when a connected tool requires manual authorization | | approvals | Human-in-the-loop tool approvals |

Wire protocol (summary)

Inbound frames use TYPE::CONTENT:

| Code | Meaning | |---|---| | HIS | Full history replay | | SE | Server event (tools, memory, external integrations, …) | | TS / TSC | Assistant text stream / complete | | RS / RSC | Reasoning stream / complete | | CFG | Flow config (attachments, greeting) | | ERR | Error string |

Outbound: M: user message, CH: clear history, AUT: runtime credential, UID: session identity.

Cloudflare Workers (optional — host the runtime)

Use this section only when you deploy the agent backend on Cloudflare Workers (e.g. a tenant Worker). Frontend-only integrations can skip it entirely.

Exports (server)

| Import | Purpose | |---|---| | @hugex/ai | handleAgentsRoutes, handleAuthRoutes, handleCommonRoutes, handleIntancesRoutes, AgentDO |

Worker setup

Chain the route handlers and re-export the Durable Object:

// workers/app.ts
import {
  handleAgentsRoutes,
  handleAuthRoutes,
  handleCommonRoutes,
  handleIntancesRoutes,
} from '@hugex/ai';

export default {
  async fetch(request, env, ctx) {
    const common = await handleCommonRoutes(request, env, ctx);
    if (common instanceof Response) return common;

    const auth = await handleAuthRoutes(request, env, ctx);
    if (auth instanceof Response) return auth;

    const agent = await handleAgentsRoutes(request, env, ctx);
    if (agent instanceof Response) return agent;

    const instances = await handleIntancesRoutes(request, env, ctx);
    if (instances instanceof Response) return instances;

    return yourAppHandler(request, { cloudflare: { env, ctx }, state: { ...auth } });
  },
} satisfies ExportedHandler<Env>;

export { AgentDO } from '@hugex/ai';

wrangler.jsonc must bind the Durable Object:

{
  "durable_objects": {
    "bindings": [{ "class_name": "AgentDO", "name": "AGENT" }]
  },
  "migrations": [{ "tag": "v2", "new_sqlite_classes": ["AgentDO"] }]
}

Required env vars (typical): HX_CORE_URL, HX_ORA_URL, HX_API_KEY, tenant Vectorize binding VDB_<tenant>_1024, AI (Workers AI).

Session memory, secrets ({{ secrets.NAME }}), Vectorize memo, and tool execution run inside AgentDO; shared data is fetched from HX Core / hx-ora APIs.

Bundler

Exclude @hugex/ai from dependency pre-bundling in your dev server:

optimizeDeps: {
  exclude: ['@hugex/ai'],
},

Architecture (high level)

Agent Design  ──save──►  HX Core (flow state + KV metadata)
                              ▲
Agent backend (optional)  ──fetch──┘
  WebSocket routes → session runtime (per flowId::sessionId)
  FlowEngine runs Start → … → Answer

React app (useAgent)  ◄──WebSocket TYPE::CONTENT──►  Agent backend

• Frontend: any React host — imports @hugex/ai/client, connects via WebSocket.
• Backend: Cloudflare Worker with @hugex/ai server exports — only when you host the runtime.

Release (maintainers)

From the ora/ source repo:

task publish:ai              # bump patch, build, publish
task publish:ai -- --dry-run  # build + npm pack only
task build:ai                 # build to ../ai without publish

License

Included with your HugeX deployment — install and use this package as documented in this README. Full terms are in the LICENSE file included in this npm package (also listed under License on this page).