注意

LlamaAgents 的云端部署目前处于 beta 预览阶段，已广泛开放以供反馈。你可以在本地试用，或部署到 LlamaCloud 并通过应用内的反馈按钮把意见发给我们。

我们的 React 库 @llamaindex/ui 是把界面与 LlamaAgents 工作流服务端及 LlamaCloud 集成的推荐方式。任何带 UI 的模板都已预装它。该库既提供用于自定义集成的 React hooks，也提供标准组件。

工作流 Hooks

我们的 React hooks 提供了一套符合习惯的写法，让前端客户端可以从远处观察并与你的 LlamaAgents 工作流交互。

一共有 4 个 hooks 可用：

1. useWorkflow：拿到某个特定工作流的操作（创建 handler、运行到完成）。
2. useHandler：拿到单个 handler 的状态与操作（流式事件、发送事件）。
3. useHandlers：列出并监视 handler，可选过滤。
4. useWorkflows：列出所有可用的工作流。

客户端准备

用一个工作流客户端来配置这些 hooks。用指向你部署的 ApiProvider 包裹你的应用：

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

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

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

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

列出可用工作流

用 useWorkflows 列出该部署中所有可用的工作流：

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

export function WorkflowList() {
  const { state, sync } = useWorkflows();

  if (state.loading) return <div>Loading…</div>;

  return (
    <div>
      <button onClick={() => sync()}>Refresh</button>
      <ul>
        {Object.values(state.workflows).map((w) => (
          <li key={w.name}>{w.name}</li>
        ))}
      </ul>
    </div>
  );
}

发起一次运行

用 useWorkflow 按名字启动工作流。带上 JSON 输入载荷调用 createHandler，就能立刻拿到 handler 状态。

import { useState } from "react";
import { useWorkflow } from "@llamaindex/ui";

export function CreateHandler() {
  const workflow = useWorkflow("stream");
  const [handlerId, setHandlerId] = useState<string | null>(null);

  async function handleClick() {
    const handlerState = await workflow.createHandler({});
    setHandlerId(handlerState.handler_id);
  }

  return (
    <div>
      <button onClick={handleClick}>Create Handler</button>
      {handlerId && <div>Created: {handlerId}</div>}
    </div>
  );
}

观察一次运行并流式接收事件

用 subscribeToEvents 订阅某个 handler 的实时事件流：

import { useEffect, useState } from "react";
import { useWorkflow, useHandler, WorkflowEvent, isStopEvent } from "@llamaindex/ui";

export function StreamEvents() {
  const workflow = useWorkflow("stream");
  const [handlerId, setHandlerId] = useState<string | null>(null);
  const handler = useHandler(handlerId);
  const [events, setEvents] = useState<WorkflowEvent[]>([]);

  async function start() {
    setEvents([]);
    const h = await workflow.createHandler({});
    setHandlerId(h.handler_id);
  }

  useEffect(() => {
    if (!handlerId) return;
    const sub = handler.subscribeToEvents({
      onData: (event) => setEvents((prev) => [...prev, event]),
    });
    return () => sub.unsubscribe();
  }, [handlerId]);

  const stop = events.find(isStopEvent);

  return (
    <div>
      <button onClick={start}>Start & Stream</button>
      {handlerId && <div>Status: {handler.state.status}</div>}
      {stop && <pre>{JSON.stringify(stop.data, null, 2)}</pre>}
      {!stop && events.length > 0 && <div>{events.length} events received</div>}
    </div>
  );
}

监视多次工作流运行

用 useHandlers 查询并监视一个经过过滤的 handler 列表。做进度指示器或「最近运行」视图时很有用。

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

export function RecentRuns() {
  const { state, sync } = useHandlers({
    query: { status: ["running", "completed"] },
  });

  if (state.loading) return <div>Loading…</div>;

  const handlers = Object.values(state.handlers);

  return (
    <div>
      <button onClick={() => sync()}>Refresh</button>
      <ul>
        {handlers.map((h) => (
          <li key={h.handler_id}>
            {h.handler_id.slice(0, 8)}… — {h.status}
          </li>
        ))}
      </ul>
    </div>
  );
}

sync 选项控制是否在挂载时拉取 handler 列表。任何时候都可以手动调用 sync() 从服务端刷新列表。

Hook 参考

Hook	用途	关键方法/属性
useWorkflow(name)	操作某个特定工作流	createHandler(input)、runToCompletion(input)、state.graph
useHandler(handlerId)	操作某个特定 handler	sendEvent(event)、subscribeToEvents(callbacks)、sync()、state.status、state.result
useHandlers({ query, sync })	列出/过滤 handler	sync()、setHandler(h)、actions(id)、state.handlers
useWorkflows({ sync })	列出全部工作流	sync()、state.workflows