如果你最近關(guān)注 AI 領(lǐng)域尤其是大模型應(yīng)用開發(fā)可能會(huì)發(fā)現(xiàn)一個(gè)現(xiàn)象人人都想做一個(gè) AI Agent但真正能跑起來(lái)、用起來(lái)的卻不多。問(wèn)題出在哪里是模型不夠聰明還是開發(fā)者能力不足都不是。真正卡住大多數(shù)人的是那些“工程化”的細(xì)節(jié)如何讓 Agent 穩(wěn)定地調(diào)用工具如何管理復(fù)雜的對(duì)話狀態(tài)如何將 Agent 能力集成到現(xiàn)有業(yè)務(wù)系統(tǒng)如何監(jiān)控和調(diào)試它的行為這些看似瑣碎的問(wèn)題恰恰是決定一個(gè) AI 想法能否落地為產(chǎn)品的關(guān)鍵。這就是AI Agent 平臺(tái)工程要解決的核心問(wèn)題。它不是一個(gè)炫酷的新概念而是一套實(shí)實(shí)在在的工程實(shí)踐旨在為 AI Agent 的構(gòu)建、部署和管理提供基礎(chǔ)設(shè)施。今天我們不談空洞的理論而是從一個(gè)實(shí)踐者的角度深入探討為什么我們需要這樣一個(gè)平臺(tái)以及如何從零開始構(gòu)建它。本文將以一個(gè)實(shí)戰(zhàn)項(xiàng)目的視角帶你理解平臺(tái)工程的必要性并拆解其核心組件與實(shí)現(xiàn)路徑。1. 這篇文章真正要解決的問(wèn)題這篇文章不是要教你調(diào)用某個(gè) API 或使用某個(gè)現(xiàn)成的 Agent 框架。它的目標(biāo)是解決一個(gè)更根本的痛點(diǎn)當(dāng)你想規(guī)?；a(chǎn)品化地使用 AI Agent 時(shí)單點(diǎn)、臨時(shí)的腳本開發(fā)模式為何會(huì)迅速失效以及如何通過(guò)平臺(tái)化的工程手段來(lái)系統(tǒng)性地解決這些問(wèn)題。很多開發(fā)者對(duì) AI Agent 的認(rèn)知還停留在“Prompt 函數(shù)調(diào)用”的層面。他們可能會(huì)用 LangChain 或 Semantic Kernel 快速拼湊出一個(gè)能回答問(wèn)題的 Demo但當(dāng)面臨以下場(chǎng)景時(shí)就會(huì)束手無(wú)策場(chǎng)景一你為客服系統(tǒng)開發(fā)了一個(gè)處理退貨的 Agent。在測(cè)試中它表現(xiàn)完美但上線后因?yàn)橐粋€(gè)外部 API 的響應(yīng)格式變化導(dǎo)致整個(gè)流程卡死且沒有留下任何可供排查的日志。場(chǎng)景二你設(shè)計(jì)了一個(gè)多步驟的財(cái)務(wù)審批 Agent涉及數(shù)據(jù)庫(kù)查詢、規(guī)則校驗(yàn)和郵件發(fā)送。當(dāng)審批邏輯需要調(diào)整時(shí)你發(fā)現(xiàn)修改代碼后新舊流程的狀態(tài)遷移變得異常復(fù)雜容易產(chǎn)生臟數(shù)據(jù)。場(chǎng)景三團(tuán)隊(duì)有多個(gè)成員在開發(fā)不同的 Agent營(yíng)銷文案、數(shù)據(jù)報(bào)表、代碼審查。每個(gè)人都有自己的環(huán)境配置、依賴管理和部署腳本導(dǎo)致協(xié)作效率低下且生產(chǎn)環(huán)境部署風(fēng)險(xiǎn)極高。這些問(wèn)題背后的共性是缺乏一套標(biāo)準(zhǔn)化的、可觀測(cè)的、可運(yùn)維的“生產(chǎn)流水線”。AI Agent 平臺(tái)工程就是要搭建這條流水線。本文將圍繞一個(gè)假設(shè)的、但高度貼近實(shí)戰(zhàn)的“OpenVitamin”平臺(tái)項(xiàng)目拆解平臺(tái)工程需要包含哪些核心模塊以及如何用具體的技術(shù)棧來(lái)實(shí)現(xiàn)它們。讀完本文你將能清晰地規(guī)劃出自己的 Agent 平臺(tái)架構(gòu)并避開初期最容易踩的坑。2. 基礎(chǔ)概念與核心原理Agent、Workflow 與 Harness在深入平臺(tái)細(xì)節(jié)前必須厘清幾個(gè)容易混淆的核心概念。網(wǎng)絡(luò)上很多討論將 Agent、Workflow、Harness 等詞混用導(dǎo)致理解上的偏差。2.1 AI Agent智能體具備自主行動(dòng)能力的單元AI Agent 的核心是感知-思考-行動(dòng)循環(huán)。它接收來(lái)自用戶或環(huán)境的輸入感知利用大模型進(jìn)行推理和規(guī)劃思考然后執(zhí)行具體的動(dòng)作行動(dòng)如調(diào)用工具、查詢知識(shí)庫(kù)、生成回復(fù)等。關(guān)鍵點(diǎn)Agent 不是簡(jiǎn)單的“問(wèn)答機(jī)”它是一個(gè)有狀態(tài)的、能自主決策的程序?qū)嶓w。一個(gè)成熟的 Agent 應(yīng)該能處理異常、管理多輪對(duì)話的上下文、并在目標(biāo)驅(qū)動(dòng)下選擇最佳行動(dòng)路徑。2.2 Workflow工作流對(duì)復(fù)雜任務(wù)的流程編排當(dāng)單個(gè) Agent 無(wú)法完成復(fù)雜任務(wù)時(shí)就需要 Workflow。Workflow 將一個(gè)大任務(wù)分解為多個(gè)有序或并行的步驟每個(gè)步驟可能由不同的 Agent 或自動(dòng)化工具如數(shù)據(jù)庫(kù)操作、API調(diào)用來(lái)完成。通俗理解Agent 是一個(gè)“智能員工”而 Workflow 是一份“標(biāo)準(zhǔn)作業(yè)程序SOP”指導(dǎo)多個(gè)員工如何協(xié)作完成一個(gè)項(xiàng)目。例如“生成季度市場(chǎng)報(bào)告”這個(gè) Workflow可能包含“數(shù)據(jù)收集Agent - 數(shù)據(jù)分析Agent - 報(bào)告撰寫Agent - 郵件發(fā)送服務(wù)”等多個(gè)環(huán)節(jié)。2.3 Harness基礎(chǔ)設(shè)施層包裹 Agent 的“航天服”這是平臺(tái)工程中最關(guān)鍵、也最容易被忽視的一層。Harness 是一套包裹在 AI Agent 核心推理邏輯之外的基礎(chǔ)設(shè)施層。它不負(fù)責(zé)代替 Agent 思考而是為 Agent 的穩(wěn)定運(yùn)行提供生命支持。你可以把 Harness 想象成宇航員的航天服。宇航員Agent負(fù)責(zé)執(zhí)行任務(wù)但航天服Harness提供了氧氣狀態(tài)/上下文管理、溫度調(diào)節(jié)異常處理/重試、通信日志/監(jiān)控和生命保障安全/權(quán)限控制。沒有 HarnessAgent 在復(fù)雜的生產(chǎn)環(huán)境中將寸步難行。Harness 的典型職責(zé)包括生命周期管理Agent 的創(chuàng)建、初始化、掛起、恢復(fù)和銷毀。狀態(tài)持久化將會(huì)話狀態(tài)、執(zhí)行上下文保存到數(shù)據(jù)庫(kù)或緩存中支持長(zhǎng)時(shí)間運(yùn)行的任務(wù)和斷點(diǎn)續(xù)傳。工具調(diào)用與編排統(tǒng)一管理 Agent 可用的工具Tools處理工具注冊(cè)、發(fā)現(xiàn)、授權(quán)和調(diào)用?？捎^測(cè)性集成日志、指標(biāo)Metrics和追蹤Tracing讓 Agent 的每一次思考、每一次行動(dòng)都清晰可見。安全與合規(guī)權(quán)限校驗(yàn)、輸入輸出過(guò)濾、敏感信息脫敏、訪問(wèn)審計(jì)。資源隔離與調(diào)度在多租戶環(huán)境下隔離不同用戶或團(tuán)隊(duì)的 Agent 運(yùn)行環(huán)境。2.4 核心架構(gòu)層級(jí)關(guān)系一個(gè)完整的 AI 應(yīng)用系統(tǒng)通常按以下層級(jí)構(gòu)成┌─────────────────────────────────────┐ │ 應(yīng)用層 (Application) │ ← 面向用戶的業(yè)務(wù)功能 ├─────────────────────────────────────┤ │ 工作流層 (Workflow) │ ← 任務(wù)編排與流程引擎 ├─────────────────────────────────────┤ │ 智能體層 (Agent) 基礎(chǔ)設(shè)施層 (Harness) │ ← 核心執(zhí)行單元與保障體系 ├─────────────────────────────────────┤ │ 推理層 (LLM) │ ← 大模型能力如 GPT、Claude、本地模型 ├─────────────────────────────────────┤ │ 檢索增強(qiáng)層 (RAG) / 工具層 (Tools) │ ← 外部知識(shí)/能力擴(kuò)展 └─────────────────────────────────────┘LLM 是大腦RAG/Tools 是手腳和資料庫(kù)Agent 是協(xié)調(diào)二者的“小腦”Harness 是保障系統(tǒng)Workflow 是項(xiàng)目經(jīng)理最終共同向上支撐具體應(yīng)用。平臺(tái)工程主要聚焦在Harness和Workflow 引擎的構(gòu)建上。3. 環(huán)境準(zhǔn)備與前置條件在開始構(gòu)建我們的“OpenVitamin”平臺(tái)前需要準(zhǔn)備好開發(fā)環(huán)境。本文假設(shè)你具備基本的 Python 后端開發(fā)經(jīng)驗(yàn)。核心環(huán)境與工具操作系統(tǒng)Linux (Ubuntu 20.04)、macOS 或 WSL2 (Windows)。Python 版本3.9 或 3.10這是多數(shù) AI 框架兼容性最好的版本。版本控制Git。包管理Pip 或 Poetry推薦 Poetry能更好地管理依賴。數(shù)據(jù)庫(kù)PostgreSQL (用于持久化元數(shù)據(jù)、狀態(tài)) 和 Redis (用于緩存、消息隊(duì)列)。容器化 (可選但推薦)Docker Docker Compose用于快速部署依賴服務(wù)。LLM 接入你需要一個(gè)可用的 LLM API 密鑰例如 OpenAI GPT、 Anthropic Claude 或國(guó)內(nèi)合規(guī)的大模型平臺(tái) API。本文示例將使用 OpenAI 格式的 API。項(xiàng)目初始化# 創(chuàng)建項(xiàng)目目錄 mkdir openvitamin-platform cd openvitamin-platform # 初始化虛擬環(huán)境 (以 Poetry 為例) poetry init -n poetry add fastapi uvicorn sqlalchemy pydantic redis psycopg2-binary # 添加 AI 相關(guān)依賴?yán)?LangChain 作為 Agent 核心框架的參考 poetry add langchain langchain-openai langchain-community # 開發(fā)依賴 poetry add --dev pytest httpx black isort關(guān)鍵依賴說(shuō)明FastAPIUvicorn: 構(gòu)建高性能的 API 服務(wù)器。SQLAlchemy: ORM用于操作 PostgreSQL。Pydantic: 數(shù)據(jù)驗(yàn)證和設(shè)置管理。Redis: 用于緩存會(huì)話、任務(wù)隊(duì)列。LangChain: 這里主要作為實(shí)現(xiàn) Agent 邏輯的參考框架。在真實(shí)平臺(tái)中你可能需要基于其思想進(jìn)行更深度的定制甚至自研。4. 平臺(tái)核心模塊拆解與設(shè)計(jì)我們的“OpenVitamin”平臺(tái)將包含以下核心模塊它們共同構(gòu)成了 Harness 層和 Workflow 引擎。4.1 模塊一Agent 運(yùn)行時(shí)引擎這是平臺(tái)的心臟負(fù)責(zé)加載 Agent 定義、管理其生命周期、執(zhí)行推理循環(huán)。設(shè)計(jì)要點(diǎn)定義統(tǒng)一的Agent基類所有自定義 Agent 必須繼承它。實(shí)現(xiàn)AgentRuntime類負(fù)責(zé)創(chuàng)建 Agent 實(shí)例、注入上下文Context、調(diào)用run方法。上下文Context應(yīng)包含會(huì)話ID、用戶信息、當(dāng)前輸入、歷史消息、可用工具列表、配置參數(shù)等。4.2 模塊二工具管理與注冊(cè)中心Agent 的能力邊界由其可調(diào)用的工具決定。平臺(tái)需要統(tǒng)一管理工具。設(shè)計(jì)要點(diǎn)定義Tool基類包含name,description,parameters,_run方法。實(shí)現(xiàn)ToolRegistry單例所有工具在啟動(dòng)時(shí)向其中注冊(cè)。Agent 在運(yùn)行時(shí)從ToolRegistry動(dòng)態(tài)獲取可用工具列表并生成符合大模型函數(shù)調(diào)用規(guī)范的描述。4.3 模塊三狀態(tài)管理與持久化Agent 和 Workflow 通常是有狀態(tài)的。狀態(tài)必須持久化以支持服務(wù)重啟、長(zhǎng)時(shí)間任務(wù)和水平擴(kuò)展。設(shè)計(jì)要點(diǎn)設(shè)計(jì)StateStore抽象層定義get_state(session_id),save_state(session_id, state)等接口。提供基于 Redis緩存和 PostgreSQL持久化的兩種實(shí)現(xiàn)。狀態(tài)數(shù)據(jù)應(yīng)包括對(duì)話歷史、Agent內(nèi)部變量、Workflow 節(jié)點(diǎn)執(zhí)行狀態(tài)等。4.4 模塊四工作流編排引擎用于定義和執(zhí)行業(yè)務(wù)流程將多個(gè) Agent 和自動(dòng)化任務(wù)串聯(lián)起來(lái)。設(shè)計(jì)要點(diǎn)采用有向無(wú)環(huán)圖DAG定義 Workflow。每個(gè)節(jié)點(diǎn)Node代表一個(gè)執(zhí)行單元Agent、工具、條件判斷、循環(huán)。引擎需要解析 DAG按依賴關(guān)系調(diào)度節(jié)點(diǎn)執(zhí)行并處理節(jié)點(diǎn)間的數(shù)據(jù)傳遞。4.5 模塊五可觀測(cè)性套件沒有可觀測(cè)性線上問(wèn)題就是黑洞。必須集成日志、指標(biāo)和鏈路追蹤。設(shè)計(jì)要點(diǎn)結(jié)構(gòu)化日志使用structlog或json-logger為每一條日志附加session_id,agent_id,workflow_id等字段。指標(biāo)Metrics使用 Prometheus 客戶端庫(kù)暴露關(guān)鍵指標(biāo)如Agent 調(diào)用次數(shù)、耗時(shí)、成功率、Token 消耗量。分布式追蹤Tracing集成 OpenTelemetry追蹤一個(gè)用戶請(qǐng)求流經(jīng)多個(gè) Agent 和 Workflow 節(jié)點(diǎn)的完整路徑。4.6 模塊六API 網(wǎng)關(guān)與權(quán)限控制對(duì)外提供統(tǒng)一的 RESTful 或 WebSocket API并處理認(rèn)證、授權(quán)、限流等。設(shè)計(jì)要點(diǎn)使用 FastAPI 的依賴注入系統(tǒng)實(shí)現(xiàn)權(quán)限校驗(yàn)。API 設(shè)計(jì)應(yīng)清晰例如POST /api/v1/agents/{agent_id}/invoke用于調(diào)用 AgentPOST /api/v1/workflows/{workflow_id}/execute用于執(zhí)行工作流。5. 核心代碼實(shí)現(xiàn)示例下面我們以“工具管理”和“Agent運(yùn)行時(shí)”為例展示關(guān)鍵代碼片段。請(qǐng)注意這是高度簡(jiǎn)化的示例用于闡明設(shè)計(jì)思想。5.1 工具注冊(cè)中心實(shí)現(xiàn)# file: openvitamin/core/tools/registry.py from typing import Dict, Any, Callable, List from pydantic import BaseModel, Field import inspect class ToolParameter(BaseModel): name: str type: str description: str required: bool True class Tool(BaseModel): 工具基類定義 name: str description: str parameters: List[ToolParameter] func: Callable class Config: arbitrary_types_allowed True async def _run(self, **kwargs) - Any: return await self.func(**kwargs) if inspect.iscoroutinefunction(self.func) else self.func(**kwargs) class ToolRegistry: 工具注冊(cè)中心單例模式 _instance None _tools: Dict[str, Tool] {} def __new__(cls): if cls._instance is None: cls._instance super(ToolRegistry, cls).__new__(cls) return cls._instance def register(self, tool: Tool): if tool.name in self._tools: raise ValueError(fTool {tool.name} is already registered.) self._tools[tool.name] tool print(fTool registered: {tool.name}) def get_tool(self, name: str) - Tool: tool self._tools.get(name) if not tool: raise KeyError(fTool {name} not found.) return tool def get_tools_for_llm(self) - List[Dict]: 生成供LLM函數(shù)調(diào)用使用的工具描述列表 tools_schema [] for tool in self._tools.values(): schema { type: function, function: { name: tool.name, description: tool.description, parameters: { type: object, properties: { param.name: {type: param.type, description: param.description} for param in tool.parameters }, required: [p.name for p in tool.parameters if p.required], } } } tools_schema.append(schema) return tools_schema # 全局注冊(cè)中心實(shí)例 registry ToolRegistry()5.2 定義一個(gè)計(jì)算器工具并注冊(cè)# file: openvitamin/core/tools/calculator.py from openvitamin.core.tools.registry import Tool, ToolParameter, registry def add_numbers(a: float, b: float) - float: 將兩個(gè)數(shù)字相加。 return a b # 創(chuàng)建工具實(shí)例并注冊(cè) calculator_tool Tool( namecalculator_add, description用于兩個(gè)數(shù)字相加的計(jì)算器。, parameters[ ToolParameter(namea, typenumber, description第一個(gè)加數(shù)), ToolParameter(nameb, typenumber, description第二個(gè)加數(shù)), ], funcadd_numbers ) registry.register(calculator_tool)5.3 簡(jiǎn)化的 Agent 運(yùn)行時(shí)與上下文# file: openvitamin/core/agent/runtime.py from typing import List, Dict, Any, Optional from pydantic import BaseModel, Field from openvitamin.core.tools.registry import registry import asyncio class AgentContext(BaseModel): Agent 執(zhí)行上下文 session_id: str user_input: str conversation_history: List[Dict] Field(default_factorylist) max_turns: int 10 class BaseAgent: Agent 基類 name: str BaseAgent system_prompt: str 你是一個(gè)有幫助的AI助手。 def __init__(self, context: AgentContext): self.context context self.available_tools registry.get_tools_for_llm() async def think(self, llm_client) - Dict: 核心推理邏輯讓LLM根據(jù)歷史和工具決定下一步行動(dòng)。 # 1. 構(gòu)建包含工具描述的提示詞 messages [ {role: system, content: self.system_prompt}, *self.context.conversation_history, {role: user, content: self.context.user_input} ] # 2. 調(diào)用LLM開啟函數(shù)調(diào)用能力 response await llm_client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, toolsself.available_tools, tool_choiceauto ) return response.choices[0].message async def act(self, llm_decision): 執(zhí)行LLM決策如果是工具調(diào)用則執(zhí)行工具。 if llm_decision.tool_calls: tool_call llm_decision.tool_calls[0] tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments) # 從注冊(cè)中心獲取工具并執(zhí)行 tool registry.get_tool(tool_name) result await tool._run(**tool_args) # 將工具執(zhí)行結(jié)果作為新的上下文消息 return { role: tool, content: str(result), tool_call_id: tool_call.id } else: # 如果是純文本回復(fù)直接返回 return {role: assistant, content: llm_decision.content} async def run(self, llm_client): 執(zhí)行一輪Agent循環(huán) llm_decision await self.think(llm_client) action_result await self.act(llm_decision) # 更新對(duì)話歷史 self.context.conversation_history.extend([ {role: user, content: self.context.user_input}, llm_decision.model_dump(), # 保存LLM的原始決策 action_result ]) return action_result class AgentRuntime: Agent 運(yùn)行時(shí)管理器 def __init__(self, state_store): self.state_store state_store async def create_session(self, agent_class, user_id, initial_input): session_id f{user_id}_{int(time.time())} context AgentContext(session_idsession_id, user_inputinitial_input) agent agent_class(context) # 保存初始狀態(tài) await self.state_store.save_state(session_id, {context: context.dict(), agent_class: agent_class.__name__}) return session_id, agent async def invoke_agent(self, session_id: str, user_input: str, llm_client): # 1. 從狀態(tài)存儲(chǔ)恢復(fù)上下文和Agent state await self.state_store.get_state(session_id) context_data state.get(context, {}) context_data[user_input] user_input context AgentContext(**context_data) # 2. 動(dòng)態(tài)創(chuàng)建Agent實(shí)例 (實(shí)際項(xiàng)目可能需要更復(fù)雜的工廠模式) agent_class globals().get(state.get(agent_class, BaseAgent)) agent agent_class(context) # 3. 執(zhí)行Agent result await agent.run(llm_client) # 4. 保存更新后的狀態(tài) await self.state_store.save_state(session_id, {context: agent.context.dict(), agent_class: agent_class.__name__}) return result5.4 基于 FastAPI 的 Agent 調(diào)用端點(diǎn)# file: openvitamin/api/endpoints/agents.py from fastapi import APIRouter, Depends, HTTPException from openvitamin.core.agent.runtime import AgentRuntime from openvitamin.core.state.redis_store import RedisStateStore # 假設(shè)我們有一個(gè)Redis實(shí)現(xiàn) from openvitamin.core.llm.client import get_llm_client # 獲取LLM客戶端 router APIRouter(prefix/api/v1/agents, tags[agents]) # 依賴注入 def get_agent_runtime(): state_store RedisStateStore() return AgentRuntime(state_store) router.post(/{agent_name}/invoke) async def invoke_agent( agent_name: str, request: dict, # 包含 session_id, message runtime: AgentRuntime Depends(get_agent_runtime), llm_client Depends(get_llm_client) ): 調(diào)用指定的Agent。 請(qǐng)求體示例: {session_id: user_123_171..., message: 你好請(qǐng)幫我計(jì)算一下1234等于多少} session_id request.get(session_id) user_input request.get(message) if not session_id: # 如果沒有session_id則創(chuàng)建新會(huì)話 session_id, _ await runtime.create_session(agent_name, anonymous, user_input) try: result await runtime.invoke_agent(session_id, user_input, llm_client) return { session_id: session_id, response: result.get(content, ), status: success } except Exception as e: # 記錄詳細(xì)日志 logger.error(fAgent invocation failed: {e}, exc_infoTrue) raise HTTPException(status_code500, detailfAgent execution error: {str(e)})6. 運(yùn)行與效果驗(yàn)證6.1 啟動(dòng)服務(wù)與依賴首先確保 PostgreSQL 和 Redis 服務(wù)已啟動(dòng)?？梢允褂?Docker Compose 快速搭建# docker-compose.yml version: 3.8 services: postgres: image: postgres:15-alpine environment: POSTGRES_USER: openvitamin POSTGRES_PASSWORD: yourpassword POSTGRES_DB: openvitamin ports: - 5432:5432 volumes: - postgres_data:/var/lib/postgresql/data redis: image: redis:7-alpine ports: - 6379:6379 volumes: - redis_data:/data volumes: postgres_data: redis_data:啟動(dòng)服務(wù)docker-compose up -d6.2 啟動(dòng)平臺(tái) API 服務(wù)在項(xiàng)目根目錄下運(yùn)行# 激活虛擬環(huán)境 poetry shell # 啟動(dòng) FastAPI 服務(wù) uvicorn openvitamin.main:app --host 0.0.0.0 --port 8000 --reload服務(wù)啟動(dòng)后訪問(wèn)http://localhost:8000/docs可以看到自動(dòng)生成的 API 文檔。6.3 測(cè)試 Agent 調(diào)用使用curl或 Postman 測(cè)試我們注冊(cè)的 Agent。假設(shè)我們有一個(gè)名為MathAssistant的 Agent繼承自BaseAgent并使用了calculator_add工具。# 第一次調(diào)用創(chuàng)建新會(huì)話 curl -X POST http://localhost:8000/api/v1/agents/MathAssistant/invoke \ -H Content-Type: application/json \ -d { message: 請(qǐng)計(jì)算 12 加 34 等于多少 } # 預(yù)期返回簡(jiǎn)化 # { # session_id: anonymous_171..., # response: 12 加 34 等于 46。, # status: success # } # 使用同一個(gè) session_id 進(jìn)行后續(xù)對(duì)話 curl -X POST http://localhost:8000/api/v1/agents/MathAssistant/invoke \ -H Content-Type: application/json \ -d { session_id: anonymous_171..., message: 再加上 20 呢 } # 預(yù)期 Agent 能記住上下文并調(diào)用工具計(jì)算 4620如何驗(yàn)證成功API 響應(yīng)返回正確的計(jì)算結(jié)果和success狀態(tài)。服務(wù)日志控制臺(tái)應(yīng)輸出工具注冊(cè)信息、LLM 調(diào)用日志和工具執(zhí)行日志。數(shù)據(jù)庫(kù)/緩存檢查 Redis 或 PostgreSQL 中是否保存了對(duì)應(yīng)session_id的對(duì)話歷史狀態(tài)。可觀測(cè)性如果集成了 Prometheus可以訪問(wèn)http://localhost:8000/metrics查看相關(guān)指標(biāo)是否增加。7. 常見問(wèn)題與排查思路在開發(fā)和運(yùn)行平臺(tái)時(shí)你幾乎一定會(huì)遇到以下問(wèn)題。這里提供一個(gè)排查清單。問(wèn)題現(xiàn)象可能原因排查方式解決方案Agent 調(diào)用返回“Tool not found”1. 工具未正確注冊(cè)。2. 工具名稱在注冊(cè)和調(diào)用時(shí)不匹配。3. Agent 初始化時(shí)未成功加載工具列表。1. 檢查應(yīng)用啟動(dòng)日志確認(rèn)工具注冊(cè)成功。2. 在ToolRegistry中添加list_tools方法打印所有已注冊(cè)工具名。3. 在BaseAgent的__init__中打印self.available_tools。確保工具注冊(cè)代碼在應(yīng)用啟動(dòng)時(shí)被執(zhí)行如放在模塊頂層或使用 FastAPI 的lifespan事件。檢查工具名大小寫和拼寫。LLM 不調(diào)用工具總是直接回復(fù)1. 工具描述description不夠清晰LLM 不理解何時(shí)使用。2. 系統(tǒng)提示詞system_prompt未鼓勵(lì)使用工具。3. LLM 溫度temperature參數(shù)過(guò)高導(dǎo)致隨機(jī)性太強(qiáng)。1. 檢查發(fā)送給 LLM 的tools參數(shù)格式是否正確。2. 在系統(tǒng)提示詞中明確告知 Agent“你可以使用以下工具”。3. 將 LLM 的temperature調(diào)低如 0.1。優(yōu)化工具描述使其任務(wù)導(dǎo)向如“用于計(jì)算兩個(gè)數(shù)字之和”。在提示詞中強(qiáng)調(diào)工具使用。調(diào)整 LLM 參數(shù)。會(huì)話狀態(tài)丟失或混亂1.session_id生成或傳遞錯(cuò)誤。2. 狀態(tài)存儲(chǔ)如 Redis連接失敗或數(shù)據(jù)序列化/反序列化出錯(cuò)。3. 并發(fā)請(qǐng)求導(dǎo)致狀態(tài)覆蓋。1. 在invoke_agent入口和StateStore方法中打印session_id。2. 檢查 Redis 連接狀態(tài)和鍵值內(nèi)容。3. 檢查StateStore.save_state是否使用了正確的序列化方式如 JSON。確保session_id全局唯一且穩(wěn)定。為狀態(tài)存儲(chǔ)實(shí)現(xiàn)連接池和重試機(jī)制。對(duì)于關(guān)鍵狀態(tài)考慮使用數(shù)據(jù)庫(kù)事務(wù)或樂觀鎖。平臺(tái)性能差響應(yīng)慢1. LLM API 調(diào)用是主要瓶頸。2. 工具同步執(zhí)行阻塞主線程。3. 狀態(tài)存儲(chǔ) I/O 頻繁。1. 使用異步 HTTP 客戶端如httpx調(diào)用 LLM API。2. 使用asyncio.gather并發(fā)執(zhí)行多個(gè)獨(dú)立工具調(diào)用。3. 為頻繁讀取的狀態(tài)引入本地緩存如內(nèi)存緩存。全鏈路異步化。對(duì) LLM 調(diào)用實(shí)施限流和隊(duì)列。優(yōu)化狀態(tài)存儲(chǔ)策略區(qū)分熱數(shù)據(jù)和冷數(shù)據(jù)。無(wú)法處理復(fù)雜多輪對(duì)話1. 上下文conversation_history過(guò)長(zhǎng)超出模型 Token 限制。2. 未對(duì)歷史消息進(jìn)行有效的摘要或過(guò)濾。1. 監(jiān)控每次請(qǐng)求發(fā)送給 LLM 的 Token 數(shù)量。2. 實(shí)現(xiàn)一個(gè)ContextManager在歷史達(dá)到一定長(zhǎng)度時(shí)自動(dòng)進(jìn)行摘要或滑動(dòng)窗口截取。集成 Token 計(jì)數(shù)器。實(shí)現(xiàn)上下文窗口管理策略如只保留最近 N 輪對(duì)話或?qū)υ缙趯?duì)話進(jìn)行總結(jié)。8. 最佳實(shí)踐與工程建議構(gòu)建一個(gè)健壯的 AI Agent 平臺(tái)遠(yuǎn)不止讓代碼跑通。以下是從項(xiàng)目實(shí)戰(zhàn)中總結(jié)出的關(guān)鍵建議定義清晰的 Agent 契約在團(tuán)隊(duì)內(nèi)部必須明確一個(gè)“合格”的 Agent 應(yīng)該滿足哪些接口規(guī)范、日志格式、錯(cuò)誤處理方式。這能極大降低協(xié)作成本。工具設(shè)計(jì)的“單一職責(zé)”原則每個(gè)工具應(yīng)只做一件事并且做好。避免創(chuàng)建功能臃腫的“超級(jí)工具”。工具的描述必須精確、無(wú)歧義這是 LLM 能否正確調(diào)用的前提。狀態(tài)管理是重中之重設(shè)計(jì)狀態(tài)數(shù)據(jù)結(jié)構(gòu)時(shí)要考慮向前/向后兼容性。使用版本號(hào)字段以便未來(lái)數(shù)據(jù)結(jié)構(gòu)升級(jí)時(shí)能平滑遷移。定期歸檔或清理過(guò)期會(huì)話狀態(tài)避免存儲(chǔ)無(wú)限膨脹?？捎^測(cè)性先行在開發(fā)第一個(gè) Agent 時(shí)就把日志、指標(biāo)和追蹤的代碼加上。不要等到出問(wèn)題再補(bǔ)。關(guān)鍵指標(biāo)包括請(qǐng)求延遲、Token 消耗、工具調(diào)用成功率、用戶滿意度可通過(guò)后續(xù)評(píng)分反饋。實(shí)施嚴(yán)格的權(quán)限與安全控制工具權(quán)限不是所有 Agent 都能調(diào)用所有工具。建立工具與 Agent或用戶角色的授權(quán)映射。輸入輸出過(guò)濾對(duì)用戶輸入和工具返回結(jié)果進(jìn)行必要的清洗和過(guò)濾防止 Prompt 注入或敏感信息泄露。審計(jì)日志記錄誰(shuí)、在什么時(shí)候、調(diào)用了哪個(gè) Agent、使用了什么工具、消耗了多少資源。為 Workflow 設(shè)計(jì)可視化編輯器當(dāng) Workflow 變得復(fù)雜時(shí)基于代碼或 YAML 的定義方式將難以維護(hù)?？紤]提供一個(gè)簡(jiǎn)單的 Web UI允許通過(guò)拖拽節(jié)點(diǎn)的方式來(lái)編排流程并自動(dòng)生成背后的 DAG 定義。建立 Agent 的評(píng)估與回滾機(jī)制如何判斷新上線的 Agent 版本比舊版本好需要定義業(yè)務(wù)相關(guān)的評(píng)估指標(biāo)如任務(wù)完成率、用戶糾正次數(shù)。同時(shí)平臺(tái)應(yīng)支持快速將 Agent 回滾到上一個(gè)穩(wěn)定版本。考慮多模型與降級(jí)策略不要綁定單一 LLM 供應(yīng)商。抽象 LLM 客戶端層支持快速切換模型如從 GPT-4 降級(jí)到 GPT-3.5 或本地模型。這能提高系統(tǒng)的魯棒性和成本可控性。9. 總結(jié)與后續(xù)學(xué)習(xí)方向通過(guò)本文的拆解我們可以看到一個(gè) AI Agent 平臺(tái)的核心價(jià)值不在于實(shí)現(xiàn)了多么驚艷的 Agent 智能而在于它通過(guò)工程化的手段將 Agent 的開發(fā)、部署和運(yùn)維變得標(biāo)準(zhǔn)化、可管理和可擴(kuò)展。它解決了從“玩具 Demo”到“生產(chǎn)系統(tǒng)”之間的巨大鴻溝。我們從一個(gè)簡(jiǎn)單的工具注冊(cè)、Agent 運(yùn)行時(shí)和狀態(tài)管理模塊開始搭建了平臺(tái)最基礎(chǔ)的骨架。但這僅僅是起點(diǎn)。一個(gè)成熟的生產(chǎn)級(jí)平臺(tái)還需要在以下方向持續(xù)深化更強(qiáng)大的 Workflow 引擎支持條件分支、循環(huán)、并行執(zhí)行、人工審核節(jié)點(diǎn)等。Agent 的版本管理與灰度發(fā)布像管理微服務(wù)一樣管理 Agent 的版本。資源成本核算與優(yōu)化精確計(jì)量每個(gè)會(huì)話、每個(gè)用戶的 Token 消耗和 API 調(diào)用成本。與現(xiàn)有 DevOps 流水線集成將 Agent 的測(cè)試、打包、部署納入 CI/CD。領(lǐng)域特定語(yǔ)言DSL為業(yè)務(wù)人員提供更友好的方式來(lái)描述 Agent 的行為和 Workflow。AI Agent 平臺(tái)工程是一個(gè)正在快速演進(jìn)的領(lǐng)域。它的最終形態(tài)可能是未來(lái)軟件開發(fā)的“操作系統(tǒng)”讓創(chuàng)造智能應(yīng)用像今天搭建網(wǎng)頁(yè)一樣便捷。作為開發(fā)者現(xiàn)在深入理解其原理并動(dòng)手實(shí)踐是在為未來(lái)積累至關(guān)重要的基礎(chǔ)設(shè)施構(gòu)建經(jīng)驗(yàn)。建議你以本文的“OpenVitamin”項(xiàng)目為藍(lán)本從一個(gè)具體的業(yè)務(wù)場(chǎng)景如智能客服、自動(dòng)報(bào)表生成出發(fā)親手搭建一個(gè)最小可用的平臺(tái)在解決真實(shí)問(wèn)題的過(guò)程中你會(huì)對(duì)平臺(tái)工程的價(jià)值有更深刻的體會(huì)。