08 · 统一工具配置

把工具系统从"能调用"推进到"能统一注册、前端可选、后端动态绑定"。

课时资源

查看本课源码

一、学习目标

本课所在阶段：第三阶段 · Agent 核心能力。

学完这一课后，你应该能够：

理解为什么工具一旦变多，就不能继续把定义和执行逻辑散落在 chatbot.ts 里
看懂 unified-tools.config.ts 如何成为工具系统的统一入口
明白前端工具面板怎样把 toolIds 传给后端，并影响这一轮真正绑定到模型的工具
知道"真实工具调用"和"工具系统工程化"之间的区别

二、问题背景

第七课已经解决了一个重要问题：Agent 能真实调用工具了。

但只要你继续往前走，很快就会遇到新的工程问题：

工具一多，定义到底放哪里
前端怎样表达"这一轮启用了哪些工具"
后端怎样只绑定本轮需要的工具，而不是每次都把全部工具塞给模型

如果这些边界不提前收束，后面一旦继续加天气、搜索、文件系统、Canvas 等能力，chatbot.ts 会越来越重，前端也没法表达工具选择。

这一课真正要解决的是：把工具从"已经能调用"推进到"能管理、能选择、能扩展"。

三、核心概念

这一课最重要的概念有三个：

统一注册所有工具先进入 toolDefinitions
前端选择页面通过工具面板决定这一轮到底启用哪些工具
动态绑定后端按本轮 toolIds 构造 LangChain tools，而不是永远绑定全部工具

这一课相对第 07 课的核心增量

维度	第 07 课	第 08 课
工具定义位置	直接散落在 Agent 内	收束到 `unified-tools.config.ts`
前端选择工具	不支持	支持工具面板和勾选状态
后端绑定工具	固定工具数组	按 `toolIds` 动态创建
工作流复用	单一工具组合	按工具组合缓存 app
页面状态	只关心消息和会话	新增 `availableTools`、`selectedToolIds`

本课建立的核心边界

工具执行定义：服务端内部持有
工具展示元数据：通过 API 给前端
当前启用哪些工具：由页面状态决定
本轮模型能用哪些工具：由后端动态绑定决定

这几个边界分开后，工具系统才算真正开始工程化。

四、整体流程

页面初始化与工具面板

按本轮选择动态绑定工具

五、运行过程

1. 页面首次加载时拿到可用工具列表

page.tsx 在 useEffect 里请求 GET /api/chat。这次 GET 不只返回 sessions，还会额外返回：

tools: getAvailableToolOptions()

前端拿到后，一方面保存到 availableTools，另一方面用 getDefaultSelectedToolIds(tools) 默认全选。

2. 工具面板集成在输入框内

ToolPanel.tsx 被集成到 ChatInput.tsx 的工具栏左侧，形成一个紧凑的工具选择入口：

tools 由页面传入
selectedToolIds 由页面传入
onToggle / onSelectAll / onClearAll 也都由页面传入

这意味着"当前这一轮到底启用了哪些工具"仍然是页面级状态，工具面板本身是一个受控组件。

3. 发送消息时把 `toolIds` 一起带给后端

这一课的请求体已经从：

{ "message": "...", "threadId": "..." }

升级为：

{ "message": "...", "threadId": "...", "toolIds": ["current_time", "calculator"] }

也就是说，工具选择不再只是页面展示，而是真正进入了后端调用链路。

4. 后端根据本轮选择动态创建工具

parseChatRequest 解析出 toolIds 后，streamChat(userMessage, threadId, toolIds) 会把它传到 Agent 层。

接着 app/agent/chatbot.ts 里会执行：

const tools = createLangChainTools(toolIds);

这一步决定了：模型本轮真正能看到哪些工具。

5. 相同工具组合会复用已有工作流

这一课没有每次请求都重新建一套 LangGraph app，而是按工具组合做缓存：

const appCache = new Map<string, ReturnType<typeof buildChatApp>>();

这样同一组工具不会反复重建工作流，结构上也更接近可扩展系统。

6. 无工具时的工作流

当前端把所有工具都关闭时，buildChatApp 会检测到 tools.length === 0，然后只调用 model.invoke(modelMessages) 而不绑定任何工具。这说明系统已经支持"纯聊天模式"和"工具增强模式"之间的平滑切换。

六、关键代码解析

app/agent/config/unified-tools.config.ts - 统一工具注册表

这是本课最重要的文件。它统一定义工具元数据、参数 schema、执行 handler，并提供前端可消费的工具选项。

关键代码：

export const toolDefinitions: ToolDefinition[] = [
  {
    id: 'current_time',
    name: 'current_time',
    description: '获取当前上海时区时间',
    icon: '🕒',
    enabled: true,
    schema: z.object({
      request: z.string().describe('用户关于时间的提问，例如 现在几点了'),
    }),
    handler: async () => `当前时间: ${getCurrentTime()}`,
  },
];

代码解析：

每个工具的定义包含了模型需要的全部信息：name、description、schema
handler 是真正执行时调用的函数，与定义分开
enabled 字段让系统能快速启用或禁用某个工具，而不需要删除代码
icon 用于前端展示，让工具面板更友好

app/agent/config/unified-tools.config.ts - 前端可消费的工具选项

关键代码：

export function getAvailableToolOptions(): ToolOption[] {
  return toolDefinitions
    .filter((tool) => tool.enabled)
    .map(({ id, name, description, icon }) => ({ id, name, description, icon }));
}

代码解析：前端只需要知道"展示什么"，不应该知道 schema 和 handler 这些服务端执行细节。所以这一层把"可展示元数据"和"可执行定义"明确拆开了。

只返回前端需要的字段：id、name、description、icon
自动过滤掉 enabled: false 的工具
后续如果需要权限控制，可以在这里添加用户级别的过滤逻辑

app/agent/chatbot.ts - 按工具组合缓存 app

根据 toolIds 动态构建工作流，并缓存不同工具组合对应的 app。

关键代码：

function getToolKey(toolIds?: string[]) {
  if (!toolIds || toolIds.length === 0) return '__no_tools__';
  return [...new Set(toolIds)].sort().join(',');  // 去重并排序，保证组合唯一性
}

const appCache = new Map<string, ReturnType<typeof buildChatApp>>();

function getChatApp(toolIds?: string[]) {
  const key = getToolKey(toolIds);
  const cachedApp = appCache.get(key);
  if (cachedApp) return cachedApp;

  const nextApp = buildChatApp(toolIds);
  appCache.set(key, nextApp);
  return nextApp;
}

代码解析：这里的关键不是字符串拼接本身，而是：工作流实例现在已经和"启用哪些工具"绑定在一起了。不同工具组合对应不同工作流实例，缓存之后才能避免重复构建。

getToolKey 对工具 ID 进行去重和排序，确保 ['a', 'b'] 和 ['b', 'a'] 生成相同的 key
__no_tools__ 作为空工具列表的特殊 key，对应纯聊天模式
缓存避免了每次请求都重新创建 StateGraph 和 compile，提升性能

app/agent/chatbot.ts - 动态工作流构建

关键代码：

function buildChatApp(toolIds?: string[]) {
  const tools = createLangChainTools(toolIds);

  const workflow = new StateGraph(MessagesAnnotation)
    .addNode('chatbot', async (state) => {
      const model = createModel();
      const modelMessages = toModelMessages(state.messages);
      const response = tools.length > 0
        ? await model.bindTools(tools).invoke(modelMessages)
        : await model.invoke(modelMessages);
      return { messages: [response] };
    })
    .addNode('tools', new ToolNode(tools))
    .addEdge(START, 'chatbot')
    .addConditionalEdges('chatbot', shouldContinue, {
      tools: 'tools',
      [END]: END,
    })
    .addEdge('tools', 'chatbot');

  return workflow.compile({ checkpointer });
}

代码解析：

工作流不再是全局单例，而是根据 toolIds 动态创建
toModelMessages 是本课新增：它负责把从 checkpointer 恢复的消息（可能是 StoredMessage 格式）统一转换成 BaseMessage[]，确保模型能正确处理历史消息
tools.length > 0 的判断决定是否绑定工具
即使没有工具，ToolNode 也会被加入工作流（只是工具列表为空），保持工作流结构统一
这为后续新增工具提供了稳定的扩展点

app/services/chat.service.ts - 解析前端传来的 toolIds

负责解析前端传来的 toolIds，再把它们继续传进 Agent。

关键代码：

// page.tsx 发送消息
body: JSON.stringify({ message: content, threadId, toolIds: selectedToolIds })

// chat.service.ts 解析请求
const toolIds = Array.isArray(body.toolIds)
  ? body.toolIds.filter((id): id is string => typeof id === 'string')
  : undefined;

// chatbot.ts 使用工具 IDs
const tools = createLangChainTools(toolIds);