工具调用

将智能体工具调用显示为丰富的、类型安全的 UI 卡片

智能体可以调用外部工具，如天气 API、计算器、网络搜索、数据库查询等。结果是原始 JSON。本模式展示了如何为智能体的每个工具调用渲染结构化的、类型安全的 UI 卡片，包含加载状态和错误处理。

工具调用的工作原理

当 LangGraph 智能体决定需要外部数据时，它会在 AI 消息中发出一个或多个工具调用。每个工具调用包含：

• name：被调用的工具（如 "get_weather"、"calculator"）
• args：传递给工具的结构化参数
• id：将调用与其结果关联的唯一标识符

智能体运行时执行工具，结果以 ToolMessage 形式返回。useStream hook 将所有这些统一为一个可以直接渲染的 toolCalls 数组。

设置 useStream

第一步是将 useStream 连接到你的智能体后端。hook 返回响应式状态，包括一个随智能体流式输出实时更新的 toolCalls 数组。

定义一个与你的智能体状态 schema 匹配的 TypeScript 接口，并将其作为类型参数传递给 useStream，以获得类型安全的状态值访问。在以下示例中，将 typeof myAgent 替换为你的接口名称：

import type { BaseMessage } from "@langchain/core/messages";

interface AgentState {
  messages: BaseMessage[];
}

React

import { useStream } from "@langchain/react";

const AGENT_URL = "http://localhost:2024";

export function Chat() {
  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "tool_calling",
  });

  return (
    <div>
      {stream.messages.map((msg) => (
        <Message key={msg.id} message={msg} toolCalls={stream.toolCalls} />
      ))}
    </div>
  );
}

ToolCallWithResult 类型

toolCalls 数组中的每个条目都是一个 ToolCallWithResult 对象：

interface ToolCallWithResult {
  call: {
    id: string;
    name: string;
    args: Record<string, unknown>;
  };
  result: ToolMessage | undefined;
  state: "pending" | "completed" | "error";
}

属性	描述
call.id	与 AI 消息的 tool_calls 条目匹配的唯一 ID
call.name	工具名称（如 "get_weather"）
call.args	智能体传递给工具的结构化参数
result	ToolMessage 响应，工具完成后可用
state	生命周期状态：运行中为 "pending"，成功为 "completed"，失败为 "error"

按消息过滤工具调用

一条 AI 消息可能触发多个工具调用，你的聊天中可能包含多条 AI 消息。要在每条消息下渲染正确的工具卡片，通过将 call.id 与消息的 tool_calls 数组匹配来过滤：

function Message({
  message,
  toolCalls,
}: {
  message: AIMessage;
  toolCalls: ToolCallWithResult[];
}) {
  const messageToolCalls = toolCalls.filter((tc) =>
    message.tool_calls?.find((t) => t.id === tc.call.id)
  );

  return (
    <div>
      <p>{message.content}</p>
      {messageToolCalls.map((tc) => (
        <ToolCard key={tc.call.id} toolCall={tc} />
      ))}
    </div>
  );
}

构建专用工具卡片

不要直接展示原始 JSON，而是为每个工具构建专门的 UI 组件。使用 call.name 选择正确的卡片：

function ToolCard({ toolCall }: { toolCall: ToolCallWithResult }) {
  if (toolCall.state === "pending") {
    return <LoadingCard name={toolCall.call.name} />;
  }

  if (toolCall.state === "error") {
    return <ErrorCard name={toolCall.call.name} error={toolCall.result} />;
  }

  switch (toolCall.call.name) {
    case "get_weather":
      return <WeatherCard args={toolCall.call.args} result={toolCall.result} />;
    case "calculator":
      return (
        <CalculatorCard args={toolCall.call.args} result={toolCall.result} />
      );
    case "web_search":
      return <SearchCard args={toolCall.call.args} result={toolCall.result} />;
    default:
      return <GenericToolCard toolCall={toolCall} />;
  }
}

天气卡片示例

function WeatherCard({
  args,
  result,
}: {
  args: { location: string };
  result: ToolMessage;
}) {
  const data = JSON.parse(result.content as string);

  return (
    <div className="rounded-lg border p-4">
      <div className="flex items-center gap-2">
        <CloudIcon />
        <h3 className="font-semibold">{args.location}</h3>
      </div>
      <div className="mt-2 text-3xl font-bold">{data.temperature}°F</div>
      <p className="text-muted-foreground">{data.condition}</p>
    </div>
  );
}

加载和错误状态

始终处理待处理和错误状态，为用户提供清晰的反馈：

function LoadingCard({ name }: { name: string }) {
  return (
    <div className="flex items-center gap-2 rounded-lg border p-4 animate-pulse">
      <Spinner />
      <span>正在运行 {name}...</span>
    </div>
  );
}

function ErrorCard({ name, error }: { name: string; error?: ToolMessage }) {
  return (
    <div className="rounded-lg border border-red-300 bg-red-50 p-4">
      <h3 className="font-semibold text-red-700">{name} 出错</h3>
      <p className="text-sm text-red-600">
        {error?.content ?? "工具执行失败"}
      </p>
    </div>
  );
}

类型安全的工具参数

如果你的工具使用结构化 schema 定义，可以使用 ToolCallFromTool 工具类型获取完全类型化的 args：

import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(async ({ location }) => { /* ... */ }, {
  name: "get_weather",
  description: "获取某个位置的当前天气",
  schema: z.object({
    location: z.string().describe("城市名称"),
  }),
});

type WeatherToolCall = ToolCallFromTool<typeof getWeather>;
// WeatherToolCall.call.args 现在是 { location: string }

使用 ToolCallFromTool 提供编译时安全性。如果工具 schema 变更，你的 UI 组件会立即标记类型错误。

在流式文本中内联渲染工具调用

工具调用经常与流式文本交织出现。useStream hook 保持 toolCalls 与流同步，因此待处理卡片在智能体发出调用时立即出现，甚至在工具完成执行之前。

这意味着用户看到：

1. AI 的文本随流式输出出现
2. 工具调用发出时立即出现加载卡片
3. 工具完成后卡片更新显示结果

工具调用原地更新。同一个 call.id 从 "pending" 过渡到 "completed"（或 "error"），因此你的 UI 使用新状态重新渲染同一个组件。

处理多个并发工具调用

智能体可以并行调用多个工具。toolCalls 数组将同时包含多个 state: "pending" 的条目。每个独立解析，因此你的 UI 应优雅地处理部分完成：

function ToolCallList({ toolCalls }: { toolCalls: ToolCallWithResult[] }) {
  const pending = toolCalls.filter((tc) => tc.state === "pending");
  const completed = toolCalls.filter((tc) => tc.state === "completed");

  return (
    <div className="space-y-2">
      {completed.map((tc) => (
        <ToolCard key={tc.call.id} toolCall={tc} />
      ))}
      {pending.map((tc) => (
        <LoadingCard key={tc.call.id} name={tc.call.name} />
      ))}
    </div>
  );
}

最佳实践

构建工具调用 UI 时请遵循以下准则：

• 始终处理所有三种状态：pending、completed 和 error。用户不应看到空白卡片。
• 安全地解析结果。工具结果以字符串形式到达。将 JSON.parse() 包裹在 try/catch 中，解析失败时显示回退内容。
• 提供通用回退。不是每个工具都需要定制卡片。为未知工具名称渲染可折叠的 JSON 视图。
• 加载时显示工具名称和参数。用户想知道智能体正在做什么，即使结果尚未到达。
• 保持卡片紧凑。工具卡片与聊天消息内联显示。避免用过大的控件淹没对话。

---

将这些文档连接到 Claude、VSCode 等工具，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交 issue。