Workflow React Hooks

@llamaindex/ui

Our React library, @llamaindex/ui, is the recommended way to easily integrate your UI with a LlamaDeploy workflow server and LlamaCloud. The library comes pre-installed in any of our templates containing a ui. The library provides both react hooks for custom integrations, as well as standard components.

Workflows Hooks

Our React hooks provide an idiomatic way to observe and interact remotely with your from your LlamaDeploy workflows from a frontend client.

There are 3 hooks you can use:

1. useWorkflowCreate: May be called to start a workflow run, and observe its status.
2. useWorkflowHandler: Observes and interact with a single run, streaming and send events.
3. useWorkflowHandlerList: Monitors and updates with the list of recent or in progress runs.

Client setup

The hooks need to be configured with a workflow client. Make sure to wrap your app with an ApiProvider to point to your deployment:

import {
  ApiProvider,
  type ApiClients,
  createWorkflowClient,
  createWorkflowConfig,
} from "@llamaindex/ui";

const deploymentName =
  (import.meta as any).env?.VITE_LLAMA_DEPLOY_DEPLOYMENT_NAME || "default";

const clients: ApiClients = {
  workflowsClient: createWorkflowClient(
    baseUrl: `/deployments/${deploymentName}`
  ),
};

export function Providers({ children }: { children: React.ReactNode }) {
  return <ApiProvider clients={clients}>{children}</ApiProvider>;
}

Start a run

Fire a workflow by name with useWorkflowCreate. Just provide a JSON input payload. You get a handler_id back immediately; the run streams events until it finishes.

import { useWorkflowCreate } from "@llamaindex/ui";

export function RunButton() {
  const { runWorkflow, isCreating, error } = useWorkflowCreate();

  async function handleClick() {
    const handler = await runWorkflow("my_workflow", { user_id: "123" });
    // e.g., navigate to a details page using handler.handler_id
    console.log("Started:", handler.handler_id);
  }

  return (
    <button disabled={isCreating} onClick={handleClick}>
      {isCreating ? "Starting…" : "Run Workflow"}
    </button>
  );
}

Watch a run and stream events

Subscribe to a single handler’s live event stream and show status with useWorkflowHandler

import { useWorkflowHandler } from "@llamaindex/ui";

export function HandlerDetails({ id }: { id: string }) {
  const { handler, events, sendEvent } =
    useWorkflowHandler(id, true);

  // Find the final StopEvent to extract the workflow result (if provided)
  const stop = events.find(
    (e) => e.type.endsWith(".StopEvent") // event type contain the event's full python module path, e.g. workflows.events.StopEvent
  );

  return (
    <div>
      <div>
        <strong>{handler.handler_id}</strong> — {handler.status}
      </div>
      {stop ? (
        <pre>{JSON.stringify(stop.data, null, 2)}</pre>
      ) : (
        <pre style={{ maxHeight: 240, overflow: "auto" }}>
          {JSON.stringify(events, null, 2)}
        </pre>
      )}
    </div>
  );
}

Monitor sets of workflows

Subscribe all running workflows with useWorkflowHandlerList. Great for a lightweight “recent runs” view.

import { useWorkflowHandlerList } from "@llamaindex/ui";

export function RecentRuns() {
  const { handlers, loading, error } = useWorkflowHandlerList();
  if (loading) return <div>Loading…</div>;
  if (error) return <div>Error: {error}</div>;
  return (
    <ul>
      {handlers.map((h) => (
        <li key={h.handler_id}>{h.handler_id} — {h.status}</li>
      ))}
    </ul>
  );
}