UXDL Docs
AI

AI Overview

The two integration patterns, when to use each, and the documentation flow.

UXDL AI features use one of two integration patterns: hosted LangGraph graphs (deployed on LangGraph Platform) or in-process LangGraph.js agents (graphs colocated with the API). Product backends do not call LLM providers from route handlers. They go through services, persist durable state in the database, and emit traces and logs through the shared observability stack.

Two patterns in the UXDL stack

PatternWhere logic livesHow the API invokes itBest for
Hosted LangGraphLangGraph Platform deployment (Python or TS graph repo)@langchain/langgraph-sdk: threads.create, runs.create, webhooksMulti-route agents, long runs, RAG, tool orchestration, shared across products
In-process LangGraph.jssrc/agents/<name>/ inside the API repograph.invoke() or agent.stream() in a serviceFocused pipelines, fast iteration, no separate deploy

Both patterns share the same product API contract: thin controllers, fat services, durable persistence (typically MongoDB), structured logging plus OpenTelemetry spans, and Bruno tests for HTTP surfaces.

How the hosted pattern works

  1. The client calls the product API (e.g. POST to start a chat or async job).
  2. The API creates a LangGraph thread and run via the SDK, saves a processing row in the database, and returns (or the client polls).
  3. LangGraph Platform runs the deployed graph. When the run finishes, it POSTs to your webhook.
  4. The webhook handler parses the result, writes output to the database, updates status, and may emit a socket event or record usage.
  5. The client gets the result via poll, socket, or a later GET. SSE can stream in-process agents; hosted jobs usually complete via webhook + poll/socket.

Details: Integration flow and Webhooks & reconciliation.

When to use which

Use hosted LangGraph when…Use in-process LangGraph.js when…
The agent has multiple routes or toolsThe graph is small and owned by one service
Runs are long (generation, research, batch)You need sub-second invoke with no webhook
Multiple products share one agent deploymentYou are prototyping or the graph rarely changes
You want LangSmith tracing on the graph hostThe team does not want a separate graph deploy

Documentation flow

Path 1 — New async feature (hosted graph)

  1. AI Overview (this page).
  2. Integration flow.
  3. Webhooks & reconciliation.
  4. Environment variables.
  5. Delivery standards.
  6. Local development.

Path 2 — Small in-repo agent (Node)

  1. AI Overview (this page).
  2. Folder layout & setup.
  3. Agents & pipelines.
  4. Streaming & realtime if user-facing chat.
  5. Delivery standards.

Path 3 — Search / recommendations (embeddings only)

  1. AI Overview (this page).
  2. Embedding models.
  3. Vector search.
  4. Persist vectors in Backend → MongoDB.

See also

Official documentation