UXDL Docs
AI

Integration Flow

Threads, runs, SDK orchestration, and persistence conventions.

Standard pattern for production agents at UXDL. The graph runs on LangGraph Platform. The product API orchestrates runs via the JS/TS SDK and owns persistence, auth, and webhooks.

Core concepts

ConceptRole
GraphDeployed agent logic (nodes, tools, routing). Lives in a separate repo or LangGraph project.
Assistant / graph IDName passed to runs.create(threadId, assistantId, …).
ThreadConversation or job scope. Created with client.threads.create().
RunSingle execution of the graph on a thread. Returns run_id.
ConfigurablePer-run metadata (user_id, thread_id, route flags) via config.configurable.
WebhookHTTPS callback when a run finishes. Product API persists output here.

Standard integration flow

Every hosted integration should follow this sequence:

  1. Create thread with client.threads.create() (or ensure an existing thread ID if resuming).
  2. Create run with client.runs.create(threadId, assistantId, { input, config, webhook }).
  3. Persist request row in the product DB with thread_id, run_id, and status: processing.
  4. Wait for completion via webhook, client poll, or reconciliation on read.
  5. Persist output by mapping graph values to product collections and setting status: completed.

Generic SDK example:

ts
const client = new Client({
  apiUrl: process.env.LANG_GRAPH_URL,
  apiKey: process.env.LANG_GRAPH_API_KEY,
  defaultHeaders: {
    Authorization: `Bearer ${process.env.LANG_GRAPH_BACKEND_TOKEN}`,
  },
});
 
const thread = await client.threads.create();
const threadId = thread.thread_id;
 
const run = await client.runs.create(threadId, "my_assistant", {
  input: { user_query: "..." },
  config: {
    configurable: {
      user_id: userId,
      thread_id: threadId,
    },
  },
  streamMode: ["updates"],
  webhook: `${process.env.WEBHOOK_PUBLIC_BASE_URL}/webhooks/agent`,
});

Multi-route graphs

A single deployed graph can serve multiple product flows by branching on input shape or config.configurable (e.g. route_type: "chat" | "batch_job" | "classifier"). The product API passes the right input and reads the matching output field from values on completion.

Pattern:

  • One graph deployment, many product endpoints.
  • Each route documents its input schema and which values key holds the result.
  • Validate structured output with Zod (or equivalent) before persisting.

Persistence conventions

Store agent state in the product database, not only in LangGraph thread memory.

StoreTypical fields
Job / request rowthread_id, run_id, status, input snapshot, user_id, timestamps
Output rowStructured graph output, linked by job ID
Chat messagesthread_id, run_id, type (user/ai), content, status
EmbeddingsVector field on the request or document for search

Use a dedicated DB or collection namespace when agent data volume or access patterns differ from core app data.

Optional vectors on request rows: Vector search.

See also

Official documentation