UXDL Docs
AI

Local Development

Run agents locally, tunnel webhooks, and debug stuck jobs.

Run and debug AI features on your machine, including webhook delivery and stuck async jobs.

Setup steps

  1. Copy env from .env.example; set LANG_GRAPH_URL to the Alpha deployment.
  2. Start the API (bun run dev or project equivalent).
  3. Expose webhooks: ngrok http <port> and set WEBHOOK_PUBLIC_BASE_URL to the tunnel URL.
  4. Trigger a run; confirm webhook logs and DB rows update.
  5. If the UI stays on processing: hit the read endpoint to trigger reconciliation, or inspect thread state via the LangGraph SDK.

Environment variables: Environment variables.

Common local pitfalls

SymptomLikely causeFix
Job forever processingWebhook URL not reachableUse ngrok; set WEBHOOK_PUBLIC_BASE_URL
Empty assistant text after runvalues shape changedUpdate webhook parser; log valueKeys
LANG_GRAPH_URL is not setMissing env in load pathCheck .env and env.ts
Thread 404 on reuseThread from a different deploymentRecreate thread or use ensureSpecificThread

Stale-run reconciliation

If a webhook never arrives, the read path should recover:

ts
const run = await client.runs.get(threadId, runId);
if (runIsTerminal(run.status)) {
  const state = await client.threads.getState(threadId);
  const output = state.values?.expected_output_key;
  // persist output and update status
}

Full pattern: Webhooks & reconciliation.

Debugging checklist

  • WEBHOOK_PUBLIC_BASE_URL matches the ngrok or staging URL LangGraph can POST to
  • Webhook route is mounted at the path passed to runs.create
  • thread_id and run_id in logs match MongoDB rows
  • LangGraph run status in Platform UI or via client.runs.get
  • Trace visible in LangSmith when LANGSMITH_PROJECT is set

See also

Official documentation