工具调用

代理可以调用外部工具，如天气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";

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>
  );
}

<script setup lang="ts">
import { useStream } from "@langchain/vue";

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

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

<template>
  <div>
    <Message
      v-for="msg in stream.messages.value"
      :key="msg.id"
      :message="msg"
      :tool-calls="stream.toolCalls.value"
    />
  </div>
</template>

<script lang="ts">
  import { useStream } from "@langchain/svelte";

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

  const { messages, toolCalls, submit } = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "tool_calling",
  });
</script>

<div>
  {#each $messages as msg (msg.id)}
    <Message message={msg} toolCalls={$toolCalls} />
  {/each}
</div>

import { Component } from "@angular/core";
import { useStream } from "@langchain/angular";

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

@Component({
  selector: "app-chat",
  template: `
    @for (msg of stream.messages(); track msg.id) {
      <app-message [message]="msg" [toolCalls]="stream.toolCalls()" />
    }
  `,
})
export class ChatComponent {
  stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "tool_calling",
  });
}

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 与流保持同步，因此待处理卡片会在代理发出调用后立即出现，即使工具尚未完成执行。这意味着用户会看到：

AI的文本流式传输进来
工具调用发出时立即显示加载卡片
工具完成后卡片更新以显示结果

工具调用会就地更新。相同的 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上编辑此页面或提交问题。

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Deploy with LangSmith

工具调用的工作原理

设置 useStream

ToolCallWithResult 类型

按消息过滤工具调用

构建专用工具卡片

天气卡片示例

加载和错误状态

类型安全的工具参数

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

处理多个并发工具调用

最佳实践

​工具调用的工作原理

​设置 useStream

​ToolCallWithResult 类型

​按消息过滤工具调用

​构建专用工具卡片

​天气卡片示例

​加载和错误状态

​类型安全的工具参数

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

​处理多个并发工具调用

​最佳实践

工具调用的工作原理

设置 useStream

ToolCallWithResult 类型

按消息过滤工具调用

构建专用工具卡片

天气卡片示例

加载和错误状态

类型安全的工具参数

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

处理多个并发工具调用

最佳实践