工具调用

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

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

工具调用的工作原理

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

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

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

设置 useStream

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

导入你的智能体并将 typeof myAgent 作为类型参数传递给 useStream，以获得对状态值的类型安全访问：

import type { myAgent } from "./agent";

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: "Get the current weather for a location",
  schema: z.object({
    location: z.string().describe("City name"),
  }),
});

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

使用 ToolCallFromTool 给你编译时安全性。如果工具 schema 更改，你的 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 视图。
• 加载时显示工具名称和参数。用户想知道智能体正在做什么，即使在结果到达之前。
• 保持卡片紧凑。工具卡片与聊天消息内联。避免用过大的小部件压倒对话。

---

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

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