)
1. 項目概述從純文本到可感知交互的范式躍遷如果你最近也在搗鼓AI應用開發(fā)尤其是基于大語言模型LLM的聊天機器人大概率會遇到一個共同的瓶頸交互體驗太“平”了。用戶輸入問題AI吐出一大段文字偶爾夾雜著一些格式混亂的代碼或JSON。當AI需要調用工具比如搜索網絡、查詢數據庫、生成圖片時這個過程對用戶而言是完全“黑盒”的。用戶只能看到一個“思考中”的提示然后等待一個最終結果中間發(fā)生了什么、進行到哪一步了一概不知。這種純文本的交互方式極大地限制了AI應用的表達力和用戶信任感。這正是我最近深度研究一個名為agui的開源項目時感觸最深的地方。agui 不僅僅是一個簡單的前后端聊天模板它更像是一個關于“如何設計下一代AI交互界面”的完整提案。它的核心目標就是實現“可感知的工具調用”。簡單來說就是讓用戶能“看見”AI思考、決策和行動的全過程將一次工具調用從后臺的靜默執(zhí)行轉變?yōu)榍芭_可觀察、可理解、甚至可交互的視覺流。想象一下這個場景你問AI“幫我總結今天關于量子計算的最新論文并找一張相關的示意圖”。在一個傳統的聊天界面里你只會看到AI回復“正在處理...”然后幾分鐘后如果沒超時的話丟給你一段總結和一張圖片鏈接。而在agui構建的界面里你可能會實時看到“步驟1正在調用學術搜索引擎...”伴隨一個旋轉的搜索圖標和進度條→ “已找到10篇相關論文正在提取摘要...”顯示一個動態(tài)增長的列表→ “正在調用文生圖模型生成示意圖...”顯示一個圖片從模糊到清晰的生成過程→ “完成”。整個過程流暢、透明用戶不再是被動等待而是成為了過程的觀察者甚至參與者。這種體驗的升級其意義遠超“好看”的范疇。它直接提升了應用的可用性、可信度和用戶粘性。用戶知道AI沒有“卡死”理解任務的復雜性并對最終結果有合理的預期。對于開發(fā)者而言agui提供了一套從后端流式數據生成到前端流式渲染的完整技術棧參考極具實戰(zhàn)價值。接下來我就結合對agui項目的拆解深入聊聊如何從零構建這樣一個“可感知”的AI交互界面。2. 核心設計理念流式UI與工具調用的深度融合2.1 打破“請求-響應”的原子模型傳統Web交互和許多早期AI應用都基于簡單的“請求-響應”模型。用戶發(fā)送一個消息服務器處理可能調用多次AI和工具最后返回一個完整的響應。這個模型對于AI工具調用極不友好因為一次復雜的任務可能包含多個串行或并行的工具調用每個調用都有其延遲和狀態(tài)。原子模型迫使我們將所有這些中間狀態(tài)壓縮成一個最終態(tài)返回丟失了所有過程信息。agui的設計起點就是徹底摒棄這個模型擁抱“流式會話”的概念。整個會話不再是一個個獨立的“消息-回復”對而是一個持續(xù)的、狀態(tài)可變的流。在這個流中不僅最終的文本內容可以分塊chunk傳輸任何中間狀態(tài)——包括但不限于AI的思考Reasoning、工具調用的決策Function Call、工具執(zhí)行的狀態(tài)Tool Status、工具執(zhí)行的結果Tool Result、乃至基于結果生成的新內容——都可以作為獨立的事件Event在流中實時推送。這種設計帶來了架構上的根本變化。后端不再是“處理完所有事情再返回”而是變成了一個“狀態(tài)機”或“工作流引擎”它負責推進會話狀態(tài)并在狀態(tài)變化的每一個節(jié)點即時地將變化序列化為事件通過SSEServer-Sent Events或WebSocket流式推送給前端。前端則監(jiān)聽這些事件流并依據事件的類型和內容動態(tài)地、增量地更新UI。2.2 定義可流式化的事件協議要實現前后端的高效協作一個清晰、可擴展的事件協議是關鍵。agui在這方面做了很好的示范。它沒有使用過于復雜的標準如OpenAI的流式格式而是定義了一套簡潔明了的自定義事件。核心事件類型通常包括text_delta: 最基礎的文本流攜帶文本塊。這是兼容普通聊天的基礎。function_call: 聲明AI決定調用某個工具。事件體包含工具名稱和調用參數通常是JSON。這是“可感知”的起點前端收到后可以立即渲染一個“準備調用XXX工具”的UI元素。tool_status: 報告工具執(zhí)行狀態(tài)。如running、success、error。攜帶狀態(tài)信息和可能的進度如progress: 50。這允許前端更新對應工具UI的狀態(tài)如進度條、顏色變化。tool_result: 攜帶工具執(zhí)行成功后的結果數據?？赡苁俏谋?、JSON、圖片URL等。前端可以用特定形式如折疊面板、卡片、內聯圖片展示結果。reasoning: 可選流式傳輸AI的“思考鏈”。這能極大增強透明度和趣味性但可能增加token消耗。一個完整的工具調用流在協議層看起來是這樣的事件: text_delta - “我需要查詢天氣...” 事件: function_call - {name: “get_weather”, arguments: {city: “北京”}} 事件: tool_status - {status: “running“, call_id: “xxx“} 事件: tool_result - {call_id: “xxx“, result: {temp: 22, condition: “晴“}} 事件: text_delta - “北京今天天氣晴朗氣溫22度...”這個協議就像前后端之間的“普通話”確保雙方對“正在發(fā)生什么”有一致的理解。2.3 前端作為流式狀態(tài)的渲染器有了流式事件前端的角色就從“結果展示器”轉變?yōu)椤盃顟B(tài)渲染器”。它的核心任務是根據源源不斷的事件流維護并渲染一個動態(tài)的會話狀態(tài)樹。這通常意味著需要一個中心化的狀態(tài)管理如Zustand, Redux Toolkit用于存儲當前會話的所有消息。每條消息不再是一個簡單的字符串而是一個復雜的對象可能包含id: 唯一標識。role:user或assistant。content: 主文本內容可能由多個text_delta事件拼接而成。tool_calls: 一個數組記錄本條消息中AI發(fā)起的所有工具調用。每個工具調用對象包含id: 調用ID用于關聯后續(xù)的tool_status和tool_result。name: 工具名。arguments: 調用參數。status: 當前狀態(tài)pending,running,success,error。result: 工具返回的結果。progress: 可選執(zhí)行進度。當前端收到一個function_call事件時它會在當前助理消息的tool_calls數組中添加一個新項狀態(tài)設為pending并立即渲染一個對應的UI占位符比如一個帶有工具圖標和名稱的卡片。當收到對應的tool_status: running時更新該項狀態(tài)并改變UI如顯示旋轉加載動畫。當收到tool_result時填充結果數據并將狀態(tài)改為successUI更新為展示結果。整個過程是增量、連貫的。實操心得狀態(tài)同步的挑戰(zhàn)這里最大的挑戰(zhàn)是事件順序和狀態(tài)合并。網絡流可能亂序雖然SSE保證順序但WebSocket不一定前端必須根據事件中的call_id等關聯ID精準找到狀態(tài)樹中需要更新的節(jié)點。建議為每個工具調用生成全局唯一的ID并在所有相關事件中攜帶。此外要考慮樂觀更新和錯誤回滾比如工具調用失敗tool_status: error前端需要將對應的UI元素標記為錯誤狀態(tài)并可能提供重試的入口。3. 技術棧深度拆解前后端如何協同工作3.1 后端架構從AI網關到事件調度中心agui的后端通常構建在Node.js如Express/Fastify或Python如FastAPI之上。其核心不再是簡單的“轉發(fā)請求到OpenAI”而是一個智能的流式工作流引擎。我們以FastAPI為例拆解其核心模塊1. 會話與工具管理層這一層維護當前聊天會話的上下文并管理所有可用的工具函數。每個工具都被定義為一個Python函數并附上符合OpenAI Function Calling規(guī)范的JSON Schema描述。當收到用戶消息時該層負責組裝包含對話歷史和工具定義的Prompt發(fā)送給LLM。2. 流式響應生成器這是后端的大腦。它利用支持流式Function Calling的LLM API如OpenAI GPT-4 Turbo, Anthropic Claude或本地部署的DeepSeek等。關鍵技巧在于不能等到LLM的完整響應結束再處理。相反需要逐塊chunk讀取響應。# 偽代碼示例處理OpenAI的流式響應 async def generate_streaming_response(messages, tools): stream await openai_client.chat.completions.create( modelgpt-4-turbo, messagesmessages, toolstools, streamTrue, # 啟用流式 ) async for chunk in stream: delta chunk.choices[0].delta if delta.tool_calls: # 如果這一塊包含工具調用信息 for tool_call in delta.tool_calls: # 累積每個tool_call的function.arguments # 當某個tool_call的arguments累積完成時觸發(fā)一個function_call事件 yield create_event(function_call, tool_call_data) if delta.content: # 如果這一塊是文本內容 yield create_event(text_delta, delta.content)3. 工具執(zhí)行與事件編排層這是最復雜的部分。當generate_streaming_response生成一個完整的function_call事件后后端需要解析出要調用的工具名和參數。立即向客戶端發(fā)送一個tool_status: running事件。在另一個異步任務中實際執(zhí)行該工具函數可能是耗時的網絡請求、數據庫查詢等。工具執(zhí)行過程中如果可以獲取進度如文件上傳百分比則發(fā)送帶有進度的tool_status事件。工具執(zhí)行完畢成功或失敗發(fā)送tool_result或錯誤的tool_status事件。同時可能需要將工具執(zhí)行結果作為新的上下文再次調用LLM生成后續(xù)文本并繼續(xù)流式輸出。注意事項并發(fā)與上下文管理多個工具調用可能是并行的。后端需要妥善管理每個調用的生命周期和上下文關聯。一個常見的做法是為每個用戶會話創(chuàng)建一個唯一的“任務隊列”或“協程組”確保事件流的有序性和隔離性。同時工具執(zhí)行結果需要被追加到會話歷史中以便LLM進行后續(xù)推理但要小心處理token長度限制。3.2 前端架構響應式狀態(tài)與組件化渲染前端采用現代React/Vue/Svelte等框架其架構核心是將事件流映射為響應式狀態(tài)再通過專用組件渲染。1. 事件流連接層使用EventSource用于SSE或WebSocket客戶端連接后端的事件流端點。需要處理連接建立、重連、錯誤處理和消息解析。這里推薦使用成熟的庫如microsoft/fetch-event-sourceSSE或socket.io-clientWebSocket它們提供了更健壯的重試和連接管理機制。2. 狀態(tài)管理中心這是前端應用的狀態(tài)“單一數據源”。以Zustand為例store中可能包含const useChatStore create((set, get) ({ messages: [], // 消息數組每個消息包含復雜的content和tool_calls currentStreamingMessageId: null, // 當前正在流式接收的消息ID // 處理新事件的reducer函數 appendTextDelta: (messageId, delta) { /*...*/ }, addToolCall: (messageId, toolCall) { /*...*/ }, updateToolStatus: (messageId, callId, status, progress) { /*...*/ }, setToolResult: (messageId, callId, result) { /*...*/ }, }));事件流監(jiān)聽器在收到事件后不是直接操作DOM而是調用這些action來更新中央狀態(tài)。3. 專用渲染組件庫這是UI表現力的關鍵。你需要為每種類型的內容設計專門的組件StreamingText組件接收一個不斷增長的文本字符串并實現打字機效果或平滑的段落追加效果。關鍵在于性能避免每次文本更新都導致整個消息重渲染。ToolCallCard組件這是“可感知”的核心視覺元素。它接收一個toolCall對象作為prop并根據其狀態(tài)動態(tài)渲染。pending狀態(tài)顯示工具名稱和參數概要背景色為中性。running狀態(tài)顯示加載動畫如旋轉的圖標或進度條背景色變?yōu)榛顒由?。如果progress屬性存在則渲染一個精確的進度條。success狀態(tài)背景色變?yōu)槌晒ι鐪\綠并展示result數據。結果渲染本身可能很復雜如果是JSON可以用可折疊的樹形視圖如果是圖片直接顯示縮略圖如果是文本優(yōu)雅地格式化。error狀態(tài)背景色變?yōu)榫嫔鐪\紅顯示錯誤信息并可能提供一個“重試”按鈕點擊后可以重新觸發(fā)該工具調用。ReasoningBubble組件可選用于展示AI的思考過程通常設計成區(qū)別于主對話氣泡的樣式如灰色、斜體以表明這是“幕后思考”。4. 布局與動畫流暢的動畫是“可感知”體驗的靈魂。當一個新的ToolCallCard被插入時一個輕微的縮放淡入動畫能吸引用戶注意。狀態(tài)切換時如從running到success可以有一個顏色過渡和圖標變化的動畫。這些微交互通過CSS Transition或Framer Motion等庫實現能極大提升界面的生動感和專業(yè)度。4. 實戰(zhàn)構建一個可感知的天氣查詢機器人讓我們通過一個具體的例子將上述理論串聯起來。我們要構建一個機器人它不僅能回答天氣還能在查詢過程中“可視化”其調用過程。4.1 后端實現FastAPI OpenAI首先定義工具。我們模擬一個天氣API。# tools.py import json import asyncio from typing import Dict import random async def get_current_weather(location: str, unit: str celsius) - Dict: 獲取指定城市的當前天氣。 # 模擬網絡延遲 await asyncio.sleep(1.5) # 模擬API返回 return { location: location, temperature: random.randint(15, 30) if unit celsius else random.randint(60, 86), unit: unit, forecast: [sunny, cloudy, rainy][random.randint(0, 2)], humidity: random.randint(30, 90) } WEATHER_TOOL { type: function, function: { name: get_current_weather, description: 獲取當前天氣信息, parameters: { type: object, properties: { location: {type: string, description: 城市名稱}, unit: {type: string, enum: [celsius, fahrenheit], description: 溫度單位} }, required: [location] } } }接著創(chuàng)建核心的流式端點。# main.py from fastapi import FastAPI, Request from fastapi.responses import StreamingResponse import asyncio import json from tools import get_current_weather, WEATHER_TOOL app FastAPI() async def event_generator(prompt: str): 核心的事件流生成器 # 1. 模擬LLM的流式文本輸出 thinking_texts [讓我查一下天氣信息..., 我需要調用天氣工具。] for text in thinking_texts: yield fdata: {json.dumps({type: text_delta, content: text})}\n\n await asyncio.sleep(0.5) # 2. 發(fā)送工具調用事件 (模擬LLM決定調用工具) tool_call_id call_weather_123 tool_call_event { type: function_call, call_id: tool_call_id, name: get_current_weather, arguments: {location: prompt, unit: celsius} } yield fdata: {json.dumps(tool_call_event)}\n\n # 3. 立即發(fā)送工具開始執(zhí)行狀態(tài) yield fdata: {json.dumps({type: tool_status, call_id: tool_call_id, status: running, progress: 0})}\n\n # 4. 模擬工具執(zhí)行進度可選 for i in range(1, 4): await asyncio.sleep(0.3) yield fdata: {json.dumps({type: tool_status, call_id: tool_call_id, status: running, progress: i*25})}\n\n # 5. 實際執(zhí)行工具這里是模擬 try: weather_result await get_current_weather(prompt) # 發(fā)送工具成功結果 yield fdata: {json.dumps({type: tool_result, call_id: tool_call_id, result: weather_result})}\n\n # 更新工具狀態(tài)為成功 yield fdata: {json.dumps({type: tool_status, call_id: tool_call_id, status: success})}\n\n # 6. 模擬LLM基于結果生成總結文本 summary f好的已為您查詢到{prompt}的天氣{weather_result[temperature]}°C天氣{weather_result[forecast]}濕度{weather_result[humidity]}%。 for char in summary: yield fdata: {json.dumps({type: text_delta, content: char})}\n\n await asyncio.sleep(0.02) # 制造打字機效果 except Exception as e: # 如果工具執(zhí)行失敗 yield fdata: {json.dumps({type: tool_status, call_id: tool_call_id, status: error, message: str(e)})}\n\n yield data: [DONE]\n\n app.post(/chat/stream) async def chat_stream(request: Request): body await request.json() user_message body.get(message, ) return StreamingResponse( event_generator(user_message), media_typetext/event-stream, headers{ Cache-Control: no-cache, Connection: keep-alive, X-Accel-Buffering: no # 對Nginx代理很重要 } )4.2 前端實現React Zustand Tailwind CSS首先設置狀態(tài)管理。// store/useChatStore.js import { create } from zustand; const useChatStore create((set, get) ({ messages: [], currentStreamingMessageId: null, // 添加用戶消息 addUserMessage: (content) set((state) ({ messages: [...state.messages, { id: Date.now(), role: user, content, toolCalls: [] }] })), // 開始一個新的助理消息流 startAssistantMessage: () { const msgId Date.now(); set((state) ({ messages: [...state.messages, { id: msgId, role: assistant, content: , toolCalls: [] }], currentStreamingMessageId: msgId })); return msgId; }, // 追加文本到當前流式消息 appendTextDelta: (delta) set((state) ({ messages: state.messages.map(msg msg.id state.currentStreamingMessageId ? { ...msg, content: msg.content delta } : msg ) })), // 添加工具調用 addToolCall: (callId, name, args) set((state) ({ messages: state.messages.map(msg msg.id state.currentStreamingMessageId ? { ...msg, toolCalls: [...msg.toolCalls, { id: callId, name, args, status: pending, result: null, progress: 0 }] } : msg ) })), // 更新工具狀態(tài)和進度 updateToolStatus: (callId, status, progress) set((state) ({ messages: state.messages.map(msg msg.id state.currentStreamingMessageId ? { ...msg, toolCalls: msg.toolCalls.map(tc tc.id callId ? { ...tc, status, ...(progress ! undefined { progress }) } : tc ) } : msg ) })), // 設置工具結果 setToolResult: (callId, result) set((state) ({ messages: state.messages.map(msg msg.id state.currentStreamingMessageId ? { ...msg, toolCalls: msg.toolCalls.map(tc tc.id callId ? { ...tc, result } : tc ) } : msg ) })), }));然后實現事件流連接和處理。// hooks/useChatStream.js import { useEffect, useRef } from react; import useChatStore from ../store/useChatStore; export function useChatStream() { const eventSourceRef useRef(null); const { startAssistantMessage, appendTextDelta, addToolCall, updateToolStatus, setToolResult, } useChatStore(); const sendMessage async (userInput) { // 1. 關閉之前的連接如果有 if (eventSourceRef.current) { eventSourceRef.current.close(); } // 2. 添加用戶消息到界面 useChatStore.getState().addUserMessage(userInput); // 3. 創(chuàng)建新的助理消息槽 const assistantMsgId startAssistantMessage(); // 4. 建立SSE連接 const eventSource new EventSourcePolyfill(/chat/stream?message${encodeURIComponent(userInput)}, { headers: { Content-Type: application/json }, method: POST, body: JSON.stringify({ message: userInput }) }); eventSourceRef.current eventSource; eventSource.onmessage (event) { if (event.data [DONE]) { eventSource.close(); return; } try { const data JSON.parse(event.data); switch (data.type) { case text_delta: appendTextDelta(data.content); break; case function_call: addToolCall(data.call_id, data.name, data.arguments); break; case tool_status: updateToolStatus(data.call_id, data.status, data.progress); break; case tool_result: setToolResult(data.call_id, data.result); break; default: console.warn(未知事件類型:, data.type); } } catch (error) { console.error(解析事件數據失敗:, error); } }; eventSource.onerror (error) { console.error(SSE連接錯誤:, error); eventSource.close(); // 可以在這里更新UI顯示連接錯誤 }; }; // 組件卸載時關閉連接 useEffect(() { return () { if (eventSourceRef.current) { eventSourceRef.current.close(); } }; }, []); return { sendMessage }; }最后創(chuàng)建核心的UI組件。// components/ToolCallCard.jsx import React from react; import { Wifi, Cloud, CloudRain, Sun, AlertCircle, CheckCircle } from lucide-react; const ToolCallCard ({ toolCall }) { const { name, args, status, result, progress } toolCall; // 根據工具名選擇圖標 const getToolIcon () { switch (name) { case get_current_weather: return Cloud classNamew-5 h-5 /; default: return Wifi classNamew-5 h-5 /; } }; // 根據狀態(tài)選擇顏色和圖標 const getStatusConfig () { switch (status) { case pending: return { bg: bg-gray-100, border: border-gray-300, icon: null }; case running: return { bg: bg-blue-50, border: border-blue-300, icon: div classNameanimate-spin rounded-full h-4 w-4 border-b-2 border-blue-500 / }; case success: return { bg: bg-green-50, border: border-green-300, icon: CheckCircle classNamew-4 h-4 text-green-500 / }; case error: return { bg: bg-red-50, border: border-red-300, icon: AlertCircle classNamew-4 h-5 text-red-500 / }; default: return { bg: bg-gray-100, border: border-gray-300, icon: null }; } }; const statusConfig getStatusConfig(); return ( div className{my-3 p-4 rounded-lg border ${statusConfig.bg} ${statusConfig.border} transition-all duration-300} div classNameflex items-center justify-between div classNameflex items-center space-x-3 {getToolIcon()} div h4 classNamefont-medium text-gray-800調用工具: {name}/h4 p classNametext-sm text-gray-600 mt-1 參數: {args ? JSON.stringify(args) : 無} /p /div /div div classNameflex items-center space-x-2 {statusConfig.icon} span className{text-sm font-medium px-2 py-1 rounded ${ status running ? text-blue-700 bg-blue-100 : status success ? text-green-700 bg-green-100 : status error ? text-red-700 bg-red-100 : text-gray-700 bg-gray-100 }} {status running ? 執(zhí)行中 : status success ? 成功 : status error ? 失敗 : 等待中} /span /div /div {/* 進度條 */} {status running progress ! undefined ( div classNamemt-3 div classNameflex justify-between text-xs text-gray-500 mb-1 span執(zhí)行進度/span span{progress}%/span /div div classNamew-full bg-gray-200 rounded-full h-2 div classNamebg-blue-500 h-2 rounded-full transition-all duration-300 style{{ width: ${progress}% }} / /div /div )} {/* 結果展示 */} {status success result ( div classNamemt-4 p-3 bg-white rounded border border-gray-200 div classNameflex items-center justify-between mb-2 span classNametext-sm font-medium text-gray-700執(zhí)行結果/span Sun classNamew-5 h-5 text-yellow-500 / /div {name get_current_weather ( div classNamegrid grid-cols-2 gap-2 text-sm div classNamespace-y-1 div classNametext-gray-600地點/div div classNamefont-medium{result.location}/div /div div classNamespace-y-1 div classNametext-gray-600溫度/div div classNamefont-medium{result.temperature}°{result.unit celsius ? C : F}/div /div div classNamespace-y-1 div classNametext-gray-600天氣/div div classNamefont-medium{result.forecast}/div /div div classNamespace-y-1 div classNametext-gray-600濕度/div div classNamefont-medium{result.humidity}%/div /div /div )} /div )} {/* 錯誤信息 */} {status error ( div classNamemt-3 p-3 bg-red-50 rounded border border-red-200 div classNameflex items-center text-red-700 AlertCircle classNamew-4 h-4 mr-2 / span classNametext-sm工具執(zhí)行失敗/span /div /div )} /div ); }; export default ToolCallCard;將這一切組合到主聊天界面。// components/ChatInterface.jsx import React, { useState } from react; import useChatStore from ../store/useChatStore; import { useChatStream } from ../hooks/useChatStream; import ToolCallCard from ./ToolCallCard; const ChatInterface () { const [input, setInput] useState(); const messages useChatStore((state) state.messages); const { sendMessage } useChatStream(); const handleSubmit async (e) { e.preventDefault(); if (!input.trim()) return; const userMessage input; setInput(); await sendMessage(userMessage); }; return ( div classNameflex flex-col h-screen max-w-4xl mx-auto p-4 {/* 消息列表 */} div classNameflex-1 overflow-y-auto mb-4 space-y-6 p-2 {messages.map((msg) ( div key{msg.id} className{flex ${msg.role user ? justify-end : justify-start}} div className{max-w-[80%] rounded-2xl px-4 py-3 ${ msg.role user ? bg-blue-500 text-white rounded-br-none : bg-gray-100 text-gray-800 rounded-bl-none }} {/* 消息文本內容 */} {msg.content ( div classNamewhitespace-pre-wrap{msg.content}/div )} {/* 工具調用卡片列表 */} {msg.toolCalls msg.toolCalls.length 0 ( div classNamemt-3 space-y-2 {msg.toolCalls.map((toolCall) ( ToolCallCard key{toolCall.id} toolCall{toolCall} / ))} /div )} /div /div ))} /div {/* 輸入框 */} form onSubmit{handleSubmit} classNameflex space-x-2 input typetext value{input} onChange{(e) setInput(e.target.value)} placeholder輸入您的問題例如北京天氣怎么樣 classNameflex-1 p-3 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 / button typesubmit classNamepx-6 py-3 bg-blue-500 text-white font-medium rounded-lg hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 發(fā)送 /button /form /div ); }; export default ChatInterface;通過以上代碼我們實現了一個完整的、可感知工具調用的天氣查詢機器人。當用戶詢問“上海天氣如何”時他們會看到首先出現“讓我查一下天氣信息...”的流式文本。緊接著一個“調用工具: get_current_weather”的卡片出現狀態(tài)從“等待中”變?yōu)椤皥?zhí)行中”并伴隨一個從0%到100%的進度條。進度條走完卡片狀態(tài)變?yōu)椤俺晒Α毕路秸归_一個美觀的天氣信息面板顯示溫度、濕度等。最后AI生成的總結文本以打字機效果流式出現。整個過程流暢、直觀用戶對AI的“工作流程”一目了然。5. 進階優(yōu)化與避坑指南5.1 性能優(yōu)化避免渲染卡頓當工具調用多、事件流密集時頻繁的React狀態(tài)更新可能導致UI卡頓。以下是一些優(yōu)化策略1. 事件批處理Debouncing不要每個text_delta事件可能每個字一個事件都觸發(fā)React更新?？梢岳鄯e一小段時間如100毫秒內的文本增量然后批量更新狀態(tài)。// 在事件處理層加入批處理 let textBuffer ; let bufferTimer null; eventSource.onmessage (event) { // ... 解析事件 ... if (data.type text_delta) { textBuffer data.content; if (!bufferTimer) { bufferTimer setTimeout(() { appendTextDelta(textBuffer); // 批量更新 textBuffer ; bufferTimer null; }, 100); // 100ms批處理窗口 } } // ... 處理其他事件 ... };2. 虛擬列表Virtual List當消息歷史很長時渲染所有消息尤其是包含復雜工具卡片的會嚴重影響性能。使用如react-window或react-virtualized庫只渲染可視區(qū)域內的消息。3. 工具卡片結果懶渲染對于狀態(tài)為success且包含大量結果數據如圖片畫廊、大型JSON的工具卡片初始可以只渲染一個摘要或“展開查看”按鈕點擊后再渲染完整內容避免一次性渲染過多DOM節(jié)點。5.2 錯誤處理與用戶體驗1. 工具調用失敗的重試機制在ToolCallCard組件的錯誤狀態(tài)中可以提供一個“重試”按鈕。點擊后前端應能向后端發(fā)送一個特定請求僅重試該失敗的工具調用而不是重新運行整個對話鏈。這需要后端支持根據call_id重新執(zhí)行特定工具。2. 網絡中斷與重連SSE連接可能不穩(wěn)定。需要實現自動重連邏輯并在UI上給予提示如“連接中斷正在重連...”。重連后理想情況是后端能從上一次中斷的事件點繼續(xù)流式傳輸但這需要后端支持會話狀態(tài)持久化和斷點續(xù)傳實現較復雜。一個更簡單的方案是提示用戶手動刷新或重新發(fā)送消息。3. 超時控制為工具調用設置超時。如果某個工具running狀態(tài)超過預定時間如30秒前端自動將其狀態(tài)標記為timeout并提示用戶“操作超時請稍后重試或簡化請求”。5.3 擴展性設計支持更豐富的工具類型上述例子主要針對數據工具。要支持更豐富的類型需要在事件協議和前端渲染上做擴展。1. 圖像生成工具后端事件除了tool_status和tool_result可以新增一個image_progress事件攜帶生成進度和中間預覽圖如果AI服務支持。前端渲染ToolCallCard可以演變?yōu)镮mageGenerationCard在running狀態(tài)顯示一個不斷演化的圖片預覽如從模糊到清晰并附上進度百分比。2. 長時間運行任務如視頻處理這類任務可能持續(xù)數分鐘。除了進度條可以提供“后臺運行”選項。用戶可最小化該工具卡片系統在后臺繼續(xù)執(zhí)行完成后通過瀏覽器通知Notification API或全局狀態(tài)提示用戶。3. 交互式工具如表單填寫某些工具可能需要用戶輸入更多信息。例如一個“預訂餐廳”的工具在調用后返回一個有空位的時段列表需要用戶選擇。這可以通過在tool_result事件中攜帶一個requires_user_input字段和一組選項來實現。前端渲染一個迷你表單用戶提交選擇后前端將該選擇作為新的user消息發(fā)送給后端繼續(xù)工作流。5.4 安全與生產化考量1. 輸入輸出凈化用戶輸入和工具返回結果在渲染到前端前必須進行凈化防止XSS攻擊。對于工具返回的JSON避免直接使用innerHTML或dangerouslySetInnerHTML。使用安全的渲染庫或確保所有動態(tài)內容都經過轉義。2. 敏感信息過濾工具調用可能返回敏感數據如個人ID、部分電話號碼。后端在發(fā)送tool_result事件前應有過濾機制對敏感字段進行脫敏如替換為***。3. 速率限制與防濫用流式端點容易被濫用。需要在后端實施嚴格的速率限制Rate Limiting基于用戶IP或會話ID限制單位時間內的請求次數和總連接數。4. 監(jiān)控與日志由于交互是流式的、狀態(tài)復雜的完善的監(jiān)控至關重要。記錄關鍵事件會話開始、工具調用、工具成功/失敗、流式結束并關聯唯一的會話ID和工具調用ID這樣在出現問題時可以快速回溯整個交互鏈條。6. 總結與展望超越聊天的未來交互通過拆解agui這類項目的思想我們可以看到“可感知的工具調用”不僅僅是一個UI特效它代表了AI應用交互范式的一次重要演進。它將AI從“神秘的黑箱”轉變?yōu)椤巴该鞯膮f作者”。這種透明性帶來了多重好處建立信任用戶能看到AI的“工作過程”理解為什么需要時間減少因等待而產生的焦慮和懷疑。教育用戶直觀展示了AI的能力邊界和工作原理幫助用戶學習如何更有效地與AI協作。提升容錯性當某個工具步驟失敗時用戶可以清晰地看到是哪一步出了問題而不是面對一個籠統的“出錯了”提示。啟發(fā)性交互動態(tài)的、可視化的過程本身可能激發(fā)用戶新的想法提出更復雜或更精準的后續(xù)指令。從技術實現角度看這套模式的核心在于將“狀態(tài)變化”作為一等公民進行建模和通信。后端專注于生成狀態(tài)變化事件流前端專注于渲染這些狀態(tài)變化。這種關注點分離使得系統非常靈活易于擴展新的工具類型和交互形式。展望未來這種“流式UI”的思想可以進一步延伸多模態(tài)流不僅是文本和工具狀態(tài)還可以流式傳輸圖像、音頻、3D模型的生成過程。協作式工具調用在工具執(zhí)行到某個中間狀態(tài)時主動暫停并邀請用戶介入做出選擇形成人機協同的混合工作流?？山忉屝栽鰪妼I的“思維鏈”Chain-of-Thought也作為可流式化、可可視化的一部分讓推理過程更加透明。實現這樣的界面固然比做一個簡單的聊天框要復雜但帶來的用戶體驗提升是巨大的。對于志在打造下一代AI原生應用的開發(fā)者來說投入精力掌握這套“流式UI”與“可感知工具調用”的技術棧無疑是構建產品護城河的關鍵一步。agui等項目為我們提供了優(yōu)秀的起點但真正的創(chuàng)新在于你如何利用這些模式去解決自己領域內那些尚未被很好滿足的交互需求。 構建可感知AI交互界面：流式UI與工具調用深度融合實戰(zhàn)
1. 項目概述從純文本到可感知交互的范式躍遷如果你最近也在搗鼓AI應用開發(fā)尤其是基于大語言模型LLM的聊天機器人大概率會遇到一個共同的瓶頸交互體驗太“平”了。用戶輸入問題AI吐出一大段文字偶爾夾雜著一些格式混亂的代碼或JSON。當AI需要調用工具比如搜索網絡、查詢數據庫、生成圖片時這個過程對用戶而言是完全“黑盒”的。用戶只能看到一個“思考中”的提示然后等待一個最終結果中間發(fā)生了什么、進行到哪一步了一概不知。這種純文本的交互方式極大地限制了AI應用的表達力和用戶信任感。這正是我最近深度研究一個名為agui的開源項目時感觸最深的地方。agui 不僅僅是一個簡單的前后端聊天模板它更像是一個關于“如何設計下一代AI交互界面”的完整提案。它的核心目標就是實現“可感知的工具調用”。簡單來說就是讓用戶能“看見”AI思考、決策和行動的全過程將一次工具調用從后臺的靜默執(zhí)行轉變?yōu)榍芭_可觀察、可理解、甚至可交互的視覺流。想象一下這個場景你問AI“幫我總結今天關于量子計算的最新論文并找一張相關的示意圖”。在一個傳統的聊天界面里你只會看到AI回復“正在處理...”然后幾分鐘后如果沒超時的話丟給你一段總結和一張圖片鏈接。而在agui構建的界面里你可能會實時看到“步驟1正在調用學術搜索引擎...”伴隨一個旋轉的搜索圖標和進度條→ “已找到10篇相關論文正在提取摘要...”顯示一個動態(tài)增長的列表→ “正在調用文生圖模型生成示意圖...”顯示一個圖片從模糊到清晰的生成過程→ “完成”。整個過程流暢、透明用戶不再是被動等待而是成為了過程的觀察者甚至參與者。這種體驗的升級其意義遠超“好看”的范疇。它直接提升了應用的可用性、可信度和用戶粘性。用戶知道AI沒有“卡死”理解任務的復雜性并對最終結果有合理的預期。對于開發(fā)者而言agui提供了一套從后端流式數據生成到前端流式渲染的完整技術棧參考極具實戰(zhàn)價值。接下來我就結合對agui項目的拆解深入聊聊如何從零構建這樣一個“可感知”的AI交互界面。2. 核心設計理念流式UI與工具調用的深度融合2.1 打破“請求-響應”的原子模型傳統Web交互和許多早期AI應用都基于簡單的“請求-響應”模型。用戶發(fā)送一個消息服務器處理可能調用多次AI和工具最后返回一個完整的響應。這個模型對于AI工具調用極不友好因為一次復雜的任務可能包含多個串行或并行的工具調用每個調用都有其延遲和狀態(tài)。原子模型迫使我們將所有這些中間狀態(tài)壓縮成一個最終態(tài)返回丟失了所有過程信息。agui的設計起點就是徹底摒棄這個模型擁抱“流式會話”的概念。整個會話不再是一個個獨立的“消息-回復”對而是一個持續(xù)的、狀態(tài)可變的流。在這個流中不僅最終的文本內容可以分塊chunk傳輸任何中間狀態(tài)——包括但不限于AI的思考Reasoning、工具調用的決策Function Call、工具執(zhí)行的狀態(tài)Tool Status、工具執(zhí)行的結果Tool Result、乃至基于結果生成的新內容——都可以作為獨立的事件Event在流中實時推送。這種設計帶來了架構上的根本變化。后端不再是“處理完所有事情再返回”而是變成了一個“狀態(tài)機”或“工作流引擎”它負責推進會話狀態(tài)并在狀態(tài)變化的每一個節(jié)點即時地將變化序列化為事件通過SSEServer-Sent Events或WebSocket流式推送給前端。前端則監(jiān)聽這些事件流并依據事件的類型和內容動態(tài)地、增量地更新UI。2.2 定義可流式化的事件協議要實現前后端的高效協作一個清晰、可擴展的事件協議是關鍵。agui在這方面做了很好的示范。它沒有使用過于復雜的標準如OpenAI的流式格式而是定義了一套簡潔明了的自定義事件。核心事件類型通常包括text_delta: 最基礎的文本流攜帶文本塊。這是兼容普通聊天的基礎。function_call: 聲明AI決定調用某個工具。事件體包含工具名稱和調用參數通常是JSON。這是“可感知”的起點前端收到后可以立即渲染一個“準備調用XXX工具”的UI元素。tool_status: 報告工具執(zhí)行狀態(tài)。如running、success、error。攜帶狀態(tài)信息和可能的進度如progress: 50。這允許前端更新對應工具UI的狀態(tài)如進度條、顏色變化。tool_result: 攜帶工具執(zhí)行成功后的結果數據?？赡苁俏谋?、JSON、圖片URL等。前端可以用特定形式如折疊面板、卡片、內聯圖片展示結果。reasoning: 可選流式傳輸AI的“思考鏈”。這能極大增強透明度和趣味性但可能增加token消耗。一個完整的工具調用流在協議層看起來是這樣的事件: text_delta - “我需要查詢天氣...” 事件: function_call - {name: “get_weather”, arguments: {city: “北京”}} 事件: tool_status - {status: “running“, call_id: “xxx“} 事件: tool_result - {call_id: “xxx“, result: {temp: 22, condition: “晴“}} 事件: text_delta - “北京今天天氣晴朗氣溫22度...”這個協議就像前后端之間的“普通話”確保雙方對“正在發(fā)生什么”有一致的理解。2.3 前端作為流式狀態(tài)的渲染器有了流式事件前端的角色就從“結果展示器”轉變?yōu)椤盃顟B(tài)渲染器”。它的核心任務是根據源源不斷的事件流維護并渲染一個動態(tài)的會話狀態(tài)樹。這通常意味著需要一個中心化的狀態(tài)管理如Zustand, Redux Toolkit用于存儲當前會話的所有消息。每條消息不再是一個簡單的字符串而是一個復雜的對象可能包含id: 唯一標識。role:user或assistant。content: 主文本內容可能由多個text_delta事件拼接而成。tool_calls: 一個數組記錄本條消息中AI發(fā)起的所有工具調用。每個工具調用對象包含id: 調用ID用于關聯后續(xù)的tool_status和tool_result。name: 工具名。arguments: 調用參數。status: 當前狀態(tài)pending,running,success,error。result: 工具返回的結果。progress: 可選執(zhí)行進度。當前端收到一個function_call事件時它會在當前助理消息的tool_calls數組中添加一個新項狀態(tài)設為pending并立即渲染一個對應的UI占位符比如一個帶有工具圖標和名稱的卡片。當收到對應的tool_status: running時更新該項狀態(tài)并改變UI如顯示旋轉加載動畫。當收到tool_result時填充結果數據并將狀態(tài)改為successUI更新為展示結果。整個過程是增量、連貫的。實操心得狀態(tài)同步的挑戰(zhàn)這里最大的挑戰(zhàn)是事件順序和狀態(tài)合并。網絡流可能亂序雖然SSE保證順序但WebSocket不一定前端必須根據事件中的call_id等關聯ID精準找到狀態(tài)樹中需要更新的節(jié)點。建議為每個工具調用生成全局唯一的ID并在所有相關事件中攜帶。此外要考慮樂觀更新和錯誤回滾比如工具調用失敗tool_status: error前端需要將對應的UI元素標記為錯誤狀態(tài)并可能提供重試的入口。3. 技術棧深度拆解前后端如何協同工作3.1 后端架構從AI網關到事件調度中心agui的后端通常構建在Node.js如Express/Fastify或Python如FastAPI之上。其核心不再是簡單的“轉發(fā)請求到OpenAI”而是一個智能的流式工作流引擎。我們以FastAPI為例拆解其核心模塊1. 會話與工具管理層這一層維護當前聊天會話的上下文并管理所有可用的工具函數。每個工具都被定義為一個Python函數并附上符合OpenAI Function Calling規(guī)范的JSON Schema描述。當收到用戶消息時該層負責組裝包含對話歷史和工具定義的Prompt發(fā)送給LLM。2. 流式響應生成器這是后端的大腦。它利用支持流式Function Calling的LLM API如OpenAI GPT-4 Turbo, Anthropic Claude或本地部署的DeepSeek等。關鍵技巧在于不能等到LLM的完整響應結束再處理。相反需要逐塊chunk讀取響應。# 偽代碼示例處理OpenAI的流式響應 async def generate_streaming_response(messages, tools): stream await openai_client.chat.completions.create( modelgpt-4-turbo, messagesmessages, toolstools, streamTrue, # 啟用流式 ) async for chunk in stream: delta chunk.choices[0].delta if delta.tool_calls: # 如果這一塊包含工具調用信息 for tool_call in delta.tool_calls: # 累積每個tool_call的function.arguments # 當某個tool_call的arguments累積完成時觸發(fā)一個function_call事件 yield create_event(function_call, tool_call_data) if delta.content: # 如果這一塊是文本內容 yield create_event(text_delta, delta.content)3. 工具執(zhí)行與事件編排層這是最復雜的部分。當generate_streaming_response生成一個完整的function_call事件后后端需要解析出要調用的工具名和參數。立即向客戶端發(fā)送一個tool_status: running事件。在另一個異步任務中實際執(zhí)行該工具函數可能是耗時的網絡請求、數據庫查詢等。工具執(zhí)行過程中如果可以獲取進度如文件上傳百分比則發(fā)送帶有進度的tool_status事件。工具執(zhí)行完畢成功或失敗發(fā)送tool_result或錯誤的tool_status事件。同時可能需要將工具執(zhí)行結果作為新的上下文再次調用LLM生成后續(xù)文本并繼續(xù)流式輸出。注意事項并發(fā)與上下文管理多個工具調用可能是并行的。后端需要妥善管理每個調用的生命周期和上下文關聯。一個常見的做法是為每個用戶會話創(chuàng)建一個唯一的“任務隊列”或“協程組”確保事件流的有序性和隔離性。同時工具執(zhí)行結果需要被追加到會話歷史中以便LLM進行后續(xù)推理但要小心處理token長度限制。3.2 前端架構響應式狀態(tài)與組件化渲染前端采用現代React/Vue/Svelte等框架其架構核心是將事件流映射為響應式狀態(tài)再通過專用組件渲染。1. 事件流連接層使用EventSource用于SSE或WebSocket客戶端連接后端的事件流端點。需要處理連接建立、重連、錯誤處理和消息解析。這里推薦使用成熟的庫如microsoft/fetch-event-sourceSSE或socket.io-clientWebSocket它們提供了更健壯的重試和連接管理機制。2. 狀態(tài)管理中心這是前端應用的狀態(tài)“單一數據源”。以Zustand為例store中可能包含const useChatStore create((set, get) ({ messages: [], // 消息數組每個消息包含復雜的content和tool_calls currentStreamingMessageId: null, // 當前正在流式接收的消息ID // 處理新事件的reducer函數 appendTextDelta: (messageId, delta) { /*...*/ }, addToolCall: (messageId, toolCall) { /*...*/ }, updateToolStatus: (messageId, callId, status, progress) { /*...*/ }, setToolResult: (messageId, callId, result) { /*...*/ }, }));事件流監(jiān)聽器在收到事件后不是直接操作DOM而是調用這些action來更新中央狀態(tài)。3. 專用渲染組件庫這是UI表現力的關鍵。你需要為每種類型的內容設計專門的組件StreamingText組件接收一個不斷增長的文本字符串并實現打字機效果或平滑的段落追加效果。關鍵在于性能避免每次文本更新都導致整個消息重渲染。ToolCallCard組件這是“可感知”的核心視覺元素。它接收一個toolCall對象作為prop并根據其狀態(tài)動態(tài)渲染。pending狀態(tài)顯示工具名稱和參數概要背景色為中性。running狀態(tài)顯示加載動畫如旋轉的圖標或進度條背景色變?yōu)榛顒由?。如果progress屬性存在則渲染一個精確的進度條。success狀態(tài)背景色變?yōu)槌晒ι鐪\綠并展示result數據。結果渲染本身可能很復雜如果是JSON可以用可折疊的樹形視圖如果是圖片直接顯示縮略圖如果是文本優(yōu)雅地格式化。error狀態(tài)背景色變?yōu)榫嫔鐪\紅顯示錯誤信息并可能提供一個“重試”按鈕點擊后可以重新觸發(fā)該工具調用。ReasoningBubble組件可選用于展示AI的思考過程通常設計成區(qū)別于主對話氣泡的樣式如灰色、斜體以表明這是“幕后思考”。4. 布局與動畫流暢的動畫是“可感知”體驗的靈魂。當一個新的ToolCallCard被插入時一個輕微的縮放淡入動畫能吸引用戶注意。狀態(tài)切換時如從running到success可以有一個顏色過渡和圖標變化的動畫。這些微交互通過CSS Transition或Framer Motion等庫實現能極大提升界面的生動感和專業(yè)度。4. 實戰(zhàn)構建一個可感知的天氣查詢機器人讓我們通過一個具體的例子將上述理論串聯起來。我們要構建一個機器人它不僅能回答天氣還能在查詢過程中“可視化”其調用過程。4.1 后端實現FastAPI OpenAI首先定義工具。我們模擬一個天氣API。# tools.py import json import asyncio from typing import Dict import random async def get_current_weather(location: str, unit: str celsius) - Dict: 獲取指定城市的當前天氣。 # 模擬網絡延遲 await asyncio.sleep(1.5) # 模擬API返回 return { location: location, temperature: random.randint(15, 30) if unit celsius else random.randint(60, 86), unit: unit, forecast: [sunny, cloudy, rainy][random.randint(0, 2)], humidity: random.randint(30, 90) } WEATHER_TOOL { type: function, function: { name: get_current_weather, description: 獲取當前天氣信息, parameters: { type: object, properties: { location: {type: string, description: 城市名稱}, unit: {type: string, enum: [celsius, fahrenheit], description: 溫度單位} }, required: [location] } } }接著創(chuàng)建核心的流式端點。# main.py from fastapi import FastAPI, Request from fastapi.responses import StreamingResponse import asyncio import json from tools import get_current_weather, WEATHER_TOOL app FastAPI() async def event_generator(prompt: str): 核心的事件流生成器 # 1. 模擬LLM的流式文本輸出 thinking_texts [讓我查一下天氣信息..., 我需要調用天氣工具。] for text in thinking_texts: yield fdata: {json.dumps({type: text_delta, content: text})}\n\n await asyncio.sleep(0.5) # 2. 發(fā)送工具調用事件 (模擬LLM決定調用工具) tool_call_id call_weather_123 tool_call_event { type: function_call, call_id: tool_call_id, name: get_current_weather, arguments: {location: prompt, unit: celsius} } yield fdata: {json.dumps(tool_call_event)}\n\n # 3. 立即發(fā)送工具開始執(zhí)行狀態(tài) yield fdata: {json.dumps({type: tool_status, call_id: tool_call_id, status: running, progress: 0})}\n\n # 4. 模擬工具執(zhí)行進度可選 for i in range(1, 4): await asyncio.sleep(0.3) yield fdata: {json.dumps({type: tool_status, call_id: tool_call_id, status: running, progress: i*25})}\n\n # 5. 實際執(zhí)行工具這里是模擬 try: weather_result await get_current_weather(prompt) # 發(fā)送工具成功結果 yield fdata: {json.dumps({type: tool_result, call_id: tool_call_id, result: weather_result})}\n\n # 更新工具狀態(tài)為成功 yield fdata: {json.dumps({type: tool_status, call_id: tool_call_id, status: success})}\n\n # 6. 模擬LLM基于結果生成總結文本 summary f好的已為您查詢到{prompt}的天氣{weather_result[temperature]}°C天氣{weather_result[forecast]}濕度{weather_result[humidity]}%。 for char in summary: yield fdata: {json.dumps({type: text_delta, content: char})}\n\n await asyncio.sleep(0.02) # 制造打字機效果 except Exception as e: # 如果工具執(zhí)行失敗 yield fdata: {json.dumps({type: tool_status, call_id: tool_call_id, status: error, message: str(e)})}\n\n yield data: [DONE]\n\n app.post(/chat/stream) async def chat_stream(request: Request): body await request.json() user_message body.get(message, ) return StreamingResponse( event_generator(user_message), media_typetext/event-stream, headers{ Cache-Control: no-cache, Connection: keep-alive, X-Accel-Buffering: no # 對Nginx代理很重要 } )4.2 前端實現React Zustand Tailwind CSS首先設置狀態(tài)管理。// store/useChatStore.js import { create } from zustand; const useChatStore create((set, get) ({ messages: [], currentStreamingMessageId: null, // 添加用戶消息 addUserMessage: (content) set((state) ({ messages: [...state.messages, { id: Date.now(), role: user, content, toolCalls: [] }] })), // 開始一個新的助理消息流 startAssistantMessage: () { const msgId Date.now(); set((state) ({ messages: [...state.messages, { id: msgId, role: assistant, content: , toolCalls: [] }], currentStreamingMessageId: msgId })); return msgId; }, // 追加文本到當前流式消息 appendTextDelta: (delta) set((state) ({ messages: state.messages.map(msg msg.id state.currentStreamingMessageId ? { ...msg, content: msg.content delta } : msg ) })), // 添加工具調用 addToolCall: (callId, name, args) set((state) ({ messages: state.messages.map(msg msg.id state.currentStreamingMessageId ? { ...msg, toolCalls: [...msg.toolCalls, { id: callId, name, args, status: pending, result: null, progress: 0 }] } : msg ) })), // 更新工具狀態(tài)和進度 updateToolStatus: (callId, status, progress) set((state) ({ messages: state.messages.map(msg msg.id state.currentStreamingMessageId ? { ...msg, toolCalls: msg.toolCalls.map(tc tc.id callId ? { ...tc, status, ...(progress ! undefined { progress }) } : tc ) } : msg ) })), // 設置工具結果 setToolResult: (callId, result) set((state) ({ messages: state.messages.map(msg msg.id state.currentStreamingMessageId ? { ...msg, toolCalls: msg.toolCalls.map(tc tc.id callId ? { ...tc, result } : tc ) } : msg ) })), }));然后實現事件流連接和處理。// hooks/useChatStream.js import { useEffect, useRef } from react; import useChatStore from ../store/useChatStore; export function useChatStream() { const eventSourceRef useRef(null); const { startAssistantMessage, appendTextDelta, addToolCall, updateToolStatus, setToolResult, } useChatStore(); const sendMessage async (userInput) { // 1. 關閉之前的連接如果有 if (eventSourceRef.current) { eventSourceRef.current.close(); } // 2. 添加用戶消息到界面 useChatStore.getState().addUserMessage(userInput); // 3. 創(chuàng)建新的助理消息槽 const assistantMsgId startAssistantMessage(); // 4. 建立SSE連接 const eventSource new EventSourcePolyfill(/chat/stream?message${encodeURIComponent(userInput)}, { headers: { Content-Type: application/json }, method: POST, body: JSON.stringify({ message: userInput }) }); eventSourceRef.current eventSource; eventSource.onmessage (event) { if (event.data [DONE]) { eventSource.close(); return; } try { const data JSON.parse(event.data); switch (data.type) { case text_delta: appendTextDelta(data.content); break; case function_call: addToolCall(data.call_id, data.name, data.arguments); break; case tool_status: updateToolStatus(data.call_id, data.status, data.progress); break; case tool_result: setToolResult(data.call_id, data.result); break; default: console.warn(未知事件類型:, data.type); } } catch (error) { console.error(解析事件數據失敗:, error); } }; eventSource.onerror (error) { console.error(SSE連接錯誤:, error); eventSource.close(); // 可以在這里更新UI顯示連接錯誤 }; }; // 組件卸載時關閉連接 useEffect(() { return () { if (eventSourceRef.current) { eventSourceRef.current.close(); } }; }, []); return { sendMessage }; }最后創(chuàng)建核心的UI組件。// components/ToolCallCard.jsx import React from react; import { Wifi, Cloud, CloudRain, Sun, AlertCircle, CheckCircle } from lucide-react; const ToolCallCard ({ toolCall }) { const { name, args, status, result, progress } toolCall; // 根據工具名選擇圖標 const getToolIcon () { switch (name) { case get_current_weather: return Cloud classNamew-5 h-5 /; default: return Wifi classNamew-5 h-5 /; } }; // 根據狀態(tài)選擇顏色和圖標 const getStatusConfig () { switch (status) { case pending: return { bg: bg-gray-100, border: border-gray-300, icon: null }; case running: return { bg: bg-blue-50, border: border-blue-300, icon: div classNameanimate-spin rounded-full h-4 w-4 border-b-2 border-blue-500 / }; case success: return { bg: bg-green-50, border: border-green-300, icon: CheckCircle classNamew-4 h-4 text-green-500 / }; case error: return { bg: bg-red-50, border: border-red-300, icon: AlertCircle classNamew-4 h-5 text-red-500 / }; default: return { bg: bg-gray-100, border: border-gray-300, icon: null }; } }; const statusConfig getStatusConfig(); return ( div className{my-3 p-4 rounded-lg border ${statusConfig.bg} ${statusConfig.border} transition-all duration-300} div classNameflex items-center justify-between div classNameflex items-center space-x-3 {getToolIcon()} div h4 classNamefont-medium text-gray-800調用工具: {name}/h4 p classNametext-sm text-gray-600 mt-1 參數: {args ? JSON.stringify(args) : 無} /p /div /div div classNameflex items-center space-x-2 {statusConfig.icon} span className{text-sm font-medium px-2 py-1 rounded ${ status running ? text-blue-700 bg-blue-100 : status success ? text-green-700 bg-green-100 : status error ? text-red-700 bg-red-100 : text-gray-700 bg-gray-100 }} {status running ? 執(zhí)行中 : status success ? 成功 : status error ? 失敗 : 等待中} /span /div /div {/* 進度條 */} {status running progress ! undefined ( div classNamemt-3 div classNameflex justify-between text-xs text-gray-500 mb-1 span執(zhí)行進度/span span{progress}%/span /div div classNamew-full bg-gray-200 rounded-full h-2 div classNamebg-blue-500 h-2 rounded-full transition-all duration-300 style{{ width: ${progress}% }} / /div /div )} {/* 結果展示 */} {status success result ( div classNamemt-4 p-3 bg-white rounded border border-gray-200 div classNameflex items-center justify-between mb-2 span classNametext-sm font-medium text-gray-700執(zhí)行結果/span Sun classNamew-5 h-5 text-yellow-500 / /div {name get_current_weather ( div classNamegrid grid-cols-2 gap-2 text-sm div classNamespace-y-1 div classNametext-gray-600地點/div div classNamefont-medium{result.location}/div /div div classNamespace-y-1 div classNametext-gray-600溫度/div div classNamefont-medium{result.temperature}°{result.unit celsius ? C : F}/div /div div classNamespace-y-1 div classNametext-gray-600天氣/div div classNamefont-medium{result.forecast}/div /div div classNamespace-y-1 div classNametext-gray-600濕度/div div classNamefont-medium{result.humidity}%/div /div /div )} /div )} {/* 錯誤信息 */} {status error ( div classNamemt-3 p-3 bg-red-50 rounded border border-red-200 div classNameflex items-center text-red-700 AlertCircle classNamew-4 h-4 mr-2 / span classNametext-sm工具執(zhí)行失敗/span /div /div )} /div ); }; export default ToolCallCard;將這一切組合到主聊天界面。// components/ChatInterface.jsx import React, { useState } from react; import useChatStore from ../store/useChatStore; import { useChatStream } from ../hooks/useChatStream; import ToolCallCard from ./ToolCallCard; const ChatInterface () { const [input, setInput] useState(); const messages useChatStore((state) state.messages); const { sendMessage } useChatStream(); const handleSubmit async (e) { e.preventDefault(); if (!input.trim()) return; const userMessage input; setInput(); await sendMessage(userMessage); }; return ( div classNameflex flex-col h-screen max-w-4xl mx-auto p-4 {/* 消息列表 */} div classNameflex-1 overflow-y-auto mb-4 space-y-6 p-2 {messages.map((msg) ( div key{msg.id} className{flex ${msg.role user ? justify-end : justify-start}} div className{max-w-[80%] rounded-2xl px-4 py-3 ${ msg.role user ? bg-blue-500 text-white rounded-br-none : bg-gray-100 text-gray-800 rounded-bl-none }} {/* 消息文本內容 */} {msg.content ( div classNamewhitespace-pre-wrap{msg.content}/div )} {/* 工具調用卡片列表 */} {msg.toolCalls msg.toolCalls.length 0 ( div classNamemt-3 space-y-2 {msg.toolCalls.map((toolCall) ( ToolCallCard key{toolCall.id} toolCall{toolCall} / ))} /div )} /div /div ))} /div {/* 輸入框 */} form onSubmit{handleSubmit} classNameflex space-x-2 input typetext value{input} onChange{(e) setInput(e.target.value)} placeholder輸入您的問題例如北京天氣怎么樣 classNameflex-1 p-3 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 / button typesubmit classNamepx-6 py-3 bg-blue-500 text-white font-medium rounded-lg hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 發(fā)送 /button /form /div ); }; export default ChatInterface;通過以上代碼我們實現了一個完整的、可感知工具調用的天氣查詢機器人。當用戶詢問“上海天氣如何”時他們會看到首先出現“讓我查一下天氣信息...”的流式文本。緊接著一個“調用工具: get_current_weather”的卡片出現狀態(tài)從“等待中”變?yōu)椤皥?zhí)行中”并伴隨一個從0%到100%的進度條。進度條走完卡片狀態(tài)變?yōu)椤俺晒Α毕路秸归_一個美觀的天氣信息面板顯示溫度、濕度等。最后AI生成的總結文本以打字機效果流式出現。整個過程流暢、直觀用戶對AI的“工作流程”一目了然。5. 進階優(yōu)化與避坑指南5.1 性能優(yōu)化避免渲染卡頓當工具調用多、事件流密集時頻繁的React狀態(tài)更新可能導致UI卡頓。以下是一些優(yōu)化策略1. 事件批處理Debouncing不要每個text_delta事件可能每個字一個事件都觸發(fā)React更新?？梢岳鄯e一小段時間如100毫秒內的文本增量然后批量更新狀態(tài)。// 在事件處理層加入批處理 let textBuffer ; let bufferTimer null; eventSource.onmessage (event) { // ... 解析事件 ... if (data.type text_delta) { textBuffer data.content; if (!bufferTimer) { bufferTimer setTimeout(() { appendTextDelta(textBuffer); // 批量更新 textBuffer ; bufferTimer null; }, 100); // 100ms批處理窗口 } } // ... 處理其他事件 ... };2. 虛擬列表Virtual List當消息歷史很長時渲染所有消息尤其是包含復雜工具卡片的會嚴重影響性能。使用如react-window或react-virtualized庫只渲染可視區(qū)域內的消息。3. 工具卡片結果懶渲染對于狀態(tài)為success且包含大量結果數據如圖片畫廊、大型JSON的工具卡片初始可以只渲染一個摘要或“展開查看”按鈕點擊后再渲染完整內容避免一次性渲染過多DOM節(jié)點。5.2 錯誤處理與用戶體驗1. 工具調用失敗的重試機制在ToolCallCard組件的錯誤狀態(tài)中可以提供一個“重試”按鈕。點擊后前端應能向后端發(fā)送一個特定請求僅重試該失敗的工具調用而不是重新運行整個對話鏈。這需要后端支持根據call_id重新執(zhí)行特定工具。2. 網絡中斷與重連SSE連接可能不穩(wěn)定。需要實現自動重連邏輯并在UI上給予提示如“連接中斷正在重連...”。重連后理想情況是后端能從上一次中斷的事件點繼續(xù)流式傳輸但這需要后端支持會話狀態(tài)持久化和斷點續(xù)傳實現較復雜。一個更簡單的方案是提示用戶手動刷新或重新發(fā)送消息。3. 超時控制為工具調用設置超時。如果某個工具running狀態(tài)超過預定時間如30秒前端自動將其狀態(tài)標記為timeout并提示用戶“操作超時請稍后重試或簡化請求”。5.3 擴展性設計支持更豐富的工具類型上述例子主要針對數據工具。要支持更豐富的類型需要在事件協議和前端渲染上做擴展。1. 圖像生成工具后端事件除了tool_status和tool_result可以新增一個image_progress事件攜帶生成進度和中間預覽圖如果AI服務支持。前端渲染ToolCallCard可以演變?yōu)镮mageGenerationCard在running狀態(tài)顯示一個不斷演化的圖片預覽如從模糊到清晰并附上進度百分比。2. 長時間運行任務如視頻處理這類任務可能持續(xù)數分鐘。除了進度條可以提供“后臺運行”選項。用戶可最小化該工具卡片系統在后臺繼續(xù)執(zhí)行完成后通過瀏覽器通知Notification API或全局狀態(tài)提示用戶。3. 交互式工具如表單填寫某些工具可能需要用戶輸入更多信息。例如一個“預訂餐廳”的工具在調用后返回一個有空位的時段列表需要用戶選擇。這可以通過在tool_result事件中攜帶一個requires_user_input字段和一組選項來實現。前端渲染一個迷你表單用戶提交選擇后前端將該選擇作為新的user消息發(fā)送給后端繼續(xù)工作流。5.4 安全與生產化考量1. 輸入輸出凈化用戶輸入和工具返回結果在渲染到前端前必須進行凈化防止XSS攻擊。對于工具返回的JSON避免直接使用innerHTML或dangerouslySetInnerHTML。使用安全的渲染庫或確保所有動態(tài)內容都經過轉義。2. 敏感信息過濾工具調用可能返回敏感數據如個人ID、部分電話號碼。后端在發(fā)送tool_result事件前應有過濾機制對敏感字段進行脫敏如替換為***。3. 速率限制與防濫用流式端點容易被濫用。需要在后端實施嚴格的速率限制Rate Limiting基于用戶IP或會話ID限制單位時間內的請求次數和總連接數。4. 監(jiān)控與日志由于交互是流式的、狀態(tài)復雜的完善的監(jiān)控至關重要。記錄關鍵事件會話開始、工具調用、工具成功/失敗、流式結束并關聯唯一的會話ID和工具調用ID這樣在出現問題時可以快速回溯整個交互鏈條。6. 總結與展望超越聊天的未來交互通過拆解agui這類項目的思想我們可以看到“可感知的工具調用”不僅僅是一個UI特效它代表了AI應用交互范式的一次重要演進。它將AI從“神秘的黑箱”轉變?yōu)椤巴该鞯膮f作者”。這種透明性帶來了多重好處建立信任用戶能看到AI的“工作過程”理解為什么需要時間減少因等待而產生的焦慮和懷疑。教育用戶直觀展示了AI的能力邊界和工作原理幫助用戶學習如何更有效地與AI協作。提升容錯性當某個工具步驟失敗時用戶可以清晰地看到是哪一步出了問題而不是面對一個籠統的“出錯了”提示。啟發(fā)性交互動態(tài)的、可視化的過程本身可能激發(fā)用戶新的想法提出更復雜或更精準的后續(xù)指令。從技術實現角度看這套模式的核心在于將“狀態(tài)變化”作為一等公民進行建模和通信。后端專注于生成狀態(tài)變化事件流前端專注于渲染這些狀態(tài)變化。這種關注點分離使得系統非常靈活易于擴展新的工具類型和交互形式。展望未來這種“流式UI”的思想可以進一步延伸多模態(tài)流不僅是文本和工具狀態(tài)還可以流式傳輸圖像、音頻、3D模型的生成過程。協作式工具調用在工具執(zhí)行到某個中間狀態(tài)時主動暫停并邀請用戶介入做出選擇形成人機協同的混合工作流?？山忉屝栽鰪妼I的“思維鏈”Chain-of-Thought也作為可流式化、可可視化的一部分讓推理過程更加透明。實現這樣的界面固然比做一個簡單的聊天框要復雜但帶來的用戶體驗提升是巨大的。對于志在打造下一代AI原生應用的開發(fā)者來說投入精力掌握這套“流式UI”與“可感知工具調用”的技術棧無疑是構建產品護城河的關鍵一步。agui等項目為我們提供了優(yōu)秀的起點但真正的創(chuàng)新在于你如何利用這些模式去解決自己領域內那些尚未被很好滿足的交互需求。