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