工具调用

通过丰富、类型安全的 UI 卡片展示智能体工具调用

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

工具调用的工作原理

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

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

智能体运行时执行该工具，结果以 ToolMessage 形式返回。useStream 钩子将所有内容统一到一个 toolCalls 数组中，您可以直接渲染。

设置 useStream

第一步是将 useStream 连接到您的智能体后端。该钩子返回响应式状态，包括一个 toolCalls 数组，该数组会在智能体流式传输时实时更新。

定义一个与智能体状态模式匹配的 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>
  );
}

类型安全的工具参数

如果您的工具是使用结构化模式定义的，您可以使用 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 可以提供编译时安全性。如果工具模式发生变化，您的 UI 组件会立即标记类型错误。

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

工具调用通常与流式文本交错到达。useStream 钩子保持 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 视图。
• 在加载期间显示工具名称和参数。用户希望知道智能体正在做什么，即使在结果到达之前。
• 保持卡片紧凑。工具卡片内嵌在聊天消息中。避免使用过大的小组件淹没对话。

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.