建AI智能體：核心概念、框架選型與多智能體協(xié)作實(shí)戰(zhàn))
在實(shí)際 AI 應(yīng)用開(kāi)發(fā)中我們經(jīng)常聽(tīng)到“智能體”這個(gè)概念但很多開(kāi)發(fā)者對(duì)它的理解停留在“能調(diào)用 API 的聊天機(jī)器人”層面。最近OpenAI 展示的智能體互聊視頻以及圍繞 Astra AI、Codex、Dify、LangChain 等工具的熱議揭示了一個(gè)更核心的趨勢(shì)智能體正在從簡(jiǎn)單的問(wèn)答工具演變?yōu)槟軌蜃灾饕?guī)劃、使用工具、相互協(xié)作的“數(shù)字員工”。對(duì)于前端、后端或全棧開(kāi)發(fā)者而言理解并實(shí)踐智能體開(kāi)發(fā)不再是錦上添花而是構(gòu)建下一代人機(jī)協(xié)同應(yīng)用的關(guān)鍵能力。本文將從工程實(shí)踐角度為你拆解智能體的核心概念、主流框架、搭建方法并提供一個(gè)從零開(kāi)始構(gòu)建可協(xié)作智能體的完整教程讓你不僅能看懂演示視頻更能親手實(shí)現(xiàn)一個(gè)具備基礎(chǔ)協(xié)作能力的智能體系統(tǒng)。1. 理解智能體從 API 調(diào)用者到自主行動(dòng)者在討論具體代碼之前我們必須先厘清“智能體”在技術(shù)語(yǔ)境下的真實(shí)含義。這決定了我們后續(xù)選擇何種框架、設(shè)計(jì)何種架構(gòu)。1.1 智能體的核心能力與工作流一個(gè)真正的智能體Agent不僅僅是封裝了 OpenAI API 的客戶端。它是一個(gè)具備感知、規(guī)劃、行動(dòng)和反思能力的軟件實(shí)體。其典型工作流可以概括為以下循環(huán)感知接收來(lái)自用戶、環(huán)境或其他智能體的輸入文本、指令、數(shù)據(jù)。規(guī)劃基于目標(biāo)分解任務(wù)決定下一步該調(diào)用哪個(gè)工具或執(zhí)行什么操作。行動(dòng)執(zhí)行規(guī)劃好的步驟例如調(diào)用一個(gè)函數(shù)、查詢數(shù)據(jù)庫(kù)、運(yùn)行一段代碼。反思評(píng)估行動(dòng)結(jié)果判斷是否達(dá)成目標(biāo)或是否需要調(diào)整策略。這個(gè)循環(huán)的核心是“工具使用”能力。智能體通過(guò)調(diào)用預(yù)先定義好的工具如搜索引擎、計(jì)算器、代碼執(zhí)行器、API接口來(lái)擴(kuò)展其能力邊界而不僅僅依賴于大語(yǔ)言模型本身的知識(shí)生成。1.2 主流智能體框架與選型建議當(dāng)前社區(qū)有多個(gè)成熟的智能體開(kāi)發(fā)框架它們抽象了上述工作流讓開(kāi)發(fā)者能更專注于業(yè)務(wù)邏輯。以下是幾個(gè)主流框架的對(duì)比框架名稱核心特點(diǎn)適用場(chǎng)景學(xué)習(xí)曲線LangChain生態(tài)最豐富模塊化設(shè)計(jì)支持多種模型和工具鏈。社區(qū)活躍文檔詳盡。復(fù)雜、定制化要求高的智能體應(yīng)用需要集成多種數(shù)據(jù)源和工具。中等偏上概念較多。Dify開(kāi)箱即用提供可視化編排界面。強(qiáng)調(diào)“工作流”和“應(yīng)用”的概念降低編碼門檻。快速構(gòu)建和部署 AI 應(yīng)用特別是面向非技術(shù)用戶或需要快速原型驗(yàn)證的場(chǎng)景。較低界面友好。Microsoft Autogen專注于多智能體協(xié)作內(nèi)置了多種智能體角色和對(duì)話模式便于構(gòu)建對(duì)話系統(tǒng)。需要多個(gè)智能體相互對(duì)話、協(xié)作完成任務(wù)的研究或應(yīng)用場(chǎng)景。中等需要理解其代理架構(gòu)。CrewAI建立在 LangChain 之上更強(qiáng)調(diào)角色扮演和任務(wù)分工適合模擬團(tuán)隊(duì)協(xié)作。需要模擬銷售、客服、研發(fā)等不同角色協(xié)同工作的場(chǎng)景。中等概念清晰。對(duì)于初學(xué)者或希望快速看到效果的開(kāi)發(fā)者從Dify或CrewAI入手是不錯(cuò)的選擇。如果你需要深度定制和控制每一個(gè)環(huán)節(jié)LangChain是更強(qiáng)大的基礎(chǔ)。而本文為了深入理解智能體協(xié)作的機(jī)制我們將以LangChain為基礎(chǔ)結(jié)合其多智能體協(xié)作擴(kuò)展來(lái)構(gòu)建一個(gè)簡(jiǎn)易的協(xié)作場(chǎng)景。2. 環(huán)境準(zhǔn)備與項(xiàng)目初始化在開(kāi)始編碼前我們需要一個(gè)干凈的 Python 環(huán)境。這里假設(shè)你已安裝 Python 3.8 和 pip。2.1 創(chuàng)建虛擬環(huán)境與安裝依賴強(qiáng)烈建議使用虛擬環(huán)境來(lái)管理依賴避免包沖突。# 創(chuàng)建項(xiàng)目目錄并進(jìn)入 mkdir collaborative-agents-demo cd collaborative-agents-demo # 創(chuàng)建虛擬環(huán)境以 venv 為例 python -m venv venv # 激活虛擬環(huán)境 # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 安裝核心依賴 pip install langchain langchain-openai langchain-community langgraph關(guān)鍵依賴說(shuō)明langchain: 智能體開(kāi)發(fā)的核心框架。langchain-openai: 官方維護(hù)的 OpenAI 模型集成。langchain-community: 社區(qū)貢獻(xiàn)的大量第三方工具和集成。langgraph: LangChain 用于構(gòu)建有狀態(tài)、多步驟工作流如圖的庫(kù)是實(shí)現(xiàn)多智能體協(xié)作循環(huán)的關(guān)鍵。2.2 配置 OpenAI API 密鑰智能體需要“大腦”我們使用 OpenAI 的模型如 gpt-3.5-turbo。你需要一個(gè)有效的 OpenAI API Key。安全提示永遠(yuǎn)不要將 API Key 硬編碼在代碼中或提交到版本控制系統(tǒng)。推薦使用環(huán)境變量管理# Linux/Mac export OPENAI_API_KEY你的-api-key-here # Windows (PowerShell) $env:OPENAI_API_KEY你的-api-key-here或者在項(xiàng)目根目錄創(chuàng)建一個(gè).env文件確保該文件在.gitignore中OPENAI_API_KEY你的-api-key-here然后在 Python 代碼中使用python-dotenv加載需額外安裝pip install python-dotenvfrom dotenv import load_dotenv load_dotenv() # 這會(huì)加載 .env 文件中的環(huán)境變量3. 構(gòu)建第一個(gè)基礎(chǔ)智能體具備工具調(diào)用能力我們從一個(gè)最簡(jiǎn)單的智能體開(kāi)始它能夠使用 Python REPL 工具來(lái)執(zhí)行計(jì)算。3.1 定義工具工具是智能體能力的延伸。我們首先定義一個(gè)計(jì)算器工具它允許智能體執(zhí)行 Python 數(shù)學(xué)表達(dá)式。# tools/calculator_tool.py from langchain.tools import Tool from langchain.utilities import PythonREPL # 創(chuàng)建一個(gè) Python REPL 工具實(shí)例 python_repl PythonREPL() def python_repl_executor(command: str) - str: 執(zhí)行一段 Python 代碼并返回結(jié)果。主要用于數(shù)學(xué)計(jì)算。 try: # 安全考慮可以在這里添加命令白名單或黑名單檢查 # 例如禁止導(dǎo)入 os, subprocess 等模塊 if import os in command or subprocess in command: return Error: For security reasons, this operation is not allowed. result python_repl.run(command) return str(result) except Exception as e: return fError executing code: {e} # 將函數(shù)包裝成 LangChain Tool 對(duì)象 calculator_tool Tool( nameCalculator, funcpython_repl_executor, descriptionUseful for when you need to perform mathematical calculations. Input should be a valid Python expression evaluating to a single number or a simple calculation. Example: 3 * 5 2 or math.sqrt(16) (ensure math is imported). )工具定義要點(diǎn)name: 工具的唯一標(biāo)識(shí)智能體在規(guī)劃時(shí)會(huì)參考這個(gè)名字。func: 工具實(shí)際執(zhí)行的函數(shù)。description: 至關(guān)重要這是告訴大語(yǔ)言模型何時(shí)以及如何使用這個(gè)工具的“說(shuō)明書(shū)”。描述必須清晰、具體包含輸入格式示例。3.2 創(chuàng)建智能體并測(cè)試現(xiàn)在我們創(chuàng)建一個(gè)能夠使用這個(gè)計(jì)算器工具的智能體。# agent_single.py import os from langchain_openai import ChatOpenAI from langchain.agents import initialize_agent, AgentType from langchain.memory import ConversationBufferMemory from tools.calculator_tool import calculator_tool # 初始化 LLM。確保 OPENAI_API_KEY 環(huán)境變量已設(shè)置。 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 給智能體一些記憶讓它能記住對(duì)話上下文 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 定義智能體可以使用的工具列表 tools [calculator_tool] # 初始化智能體 agent initialize_agent( tools, llm, agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION, # 適合對(duì)話且有工具的智能體類型 verboseTrue, # 設(shè)置為 True 可以看到智能體的思考過(guò)程 memorymemory, handle_parsing_errorsTrue # 當(dāng)模型輸出無(wú)法解析為工具調(diào)用時(shí)嘗試處理錯(cuò)誤 ) # 測(cè)試智能體 if __name__ __main__: query 請(qǐng)計(jì)算半徑為 5 的圓的面積用圓周率 3.14 計(jì)算。 print(f用戶: {query}) response agent.invoke({input: query}) print(f智能體: {response[output]})運(yùn)行這個(gè)腳本 (python agent_single.py)你將看到類似以下的輸出其中Thought:、Action:、Observation:展示了智能體的推理鏈 Entering new AgentExecutor chain... Thought: 用戶需要計(jì)算圓的面積。公式是 面積 π * r^2。這里 π 是 3.14r 是 5。 Action: Calculator Action Input: 3.14 * 5 ** 2 Observation: 78.5 Thought: 我計(jì)算出了面積是 78.5。 Final Answer: 半徑為5的圓的面積是78.5。 Finished chain. 用戶: 請(qǐng)計(jì)算半徑為 5 的圓的面積用圓周率 3.14 計(jì)算。 智能體: 半徑為5的圓的面積是78.5。至此一個(gè)具備基礎(chǔ)工具調(diào)用能力的單智能體已經(jīng)構(gòu)建完成。它能夠理解自然語(yǔ)言問(wèn)題規(guī)劃出需要調(diào)用計(jì)算器工具執(zhí)行計(jì)算并給出最終答案。4. 實(shí)現(xiàn)多智能體協(xié)作模擬一個(gè)簡(jiǎn)易任務(wù)分解場(chǎng)景單智能體可以處理明確指令。但復(fù)雜任務(wù)往往需要分工協(xié)作。接下來(lái)我們模擬一個(gè)經(jīng)典場(chǎng)景一個(gè)“規(guī)劃者”智能體負(fù)責(zé)分解任務(wù)一個(gè)“執(zhí)行者”智能體負(fù)責(zé)調(diào)用工具完成子任務(wù)。我們將使用langgraph來(lái)構(gòu)建兩個(gè)智能體之間的協(xié)作工作流。這個(gè)工作流是一個(gè)有向圖節(jié)點(diǎn)代表智能體或函數(shù)邊代表控制流。4.1 定義協(xié)作智能體及其工具假設(shè)我們有兩位專家PlannerAgent規(guī)劃者擅長(zhǎng)分析復(fù)雜問(wèn)題并將其分解為清晰的、可執(zhí)行的步驟序列。它不直接使用工具。ExecutorAgent執(zhí)行者擅長(zhǎng)接收具體指令并調(diào)用合適的工具如計(jì)算器來(lái)完成任務(wù)。# agents/collaborative_agents.py from langchain_openai import ChatOpenAI from langchain.agents import initialize_agent, AgentType from langchain.agents import AgentExecutor from langchain.memory import ConversationBufferMemory from tools.calculator_tool import calculator_tool from langchain_core.messages import HumanMessage, AIMessage from typing import Literal # 初始化共享的 LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.2) # 給規(guī)劃者一點(diǎn)創(chuàng)造性 # 1. 創(chuàng)建執(zhí)行者智能體 (擁有計(jì)算器工具) executor_tools [calculator_tool] executor_memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) executor_agent: AgentExecutor initialize_agent( executor_tools, llm, agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION, verboseFalse, # 在協(xié)作流程中先關(guān)閉詳細(xì)輸出 memoryexecutor_memory, handle_parsing_errorsTrue ) # 2. 創(chuàng)建規(guī)劃者智能體 (沒(méi)有工具純分析) # 規(guī)劃者不需要工具它只需要分析任務(wù)并輸出步驟。 planner_llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.1) # 為規(guī)劃者定義一個(gè)系統(tǒng)提示詞明確其角色和能力 from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder planner_prompt ChatPromptTemplate.from_messages([ (system, 你是一個(gè)任務(wù)規(guī)劃專家。你的職責(zé)是分析用戶提出的復(fù)雜問(wèn)題并將其分解成一個(gè)按順序執(zhí)行的、清晰的步驟列表。 每個(gè)步驟應(yīng)該是一個(gè)具體的、可操作的指令能夠被另一個(gè)擁有計(jì)算工具的智能體直接執(zhí)行。 請(qǐng)只輸出步驟列表每行一個(gè)步驟格式為1. [步驟描述]。不要輸出其他解釋。), MessagesPlaceholder(variable_namemessages), ]) planner_chain planner_prompt | planner_llm4.2 使用 LangGraph 構(gòu)建協(xié)作圖langgraph讓我們可以定義智能體之間的交互邏輯。# workflow/collaboration_workflow.py from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated, List import operator from langchain_core.messages import BaseMessage, HumanMessage, AIMessage from agents.collaborative_agents import executor_agent, planner_chain # 1. 定義圖的狀態(tài)State # 狀態(tài)是所有節(jié)點(diǎn)共享的數(shù)據(jù)結(jié)構(gòu) class AgentState(TypedDict): messages: Annotated[List[BaseMessage], operator.add] # 消息歷史會(huì)自動(dòng)追加 final_answer: str # 存儲(chǔ)最終答案 # 2. 定義節(jié)點(diǎn)函數(shù) def call_planner(state: AgentState): 規(guī)劃者節(jié)點(diǎn)分析最新用戶消息生成步驟列表。 # 獲取最新的用戶消息 last_message state[messages][-1] # 調(diào)用規(guī)劃鏈 plan_result planner_chain.invoke({messages: [last_message]}) # 規(guī)劃結(jié)果是一個(gè) AIMessage其內(nèi)容就是步驟列表 plan_steps plan_result.content # 將規(guī)劃步驟作為一條新的 AI 消息加入歷史 new_ai_message AIMessage(contentf任務(wù)分解如下\n{plan_steps}) return {messages: [new_ai_message]} def call_executor(state: AgentState): 執(zhí)行者節(jié)點(diǎn)根據(jù)規(guī)劃步驟依次執(zhí)行任務(wù)。 messages state[messages] # 找到最新的規(guī)劃消息通常是上一步 call_planner 產(chǎn)生的 plan_message None for msg in reversed(messages): if isinstance(msg, AIMessage) and 任務(wù)分解如下 in msg.content: plan_message msg break if not plan_message: # 如果沒(méi)有找到規(guī)劃直接嘗試回答 result executor_agent.invoke({input: messages[-1].content}) return {messages: [AIMessage(contentresult[output])], final_answer: result[output]} # 解析規(guī)劃步驟這里做簡(jiǎn)化處理實(shí)際可能需要更復(fù)雜的解析 plan_text plan_message.content # 假設(shè)規(guī)劃者輸出的步驟以數(shù)字編號(hào)開(kāi)頭 import re steps re.findall(r\d\.\s*(.?)(?\n\d\.|\n*$), plan_text, re.DOTALL) all_results [] for step in steps: # 對(duì)每個(gè)步驟讓執(zhí)行者智能體去執(zhí)行 # 注意這里需要重置或管理執(zhí)行者的記憶避免步驟間干擾。簡(jiǎn)化處理每次用新輸入。 step_result executor_agent.run(step) # 使用 run 方法它處理字典輸入 all_results.append(f步驟 {step} 的結(jié)果是: {step_result}) final_output 任務(wù)執(zhí)行完畢\n \n.join(all_results) return {messages: [AIMessage(contentfinal_output)], final_answer: final_output} def should_continue(state: AgentState) - Literal[call_executor, END]: 路由函數(shù)決定下一步是去執(zhí)行還是結(jié)束。 messages state[messages] last_message messages[-1] # 如果上一步是規(guī)劃者那么下一步去執(zhí)行 if isinstance(last_message, AIMessage) and 任務(wù)分解如下 in last_message.content: return call_executor # 否則流程結(jié)束 return END # 3. 構(gòu)建圖 workflow StateGraph(AgentState) # 添加節(jié)點(diǎn) workflow.add_node(planner, call_planner) workflow.add_node(executor, call_executor) # 設(shè)置入口點(diǎn) workflow.set_entry_point(planner) # 添加條件邊 workflow.add_conditional_edges( planner, should_continue, { call_executor: executor, END: END } ) workflow.add_edge(executor, END) # 編譯圖 app workflow.compile()4.3 運(yùn)行協(xié)作智能體系統(tǒng)現(xiàn)在我們可以運(yùn)行這個(gè)協(xié)作系統(tǒng)來(lái)處理一個(gè)復(fù)雜查詢。# run_collaboration.py from workflow.collaboration_workflow import app from langchain_core.messages import HumanMessage if __name__ __main__: # 模擬一個(gè)需要多步計(jì)算的問(wèn)題 complex_query 我需要為我的花園規(guī)劃預(yù)算。 首先我需要買草坪。花園是長(zhǎng)方形長(zhǎng)10米寬8米。草坪每平方米50元。 其次我需要買圍欄。只圍長(zhǎng)方形的三條邊兩條寬和一條長(zhǎng)圍欄每米30元。 最后我還想買一些裝飾石每公斤5元我預(yù)計(jì)需要100公斤。 請(qǐng)幫我計(jì)算總花費(fèi)。 print(f用戶問(wèn)題: {complex_query}\n) # 初始化狀態(tài) initial_state { messages: [HumanMessage(contentcomplex_query)], final_answer: } # 運(yùn)行圖應(yīng)用 final_state app.invoke(initial_state) print(*50) print(協(xié)作過(guò)程摘要:) for msg in final_state[messages]: role 用戶 if isinstance(msg, HumanMessage) else 智能體 print(f[{role}]: {msg.content[:200]}...) # 截?cái)囡@示 print(\n *50) print(最終答案:) print(final_state[final_answer])運(yùn)行此腳本你將觀察到兩個(gè)智能體的協(xié)作過(guò)程。規(guī)劃者首先將問(wèn)題分解為計(jì)算草坪面積費(fèi)用、圍欄長(zhǎng)度費(fèi)用、裝飾石費(fèi)用以及求和的步驟。然后執(zhí)行者依次調(diào)用計(jì)算器工具完成每一步計(jì)算并匯總結(jié)果。雖然這個(gè)例子比較簡(jiǎn)單但它清晰地展示了任務(wù)分解與執(zhí)行的協(xié)作范式。5. 關(guān)鍵配置、參數(shù)詳解與常見(jiàn)問(wèn)題排查構(gòu)建和運(yùn)行智能體時(shí)配置和參數(shù)的理解至關(guān)重要它們直接影響智能體的行為和性能。5.1 核心參數(shù)解析以下表格列出了在初始化智能體時(shí)最關(guān)鍵的幾個(gè)參數(shù)參數(shù)所屬對(duì)象含義與影響推薦值/建議modelChatOpenAI指定使用的基礎(chǔ)大語(yǔ)言模型。不同模型在推理能力、成本、速度上差異巨大。gpt-3.5-turbo性價(jià)比高gpt-4/gpt-4-turbo更強(qiáng)推理成本高。temperatureChatOpenAI控制輸出的隨機(jī)性。值越高接近1回答越多樣、有創(chuàng)造性值越低接近0回答越確定、一致。規(guī)劃任務(wù)0.1-0.3保持穩(wěn)定。創(chuàng)意任務(wù)0.7-0.9。工具調(diào)用建議 0-0.2確保可靠性。agentinitialize_agent智能體的類型決定了其推理和調(diào)用工具的策略。CONVERSATIONAL_REACT_DESCRIPTION適合多輪對(duì)話且需工具的場(chǎng)景。ZERO_SHOT_REACT_DESCRIPTION適合單輪任務(wù)。OPENAI_FUNCTIONS使用 OpenAI 的 Function Calling 特性更穩(wěn)定。verboseinitialize_agent是否打印詳細(xì)的推理鏈Thought/Action/Observation。開(kāi)發(fā)調(diào)試時(shí)設(shè)為True生產(chǎn)環(huán)境設(shè)為False。handle_parsing_errorsinitialize_agent當(dāng)模型輸出無(wú)法被解析為有效的工具調(diào)用時(shí)是否嘗試處理。建議設(shè)為True并配合自定義錯(cuò)誤處理函數(shù)避免智能體因格式錯(cuò)誤而崩潰。max_iterationsAgentExecutor(可通過(guò)agent_kwargs傳入)智能體執(zhí)行的最大循環(huán)次數(shù)防止陷入死循環(huán)。根據(jù)任務(wù)復(fù)雜度設(shè)置通常 5-10。簡(jiǎn)單任務(wù)可設(shè) 3。memoryinitialize_agent為智能體提供對(duì)話記憶。ConversationBufferMemory存儲(chǔ)所有歷史。ConversationSummaryMemory存儲(chǔ)摘要節(jié)省 token。根據(jù)上下文長(zhǎng)度選擇。5.2 常見(jiàn)問(wèn)題與排查路徑在開(kāi)發(fā)智能體時(shí)你可能會(huì)遇到以下典型問(wèn)題問(wèn)題現(xiàn)象可能原因檢查與解決步驟智能體不調(diào)用工具直接回答1. 工具描述不清晰。2. 問(wèn)題描述太簡(jiǎn)單模型認(rèn)為無(wú)需工具。3. Agent 類型選擇不當(dāng)。1.檢查工具描述確保description字段清晰說(shuō)明了工具的用途、輸入格式和示例。2.調(diào)整問(wèn)題提示在用戶問(wèn)題中明確要求“請(qǐng)使用計(jì)算器”或“請(qǐng)分步計(jì)算”。3.嘗試OPENAI_FUNCTIONSAgent它對(duì)工具調(diào)用的支持更魯棒。工具調(diào)用格式錯(cuò)誤Parsing error模型輸出不符合 LangChain 的解析期望。1. 設(shè)置handle_parsing_errorsTrue。2. 將verbose設(shè)為True查看模型的原始輸出檢查其格式。3. 考慮使用OpenAIFunctionsAgent它利用 OpenAI 官方的 function calling格式更穩(wěn)定。智能體陷入循環(huán)重復(fù)調(diào)用同一工具1. 工具返回的結(jié)果未能讓智能體滿足停止條件。2.max_iterations設(shè)置過(guò)高。1.檢查工具輸出確保工具返回了清晰、完整的結(jié)果。2.降低max_iterations設(shè)為 3 或 5觀察是否在合理步驟內(nèi)完成。3.優(yōu)化系統(tǒng)提示詞在提示詞中明確告訴智能體“在得到最終答案后必須立即停止”。多智能體協(xié)作時(shí)上下文混亂每個(gè)智能體的記憶Memory沒(méi)有正確隔離或重置。1.為每個(gè)智能體實(shí)例分配獨(dú)立的memory對(duì)象避免記憶串?dāng)_。2.在協(xié)作工作流中考慮顯式地傳遞和裁剪消息歷史而不是完全依賴內(nèi)存對(duì)象。3. 使用langgraph的狀態(tài)管理來(lái)精確控制消息流。API 調(diào)用超時(shí)或速率限制1. 網(wǎng)絡(luò)問(wèn)題。2. OpenAI API 達(dá)到速率限制。3. 智能體循環(huán)次數(shù)太多導(dǎo)致總 token 消耗大、耗時(shí)長(zhǎng)。1.增加超時(shí)設(shè)置在ChatOpenAI初始化時(shí)傳入request_timeout30。2.實(shí)現(xiàn)重試邏輯使用tenacity庫(kù)或 LangChain 內(nèi)置的Retry回調(diào)。3.監(jiān)控 token 使用在verbose模式下可估算或使用 OpenAI 官方 dashboard?！癘penAI API 密鑰無(wú)效”錯(cuò)誤1. 環(huán)境變量未正確加載。2. 密鑰本身無(wú)效或過(guò)期。3. 賬戶余額不足。1.驗(yàn)證環(huán)境變量在 Python 中print(os.getenv(‘OPENAI_API_KEY’))檢查。2.在 OpenAI 平臺(tái)檢查密鑰狀態(tài)和余額。3. 確保代碼中沒(méi)有硬編碼錯(cuò)誤的密鑰。5.3 安全與生產(chǎn)環(huán)境最佳實(shí)踐將智能體從學(xué)習(xí)環(huán)境推向生產(chǎn)環(huán)境需要考慮更多因素工具安全性像PythonREPL這樣的工具非常強(qiáng)大但也極其危險(xiǎn)。在生產(chǎn)環(huán)境中必須嚴(yán)格限制其可執(zhí)行的操作。可以使用沙箱環(huán)境如Docker容器來(lái)運(yùn)行不受信任的代碼。在工具函數(shù)內(nèi)部實(shí)現(xiàn)命令白名單或黑名單過(guò)濾。考慮使用更安全的替代品如專門用于數(shù)學(xué)計(jì)算的庫(kù)numexpr或受限的 DSL領(lǐng)域特定語(yǔ)言。成本控制設(shè)置max_tokens限制防止生成過(guò)長(zhǎng)的內(nèi)容。使用ConversationSummaryMemory或ConversationBufferWindowMemory來(lái)限制保存的歷史消息長(zhǎng)度減少 token 消耗。對(duì)非關(guān)鍵任務(wù)優(yōu)先使用gpt-3.5-turbo模型。錯(cuò)誤處理與降級(jí)用try...except包裹智能體的invoke調(diào)用。當(dāng)智能體失敗時(shí)提供友好的用戶提示或 fallback 到更簡(jiǎn)單的流程。記錄詳細(xì)的日志包括用戶輸入、智能體的思考過(guò)程、工具調(diào)用和最終輸出便于事后分析和優(yōu)化。配置外置化將模型名稱、API Base URL、溫度等參數(shù)放在配置文件如config.yaml或環(huán)境變量中。避免在代碼中硬編碼任何敏感信息或環(huán)境特定的配置。6. 擴(kuò)展方向與下一步學(xué)習(xí)建議通過(guò)本文的實(shí)踐你已經(jīng)掌握了構(gòu)建基礎(chǔ)單智能體和簡(jiǎn)單多智能體協(xié)作系統(tǒng)的方法。要深入智能體開(kāi)發(fā)可以從以下幾個(gè)方向繼續(xù)探索集成更豐富的工具智能體的能力取決于其工具集。嘗試集成網(wǎng)絡(luò)搜索使用SerpAPI或DuckDuckGoSearch工具讓智能體獲取實(shí)時(shí)信息。數(shù)據(jù)庫(kù)查詢集成SQLDatabaseToolkit讓智能體能查詢業(yè)務(wù)數(shù)據(jù)。代碼執(zhí)行與文件操作在嚴(yán)格的安全約束下讓智能體能編寫并運(yùn)行代碼片段或讀寫特定文件。探索更復(fù)雜的協(xié)作模式本文的“規(guī)劃-執(zhí)行”只是最簡(jiǎn)單的一種。研究以下模式辯論模式讓多個(gè)智能體就一個(gè)問(wèn)題提出不同觀點(diǎn)最終達(dá)成共識(shí)。評(píng)審模式一個(gè)智能體生成內(nèi)容另一個(gè)智能體負(fù)責(zé)評(píng)審和提出修改意見(jiàn)。分層管理一個(gè)“經(jīng)理”智能體接收任務(wù)分配給多個(gè)“員工”智能體并匯總結(jié)果。使用可視化平臺(tái)加速開(kāi)發(fā)對(duì)于復(fù)雜的工作流使用Dify或LangFlow這類可視化工具進(jìn)行編排和調(diào)試可以極大提升效率。你可以在這些平臺(tái)上設(shè)計(jì)節(jié)點(diǎn)和連接再導(dǎo)出為代碼。深入提示詞工程智能體的表現(xiàn)很大程度上受系統(tǒng)提示詞System Prompt影響。學(xué)習(xí)如何為不同角色規(guī)劃者、執(zhí)行者、評(píng)審者編寫清晰、具體、有約束力的提示詞是提升智能體性能的關(guān)鍵。關(guān)注智能體評(píng)估如何衡量一個(gè)智能體系統(tǒng)的優(yōu)劣建立評(píng)估體系包括任務(wù)完成率、步驟合理性、工具調(diào)用準(zhǔn)確率、耗時(shí)和成本等指標(biāo)并以此為導(dǎo)向進(jìn)行迭代優(yōu)化。智能體開(kāi)發(fā)是一個(gè)快速演進(jìn)的領(lǐng)域核心在于理解“感知-規(guī)劃-行動(dòng)-反思”這一范式并熟練運(yùn)用 LangChain 等框架將其工程化落地。從解決一個(gè)具體的、小的自動(dòng)化任務(wù)開(kāi)始逐步增加其復(fù)雜性和協(xié)作性是學(xué)習(xí)這門技術(shù)最有效的路徑。 從零構(gòu)建AI智能體：核心概念、框架選型與多智能體協(xié)作實(shí)戰(zhàn)
在實(shí)際 AI 應(yīng)用開(kāi)發(fā)中我們經(jīng)常聽(tīng)到“智能體”這個(gè)概念但很多開(kāi)發(fā)者對(duì)它的理解停留在“能調(diào)用 API 的聊天機(jī)器人”層面。最近OpenAI 展示的智能體互聊視頻以及圍繞 Astra AI、Codex、Dify、LangChain 等工具的熱議揭示了一個(gè)更核心的趨勢(shì)智能體正在從簡(jiǎn)單的問(wèn)答工具演變?yōu)槟軌蜃灾饕?guī)劃、使用工具、相互協(xié)作的“數(shù)字員工”。對(duì)于前端、后端或全棧開(kāi)發(fā)者而言理解并實(shí)踐智能體開(kāi)發(fā)不再是錦上添花而是構(gòu)建下一代人機(jī)協(xié)同應(yīng)用的關(guān)鍵能力。本文將從工程實(shí)踐角度為你拆解智能體的核心概念、主流框架、搭建方法并提供一個(gè)從零開(kāi)始構(gòu)建可協(xié)作智能體的完整教程讓你不僅能看懂演示視頻更能親手實(shí)現(xiàn)一個(gè)具備基礎(chǔ)協(xié)作能力的智能體系統(tǒng)。1. 理解智能體從 API 調(diào)用者到自主行動(dòng)者在討論具體代碼之前我們必須先厘清“智能體”在技術(shù)語(yǔ)境下的真實(shí)含義。這決定了我們后續(xù)選擇何種框架、設(shè)計(jì)何種架構(gòu)。1.1 智能體的核心能力與工作流一個(gè)真正的智能體Agent不僅僅是封裝了 OpenAI API 的客戶端。它是一個(gè)具備感知、規(guī)劃、行動(dòng)和反思能力的軟件實(shí)體。其典型工作流可以概括為以下循環(huán)感知接收來(lái)自用戶、環(huán)境或其他智能體的輸入文本、指令、數(shù)據(jù)。規(guī)劃基于目標(biāo)分解任務(wù)決定下一步該調(diào)用哪個(gè)工具或執(zhí)行什么操作。行動(dòng)執(zhí)行規(guī)劃好的步驟例如調(diào)用一個(gè)函數(shù)、查詢數(shù)據(jù)庫(kù)、運(yùn)行一段代碼。反思評(píng)估行動(dòng)結(jié)果判斷是否達(dá)成目標(biāo)或是否需要調(diào)整策略。這個(gè)循環(huán)的核心是“工具使用”能力。智能體通過(guò)調(diào)用預(yù)先定義好的工具如搜索引擎、計(jì)算器、代碼執(zhí)行器、API接口來(lái)擴(kuò)展其能力邊界而不僅僅依賴于大語(yǔ)言模型本身的知識(shí)生成。1.2 主流智能體框架與選型建議當(dāng)前社區(qū)有多個(gè)成熟的智能體開(kāi)發(fā)框架它們抽象了上述工作流讓開(kāi)發(fā)者能更專注于業(yè)務(wù)邏輯。以下是幾個(gè)主流框架的對(duì)比框架名稱核心特點(diǎn)適用場(chǎng)景學(xué)習(xí)曲線LangChain生態(tài)最豐富模塊化設(shè)計(jì)支持多種模型和工具鏈。社區(qū)活躍文檔詳盡。復(fù)雜、定制化要求高的智能體應(yīng)用需要集成多種數(shù)據(jù)源和工具。中等偏上概念較多。Dify開(kāi)箱即用提供可視化編排界面。強(qiáng)調(diào)“工作流”和“應(yīng)用”的概念降低編碼門檻。快速構(gòu)建和部署 AI 應(yīng)用特別是面向非技術(shù)用戶或需要快速原型驗(yàn)證的場(chǎng)景。較低界面友好。Microsoft Autogen專注于多智能體協(xié)作內(nèi)置了多種智能體角色和對(duì)話模式便于構(gòu)建對(duì)話系統(tǒng)。需要多個(gè)智能體相互對(duì)話、協(xié)作完成任務(wù)的研究或應(yīng)用場(chǎng)景。中等需要理解其代理架構(gòu)。CrewAI建立在 LangChain 之上更強(qiáng)調(diào)角色扮演和任務(wù)分工適合模擬團(tuán)隊(duì)協(xié)作。需要模擬銷售、客服、研發(fā)等不同角色協(xié)同工作的場(chǎng)景。中等概念清晰。對(duì)于初學(xué)者或希望快速看到效果的開(kāi)發(fā)者從Dify或CrewAI入手是不錯(cuò)的選擇。如果你需要深度定制和控制每一個(gè)環(huán)節(jié)LangChain是更強(qiáng)大的基礎(chǔ)。而本文為了深入理解智能體協(xié)作的機(jī)制我們將以LangChain為基礎(chǔ)結(jié)合其多智能體協(xié)作擴(kuò)展來(lái)構(gòu)建一個(gè)簡(jiǎn)易的協(xié)作場(chǎng)景。2. 環(huán)境準(zhǔn)備與項(xiàng)目初始化在開(kāi)始編碼前我們需要一個(gè)干凈的 Python 環(huán)境。這里假設(shè)你已安裝 Python 3.8 和 pip。2.1 創(chuàng)建虛擬環(huán)境與安裝依賴強(qiáng)烈建議使用虛擬環(huán)境來(lái)管理依賴避免包沖突。# 創(chuàng)建項(xiàng)目目錄并進(jìn)入 mkdir collaborative-agents-demo cd collaborative-agents-demo # 創(chuàng)建虛擬環(huán)境以 venv 為例 python -m venv venv # 激活虛擬環(huán)境 # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 安裝核心依賴 pip install langchain langchain-openai langchain-community langgraph關(guān)鍵依賴說(shuō)明langchain: 智能體開(kāi)發(fā)的核心框架。langchain-openai: 官方維護(hù)的 OpenAI 模型集成。langchain-community: 社區(qū)貢獻(xiàn)的大量第三方工具和集成。langgraph: LangChain 用于構(gòu)建有狀態(tài)、多步驟工作流如圖的庫(kù)是實(shí)現(xiàn)多智能體協(xié)作循環(huán)的關(guān)鍵。2.2 配置 OpenAI API 密鑰智能體需要“大腦”我們使用 OpenAI 的模型如 gpt-3.5-turbo。你需要一個(gè)有效的 OpenAI API Key。安全提示永遠(yuǎn)不要將 API Key 硬編碼在代碼中或提交到版本控制系統(tǒng)。推薦使用環(huán)境變量管理# Linux/Mac export OPENAI_API_KEY你的-api-key-here # Windows (PowerShell) $env:OPENAI_API_KEY你的-api-key-here或者在項(xiàng)目根目錄創(chuàng)建一個(gè).env文件確保該文件在.gitignore中OPENAI_API_KEY你的-api-key-here然后在 Python 代碼中使用python-dotenv加載需額外安裝pip install python-dotenvfrom dotenv import load_dotenv load_dotenv() # 這會(huì)加載 .env 文件中的環(huán)境變量3. 構(gòu)建第一個(gè)基礎(chǔ)智能體具備工具調(diào)用能力我們從一個(gè)最簡(jiǎn)單的智能體開(kāi)始它能夠使用 Python REPL 工具來(lái)執(zhí)行計(jì)算。3.1 定義工具工具是智能體能力的延伸。我們首先定義一個(gè)計(jì)算器工具它允許智能體執(zhí)行 Python 數(shù)學(xué)表達(dá)式。# tools/calculator_tool.py from langchain.tools import Tool from langchain.utilities import PythonREPL # 創(chuàng)建一個(gè) Python REPL 工具實(shí)例 python_repl PythonREPL() def python_repl_executor(command: str) - str: 執(zhí)行一段 Python 代碼并返回結(jié)果。主要用于數(shù)學(xué)計(jì)算。 try: # 安全考慮可以在這里添加命令白名單或黑名單檢查 # 例如禁止導(dǎo)入 os, subprocess 等模塊 if import os in command or subprocess in command: return Error: For security reasons, this operation is not allowed. result python_repl.run(command) return str(result) except Exception as e: return fError executing code: {e} # 將函數(shù)包裝成 LangChain Tool 對(duì)象 calculator_tool Tool( nameCalculator, funcpython_repl_executor, descriptionUseful for when you need to perform mathematical calculations. Input should be a valid Python expression evaluating to a single number or a simple calculation. Example: 3 * 5 2 or math.sqrt(16) (ensure math is imported). )工具定義要點(diǎn)name: 工具的唯一標(biāo)識(shí)智能體在規(guī)劃時(shí)會(huì)參考這個(gè)名字。func: 工具實(shí)際執(zhí)行的函數(shù)。description: 至關(guān)重要這是告訴大語(yǔ)言模型何時(shí)以及如何使用這個(gè)工具的“說(shuō)明書(shū)”。描述必須清晰、具體包含輸入格式示例。3.2 創(chuàng)建智能體并測(cè)試現(xiàn)在我們創(chuàng)建一個(gè)能夠使用這個(gè)計(jì)算器工具的智能體。# agent_single.py import os from langchain_openai import ChatOpenAI from langchain.agents import initialize_agent, AgentType from langchain.memory import ConversationBufferMemory from tools.calculator_tool import calculator_tool # 初始化 LLM。確保 OPENAI_API_KEY 環(huán)境變量已設(shè)置。 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 給智能體一些記憶讓它能記住對(duì)話上下文 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 定義智能體可以使用的工具列表 tools [calculator_tool] # 初始化智能體 agent initialize_agent( tools, llm, agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION, # 適合對(duì)話且有工具的智能體類型 verboseTrue, # 設(shè)置為 True 可以看到智能體的思考過(guò)程 memorymemory, handle_parsing_errorsTrue # 當(dāng)模型輸出無(wú)法解析為工具調(diào)用時(shí)嘗試處理錯(cuò)誤 ) # 測(cè)試智能體 if __name__ __main__: query 請(qǐng)計(jì)算半徑為 5 的圓的面積用圓周率 3.14 計(jì)算。 print(f用戶: {query}) response agent.invoke({input: query}) print(f智能體: {response[output]})運(yùn)行這個(gè)腳本 (python agent_single.py)你將看到類似以下的輸出其中Thought:、Action:、Observation:展示了智能體的推理鏈 Entering new AgentExecutor chain... Thought: 用戶需要計(jì)算圓的面積。公式是 面積 π * r^2。這里 π 是 3.14r 是 5。 Action: Calculator Action Input: 3.14 * 5 ** 2 Observation: 78.5 Thought: 我計(jì)算出了面積是 78.5。 Final Answer: 半徑為5的圓的面積是78.5。 Finished chain. 用戶: 請(qǐng)計(jì)算半徑為 5 的圓的面積用圓周率 3.14 計(jì)算。 智能體: 半徑為5的圓的面積是78.5。至此一個(gè)具備基礎(chǔ)工具調(diào)用能力的單智能體已經(jīng)構(gòu)建完成。它能夠理解自然語(yǔ)言問(wèn)題規(guī)劃出需要調(diào)用計(jì)算器工具執(zhí)行計(jì)算并給出最終答案。4. 實(shí)現(xiàn)多智能體協(xié)作模擬一個(gè)簡(jiǎn)易任務(wù)分解場(chǎng)景單智能體可以處理明確指令。但復(fù)雜任務(wù)往往需要分工協(xié)作。接下來(lái)我們模擬一個(gè)經(jīng)典場(chǎng)景一個(gè)“規(guī)劃者”智能體負(fù)責(zé)分解任務(wù)一個(gè)“執(zhí)行者”智能體負(fù)責(zé)調(diào)用工具完成子任務(wù)。我們將使用langgraph來(lái)構(gòu)建兩個(gè)智能體之間的協(xié)作工作流。這個(gè)工作流是一個(gè)有向圖節(jié)點(diǎn)代表智能體或函數(shù)邊代表控制流。4.1 定義協(xié)作智能體及其工具假設(shè)我們有兩位專家PlannerAgent規(guī)劃者擅長(zhǎng)分析復(fù)雜問(wèn)題并將其分解為清晰的、可執(zhí)行的步驟序列。它不直接使用工具。ExecutorAgent執(zhí)行者擅長(zhǎng)接收具體指令并調(diào)用合適的工具如計(jì)算器來(lái)完成任務(wù)。# agents/collaborative_agents.py from langchain_openai import ChatOpenAI from langchain.agents import initialize_agent, AgentType from langchain.agents import AgentExecutor from langchain.memory import ConversationBufferMemory from tools.calculator_tool import calculator_tool from langchain_core.messages import HumanMessage, AIMessage from typing import Literal # 初始化共享的 LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.2) # 給規(guī)劃者一點(diǎn)創(chuàng)造性 # 1. 創(chuàng)建執(zhí)行者智能體 (擁有計(jì)算器工具) executor_tools [calculator_tool] executor_memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) executor_agent: AgentExecutor initialize_agent( executor_tools, llm, agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION, verboseFalse, # 在協(xié)作流程中先關(guān)閉詳細(xì)輸出 memoryexecutor_memory, handle_parsing_errorsTrue ) # 2. 創(chuàng)建規(guī)劃者智能體 (沒(méi)有工具純分析) # 規(guī)劃者不需要工具它只需要分析任務(wù)并輸出步驟。 planner_llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.1) # 為規(guī)劃者定義一個(gè)系統(tǒng)提示詞明確其角色和能力 from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder planner_prompt ChatPromptTemplate.from_messages([ (system, 你是一個(gè)任務(wù)規(guī)劃專家。你的職責(zé)是分析用戶提出的復(fù)雜問(wèn)題并將其分解成一個(gè)按順序執(zhí)行的、清晰的步驟列表。 每個(gè)步驟應(yīng)該是一個(gè)具體的、可操作的指令能夠被另一個(gè)擁有計(jì)算工具的智能體直接執(zhí)行。 請(qǐng)只輸出步驟列表每行一個(gè)步驟格式為1. [步驟描述]。不要輸出其他解釋。), MessagesPlaceholder(variable_namemessages), ]) planner_chain planner_prompt | planner_llm4.2 使用 LangGraph 構(gòu)建協(xié)作圖langgraph讓我們可以定義智能體之間的交互邏輯。# workflow/collaboration_workflow.py from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated, List import operator from langchain_core.messages import BaseMessage, HumanMessage, AIMessage from agents.collaborative_agents import executor_agent, planner_chain # 1. 定義圖的狀態(tài)State # 狀態(tài)是所有節(jié)點(diǎn)共享的數(shù)據(jù)結(jié)構(gòu) class AgentState(TypedDict): messages: Annotated[List[BaseMessage], operator.add] # 消息歷史會(huì)自動(dòng)追加 final_answer: str # 存儲(chǔ)最終答案 # 2. 定義節(jié)點(diǎn)函數(shù) def call_planner(state: AgentState): 規(guī)劃者節(jié)點(diǎn)分析最新用戶消息生成步驟列表。 # 獲取最新的用戶消息 last_message state[messages][-1] # 調(diào)用規(guī)劃鏈 plan_result planner_chain.invoke({messages: [last_message]}) # 規(guī)劃結(jié)果是一個(gè) AIMessage其內(nèi)容就是步驟列表 plan_steps plan_result.content # 將規(guī)劃步驟作為一條新的 AI 消息加入歷史 new_ai_message AIMessage(contentf任務(wù)分解如下\n{plan_steps}) return {messages: [new_ai_message]} def call_executor(state: AgentState): 執(zhí)行者節(jié)點(diǎn)根據(jù)規(guī)劃步驟依次執(zhí)行任務(wù)。 messages state[messages] # 找到最新的規(guī)劃消息通常是上一步 call_planner 產(chǎn)生的 plan_message None for msg in reversed(messages): if isinstance(msg, AIMessage) and 任務(wù)分解如下 in msg.content: plan_message msg break if not plan_message: # 如果沒(méi)有找到規(guī)劃直接嘗試回答 result executor_agent.invoke({input: messages[-1].content}) return {messages: [AIMessage(contentresult[output])], final_answer: result[output]} # 解析規(guī)劃步驟這里做簡(jiǎn)化處理實(shí)際可能需要更復(fù)雜的解析 plan_text plan_message.content # 假設(shè)規(guī)劃者輸出的步驟以數(shù)字編號(hào)開(kāi)頭 import re steps re.findall(r\d\.\s*(.?)(?\n\d\.|\n*$), plan_text, re.DOTALL) all_results [] for step in steps: # 對(duì)每個(gè)步驟讓執(zhí)行者智能體去執(zhí)行 # 注意這里需要重置或管理執(zhí)行者的記憶避免步驟間干擾。簡(jiǎn)化處理每次用新輸入。 step_result executor_agent.run(step) # 使用 run 方法它處理字典輸入 all_results.append(f步驟 {step} 的結(jié)果是: {step_result}) final_output 任務(wù)執(zhí)行完畢\n \n.join(all_results) return {messages: [AIMessage(contentfinal_output)], final_answer: final_output} def should_continue(state: AgentState) - Literal[call_executor, END]: 路由函數(shù)決定下一步是去執(zhí)行還是結(jié)束。 messages state[messages] last_message messages[-1] # 如果上一步是規(guī)劃者那么下一步去執(zhí)行 if isinstance(last_message, AIMessage) and 任務(wù)分解如下 in last_message.content: return call_executor # 否則流程結(jié)束 return END # 3. 構(gòu)建圖 workflow StateGraph(AgentState) # 添加節(jié)點(diǎn) workflow.add_node(planner, call_planner) workflow.add_node(executor, call_executor) # 設(shè)置入口點(diǎn) workflow.set_entry_point(planner) # 添加條件邊 workflow.add_conditional_edges( planner, should_continue, { call_executor: executor, END: END } ) workflow.add_edge(executor, END) # 編譯圖 app workflow.compile()4.3 運(yùn)行協(xié)作智能體系統(tǒng)現(xiàn)在我們可以運(yùn)行這個(gè)協(xié)作系統(tǒng)來(lái)處理一個(gè)復(fù)雜查詢。# run_collaboration.py from workflow.collaboration_workflow import app from langchain_core.messages import HumanMessage if __name__ __main__: # 模擬一個(gè)需要多步計(jì)算的問(wèn)題 complex_query 我需要為我的花園規(guī)劃預(yù)算。 首先我需要買草坪。花園是長(zhǎng)方形長(zhǎng)10米寬8米。草坪每平方米50元。 其次我需要買圍欄。只圍長(zhǎng)方形的三條邊兩條寬和一條長(zhǎng)圍欄每米30元。 最后我還想買一些裝飾石每公斤5元我預(yù)計(jì)需要100公斤。 請(qǐng)幫我計(jì)算總花費(fèi)。 print(f用戶問(wèn)題: {complex_query}\n) # 初始化狀態(tài) initial_state { messages: [HumanMessage(contentcomplex_query)], final_answer: } # 運(yùn)行圖應(yīng)用 final_state app.invoke(initial_state) print(*50) print(協(xié)作過(guò)程摘要:) for msg in final_state[messages]: role 用戶 if isinstance(msg, HumanMessage) else 智能體 print(f[{role}]: {msg.content[:200]}...) # 截?cái)囡@示 print(\n *50) print(最終答案:) print(final_state[final_answer])運(yùn)行此腳本你將觀察到兩個(gè)智能體的協(xié)作過(guò)程。規(guī)劃者首先將問(wèn)題分解為計(jì)算草坪面積費(fèi)用、圍欄長(zhǎng)度費(fèi)用、裝飾石費(fèi)用以及求和的步驟。然后執(zhí)行者依次調(diào)用計(jì)算器工具完成每一步計(jì)算并匯總結(jié)果。雖然這個(gè)例子比較簡(jiǎn)單但它清晰地展示了任務(wù)分解與執(zhí)行的協(xié)作范式。5. 關(guān)鍵配置、參數(shù)詳解與常見(jiàn)問(wèn)題排查構(gòu)建和運(yùn)行智能體時(shí)配置和參數(shù)的理解至關(guān)重要它們直接影響智能體的行為和性能。5.1 核心參數(shù)解析以下表格列出了在初始化智能體時(shí)最關(guān)鍵的幾個(gè)參數(shù)參數(shù)所屬對(duì)象含義與影響推薦值/建議modelChatOpenAI指定使用的基礎(chǔ)大語(yǔ)言模型。不同模型在推理能力、成本、速度上差異巨大。gpt-3.5-turbo性價(jià)比高gpt-4/gpt-4-turbo更強(qiáng)推理成本高。temperatureChatOpenAI控制輸出的隨機(jī)性。值越高接近1回答越多樣、有創(chuàng)造性值越低接近0回答越確定、一致。規(guī)劃任務(wù)0.1-0.3保持穩(wěn)定。創(chuàng)意任務(wù)0.7-0.9。工具調(diào)用建議 0-0.2確保可靠性。agentinitialize_agent智能體的類型決定了其推理和調(diào)用工具的策略。CONVERSATIONAL_REACT_DESCRIPTION適合多輪對(duì)話且需工具的場(chǎng)景。ZERO_SHOT_REACT_DESCRIPTION適合單輪任務(wù)。OPENAI_FUNCTIONS使用 OpenAI 的 Function Calling 特性更穩(wěn)定。verboseinitialize_agent是否打印詳細(xì)的推理鏈Thought/Action/Observation。開(kāi)發(fā)調(diào)試時(shí)設(shè)為True生產(chǎn)環(huán)境設(shè)為False。handle_parsing_errorsinitialize_agent當(dāng)模型輸出無(wú)法被解析為有效的工具調(diào)用時(shí)是否嘗試處理。建議設(shè)為True并配合自定義錯(cuò)誤處理函數(shù)避免智能體因格式錯(cuò)誤而崩潰。max_iterationsAgentExecutor(可通過(guò)agent_kwargs傳入)智能體執(zhí)行的最大循環(huán)次數(shù)防止陷入死循環(huán)。根據(jù)任務(wù)復(fù)雜度設(shè)置通常 5-10。簡(jiǎn)單任務(wù)可設(shè) 3。memoryinitialize_agent為智能體提供對(duì)話記憶。ConversationBufferMemory存儲(chǔ)所有歷史。ConversationSummaryMemory存儲(chǔ)摘要節(jié)省 token。根據(jù)上下文長(zhǎng)度選擇。5.2 常見(jiàn)問(wèn)題與排查路徑在開(kāi)發(fā)智能體時(shí)你可能會(huì)遇到以下典型問(wèn)題問(wèn)題現(xiàn)象可能原因檢查與解決步驟智能體不調(diào)用工具直接回答1. 工具描述不清晰。2. 問(wèn)題描述太簡(jiǎn)單模型認(rèn)為無(wú)需工具。3. Agent 類型選擇不當(dāng)。1.檢查工具描述確保description字段清晰說(shuō)明了工具的用途、輸入格式和示例。2.調(diào)整問(wèn)題提示在用戶問(wèn)題中明確要求“請(qǐng)使用計(jì)算器”或“請(qǐng)分步計(jì)算”。3.嘗試OPENAI_FUNCTIONSAgent它對(duì)工具調(diào)用的支持更魯棒。工具調(diào)用格式錯(cuò)誤Parsing error模型輸出不符合 LangChain 的解析期望。1. 設(shè)置handle_parsing_errorsTrue。2. 將verbose設(shè)為True查看模型的原始輸出檢查其格式。3. 考慮使用OpenAIFunctionsAgent它利用 OpenAI 官方的 function calling格式更穩(wěn)定。智能體陷入循環(huán)重復(fù)調(diào)用同一工具1. 工具返回的結(jié)果未能讓智能體滿足停止條件。2.max_iterations設(shè)置過(guò)高。1.檢查工具輸出確保工具返回了清晰、完整的結(jié)果。2.降低max_iterations設(shè)為 3 或 5觀察是否在合理步驟內(nèi)完成。3.優(yōu)化系統(tǒng)提示詞在提示詞中明確告訴智能體“在得到最終答案后必須立即停止”。多智能體協(xié)作時(shí)上下文混亂每個(gè)智能體的記憶Memory沒(méi)有正確隔離或重置。1.為每個(gè)智能體實(shí)例分配獨(dú)立的memory對(duì)象避免記憶串?dāng)_。2.在協(xié)作工作流中考慮顯式地傳遞和裁剪消息歷史而不是完全依賴內(nèi)存對(duì)象。3. 使用langgraph的狀態(tài)管理來(lái)精確控制消息流。API 調(diào)用超時(shí)或速率限制1. 網(wǎng)絡(luò)問(wèn)題。2. OpenAI API 達(dá)到速率限制。3. 智能體循環(huán)次數(shù)太多導(dǎo)致總 token 消耗大、耗時(shí)長(zhǎng)。1.增加超時(shí)設(shè)置在ChatOpenAI初始化時(shí)傳入request_timeout30。2.實(shí)現(xiàn)重試邏輯使用tenacity庫(kù)或 LangChain 內(nèi)置的Retry回調(diào)。3.監(jiān)控 token 使用在verbose模式下可估算或使用 OpenAI 官方 dashboard?！癘penAI API 密鑰無(wú)效”錯(cuò)誤1. 環(huán)境變量未正確加載。2. 密鑰本身無(wú)效或過(guò)期。3. 賬戶余額不足。1.驗(yàn)證環(huán)境變量在 Python 中print(os.getenv(‘OPENAI_API_KEY’))檢查。2.在 OpenAI 平臺(tái)檢查密鑰狀態(tài)和余額。3. 確保代碼中沒(méi)有硬編碼錯(cuò)誤的密鑰。5.3 安全與生產(chǎn)環(huán)境最佳實(shí)踐將智能體從學(xué)習(xí)環(huán)境推向生產(chǎn)環(huán)境需要考慮更多因素工具安全性像PythonREPL這樣的工具非常強(qiáng)大但也極其危險(xiǎn)。在生產(chǎn)環(huán)境中必須嚴(yán)格限制其可執(zhí)行的操作。可以使用沙箱環(huán)境如Docker容器來(lái)運(yùn)行不受信任的代碼。在工具函數(shù)內(nèi)部實(shí)現(xiàn)命令白名單或黑名單過(guò)濾。考慮使用更安全的替代品如專門用于數(shù)學(xué)計(jì)算的庫(kù)numexpr或受限的 DSL領(lǐng)域特定語(yǔ)言。成本控制設(shè)置max_tokens限制防止生成過(guò)長(zhǎng)的內(nèi)容。使用ConversationSummaryMemory或ConversationBufferWindowMemory來(lái)限制保存的歷史消息長(zhǎng)度減少 token 消耗。對(duì)非關(guān)鍵任務(wù)優(yōu)先使用gpt-3.5-turbo模型。錯(cuò)誤處理與降級(jí)用try...except包裹智能體的invoke調(diào)用。當(dāng)智能體失敗時(shí)提供友好的用戶提示或 fallback 到更簡(jiǎn)單的流程。記錄詳細(xì)的日志包括用戶輸入、智能體的思考過(guò)程、工具調(diào)用和最終輸出便于事后分析和優(yōu)化。配置外置化將模型名稱、API Base URL、溫度等參數(shù)放在配置文件如config.yaml或環(huán)境變量中。避免在代碼中硬編碼任何敏感信息或環(huán)境特定的配置。6. 擴(kuò)展方向與下一步學(xué)習(xí)建議通過(guò)本文的實(shí)踐你已經(jīng)掌握了構(gòu)建基礎(chǔ)單智能體和簡(jiǎn)單多智能體協(xié)作系統(tǒng)的方法。要深入智能體開(kāi)發(fā)可以從以下幾個(gè)方向繼續(xù)探索集成更豐富的工具智能體的能力取決于其工具集。嘗試集成網(wǎng)絡(luò)搜索使用SerpAPI或DuckDuckGoSearch工具讓智能體獲取實(shí)時(shí)信息。數(shù)據(jù)庫(kù)查詢集成SQLDatabaseToolkit讓智能體能查詢業(yè)務(wù)數(shù)據(jù)。代碼執(zhí)行與文件操作在嚴(yán)格的安全約束下讓智能體能編寫并運(yùn)行代碼片段或讀寫特定文件。探索更復(fù)雜的協(xié)作模式本文的“規(guī)劃-執(zhí)行”只是最簡(jiǎn)單的一種。研究以下模式辯論模式讓多個(gè)智能體就一個(gè)問(wèn)題提出不同觀點(diǎn)最終達(dá)成共識(shí)。評(píng)審模式一個(gè)智能體生成內(nèi)容另一個(gè)智能體負(fù)責(zé)評(píng)審和提出修改意見(jiàn)。分層管理一個(gè)“經(jīng)理”智能體接收任務(wù)分配給多個(gè)“員工”智能體并匯總結(jié)果。使用可視化平臺(tái)加速開(kāi)發(fā)對(duì)于復(fù)雜的工作流使用Dify或LangFlow這類可視化工具進(jìn)行編排和調(diào)試可以極大提升效率。你可以在這些平臺(tái)上設(shè)計(jì)節(jié)點(diǎn)和連接再導(dǎo)出為代碼。深入提示詞工程智能體的表現(xiàn)很大程度上受系統(tǒng)提示詞System Prompt影響。學(xué)習(xí)如何為不同角色規(guī)劃者、執(zhí)行者、評(píng)審者編寫清晰、具體、有約束力的提示詞是提升智能體性能的關(guān)鍵。關(guān)注智能體評(píng)估如何衡量一個(gè)智能體系統(tǒng)的優(yōu)劣建立評(píng)估體系包括任務(wù)完成率、步驟合理性、工具調(diào)用準(zhǔn)確率、耗時(shí)和成本等指標(biāo)并以此為導(dǎo)向進(jìn)行迭代優(yōu)化。智能體開(kāi)發(fā)是一個(gè)快速演進(jìn)的領(lǐng)域核心在于理解“感知-規(guī)劃-行動(dòng)-反思”這一范式并熟練運(yùn)用 LangChain 等框架將其工程化落地。從解決一個(gè)具體的、小的自動(dòng)化任務(wù)開(kāi)始逐步增加其復(fù)雜性和協(xié)作性是學(xué)習(xí)這門技術(shù)最有效的路徑。