戰(zhàn)指南：從零搭建多智能體協(xié)作工作流)
如果你最近在關(guān)注 AI Agent 方向大概率會(huì)注意到一個(gè)現(xiàn)象ChatGPT 這類(lèi)單一大模型已經(jīng)不能滿(mǎn)足復(fù)雜任務(wù)的落地需求了。真正要做一份行業(yè)研究報(bào)告、一套競(jìng)品分析、一個(gè)自動(dòng)化運(yùn)營(yíng) SOP如果只靠一次 Prompt模型很快就會(huì)出現(xiàn)上下文丟失、步驟遺漏、結(jié)果深度不夠的問(wèn)題。于是“多智能體系統(tǒng)”這個(gè)概念被推到了臺(tái)前。但說(shuō)實(shí)話(huà)多智能體這個(gè)概念在業(yè)界的討論熱度遠(yuǎn)遠(yuǎn)超過(guò)了實(shí)際落地進(jìn)度。原因很簡(jiǎn)單大模型本身只是“大腦”而多智能體系統(tǒng)要解決的是“多個(gè)大腦如何分工、如何協(xié)作、如何把任務(wù)跑完”的系統(tǒng)工程問(wèn)題。很多人看完概念覺(jué)得懂了一寫(xiě)代碼就發(fā)現(xiàn)智能體怎么定義、任務(wù)怎么拆分、角色之間怎么交接、失敗怎么重試全是難題。這篇文章要寫(xiě)的 CrewAI就是目前開(kāi)源社區(qū)里把“多智能體協(xié)作”這個(gè)概念落地得比較完整的一套 Python 框架。它不要求你從零實(shí)現(xiàn) Agent 調(diào)度邏輯而是用類(lèi)聲明式的方式把智能體、任務(wù)、流程、協(xié)作工具組裝成一個(gè)可運(yùn)行的 Crew團(tuán)隊(duì)。文章的定位很明確不堆概念直接給你一條能跑通的主線(xiàn)——從 CrewAI 的核心設(shè)計(jì)講起到環(huán)境搭建、代碼示例、運(yùn)行驗(yàn)證、常見(jiàn)問(wèn)題最后給出工程落地建議。讀完你應(yīng)該能做到自己定義一個(gè)多角色智能體團(tuán)隊(duì)編排任務(wù)流程跑出一個(gè)真實(shí)可用的自動(dòng)化工作流。1. 這篇文章真正要解決的問(wèn)題先花一點(diǎn)時(shí)間搞清楚為什么在多智能體這個(gè)方向上我們特別需要 CrewAI 這種框架如果你自己嘗試過(guò)用 LangChain 或者直接調(diào)用 OpenAI SDK 寫(xiě) Agent你會(huì)發(fā)現(xiàn)真正的痛點(diǎn)不是讓模型“變聰明”而是把復(fù)雜任務(wù)結(jié)構(gòu)化。比如要做一個(gè)企業(yè)輿情分析報(bào)告任務(wù)天然包含以下環(huán)節(jié)采集信息源篩選高價(jià)值信息判斷情緒和風(fēng)險(xiǎn)等級(jí)撰寫(xiě)分析正文整理成固定格式的報(bào)告。如果只讓一個(gè) Agent 完成全部工作它既要會(huì)搜索、又要會(huì)寫(xiě)作、還要會(huì)判斷不僅系統(tǒng) Prompt 會(huì)寫(xiě)得非常長(zhǎng)而且任何一個(gè)環(huán)節(jié)失敗都會(huì)導(dǎo)致整條鏈路不可用。更麻煩的是這種單體 Agent 出現(xiàn)錯(cuò)誤時(shí)你很難定位是采集的問(wèn)題還是判斷邏輯的問(wèn)題還是生成格式的問(wèn)題。多智能體系統(tǒng)的核心價(jià)值就是把這種“大而全”的任務(wù)拆成多個(gè)“小而專(zhuān)”的角色任務(wù)。每個(gè)智能體只把自己負(fù)責(zé)的環(huán)節(jié)做到位再通過(guò)流程機(jī)制實(shí)現(xiàn)任務(wù)上下文傳遞和結(jié)果匯總。CrewAI 解決的問(wèn)題概括起來(lái)就是三件事智能體定義如何用清晰的角色Role、目標(biāo)Goal和背景故事Backstory定義一個(gè)專(zhuān)職智能體。任務(wù)編排如何把多個(gè)任務(wù)按順序、按層級(jí)或者按事件驅(qū)動(dòng)的方式串起來(lái)形成完整工作流?？蛇\(yùn)行的自動(dòng)化流程如何讓這套多智能體系統(tǒng)不僅存在于文檔里還能真正跑出結(jié)果并接入大模型 API、外部工具和企業(yè)數(shù)據(jù)。所以這篇文章適合的讀者有三類(lèi)。第一類(lèi)是剛開(kāi)始了解 Agent 開(kāi)發(fā)、想找一套能快速跑通的腳手架的人第二類(lèi)是已經(jīng)用 LangChain 寫(xiě)過(guò) Agent但覺(jué)得直接編排多角色太痛苦的人第三類(lèi)是團(tuán)隊(duì)里要評(píng)估多智能體框架選型需要看 CrewAI 到底能做什么、不能做什么的技術(shù)負(fù)責(zé)人。一句話(huà)總結(jié)我的判斷CrewAI 不是讓 AI 從“單打獨(dú)斗”變成“一堆 Agent 聊天”而是把多智能體協(xié)作變成了可配置、可復(fù)用、可維護(hù)的工程代碼。這種變化才是它真正值得關(guān)注的原因。2. CrewAI 核心概念與設(shè)計(jì)思想CrewAI 之所以上手門(mén)檻比從零寫(xiě)調(diào)度器低是因?yàn)樗讯嘀悄荏w系統(tǒng)中的幾個(gè)高頻抽象概念直接做成了框架的基礎(chǔ)組件。理解這幾個(gè)概念勝過(guò)背誦十篇 API 文檔。2.1 Crew、Agent、Task 是三大基礎(chǔ)組件CrewAI 的頂層抽象是 Crew團(tuán)隊(duì)/劇組它定義了一個(gè)多智能體組織負(fù)責(zé)管理這個(gè)系統(tǒng)里有哪些智能體、要執(zhí)行哪些任務(wù)、任務(wù)之間以什么方式流轉(zhuǎn)。Agent智能體是 Crew 里的執(zhí)行單元。每個(gè) Agent 是一個(gè)“帶角色設(shè)定的大模型實(shí)例”它擁有獨(dú)立的角色、目標(biāo)和背景信息。CrewAI 里的 Agent 還有一個(gè)重要特性它可以配置工具Tools比如搜索、網(wǎng)頁(yè)訪問(wèn)、自定義 Python 函數(shù)這樣它在執(zhí)行任務(wù)時(shí)就有能力調(diào)用外部資源。Task任務(wù)是分配給 Agent 的、明確要輸出結(jié)果的工作單元。Task 包含任務(wù)描述、期望輸出格式、負(fù)責(zé)任務(wù)的 Agent 等信息。多個(gè) Task 之間允許有依賴(lài)關(guān)系后置任務(wù)可以把前置任務(wù)的輸出作為輸入上下文。下面用一個(gè)表格把這幾個(gè)概念對(duì)照一下概念通俗理解解決的核心問(wèn)題CrewAI 中的關(guān)鍵配置Agent團(tuán)隊(duì)里的一個(gè)“員工”每個(gè)角色只做專(zhuān)業(yè)的事role、goal、backstory、llm、toolsTask安排給員工的一條工作指令工作邊界和輸出標(biāo)準(zhǔn)description、expected_output、agentCrew一條完整的業(yè)務(wù)流水線(xiàn)把角色和任務(wù)組裝成可運(yùn)行流程agents、tasks、processProcess流水線(xiàn)的執(zhí)行方式?jīng)Q定任務(wù)串行還是分級(jí)管理sequential、hierarchicalFlow基于事件驅(qū)動(dòng)的工作流控制器更靈活的編排與狀態(tài)管理start、listen、狀態(tài)對(duì)象只看表格可能還不夠“切膚”。要理解這些概念最好的方式是把 CrewAI 比作一個(gè)劇組導(dǎo)演Flow 或 Hierarchical Process 中的 Manager不親自演戲但決定哪個(gè)演員在什么節(jié)點(diǎn)上場(chǎng)。編劇和攝影師Agent是不同的執(zhí)行單元編劇寫(xiě)腳本攝影師拍畫(huà)面。每個(gè)拍攝任務(wù)Task都有明確交付物。整部電影Crew是以上所有元素的集合。當(dāng)然這個(gè)類(lèi)比只是為了幫新手建立心智模型。真正寫(xiě)代碼時(shí)Agent 不會(huì)像人一樣“商量”著干活它靠的是結(jié)構(gòu)化 Prompt、工具調(diào)用和任務(wù)上下文傳遞。2.2 Process 決定協(xié)作是順序還是分級(jí)多智能體系統(tǒng)里最容易讓人困惑的一點(diǎn)是多個(gè)智能體到底怎么協(xié)作是我命令你、你命令他還是大家各干各的最后拼在一起CrewAI 提供兩種內(nèi)置 ProcessSequential Process順序流程。所有任務(wù)按聲明順序依次執(zhí)行Agent 像流水線(xiàn)工人一樣逐個(gè)處理自己負(fù)責(zé)的環(huán)節(jié)。優(yōu)點(diǎn)是好理解、好排錯(cuò)、成本和延遲可控。適合上下文強(qiáng)依賴(lài)、不適合并行的任務(wù)鏈。比如“先生成大綱再根據(jù)大綱寫(xiě)正文再基于正文配摘要”。Hierarchical Process層級(jí)流程。Crew 里會(huì)安排一個(gè) Manager Agent 或指定 manager_llm由它負(fù)責(zé)任務(wù)規(guī)劃、分配、審查和交接普通 Task 不預(yù)先綁定 Agent而是由 Manager 動(dòng)態(tài)決定。優(yōu)點(diǎn)是有全局統(tǒng)籌適合任務(wù)拆解不固定、依賴(lài)關(guān)系相對(duì)動(dòng)態(tài)的場(chǎng)景。缺點(diǎn)是多一次管理調(diào)度會(huì)引入額外的大模型調(diào)用開(kāi)銷(xiāo)和不確定性。社區(qū)里經(jīng)常討論“多智能體的四種交互模式”典型分類(lèi)包括順序鏈、并行分組、主從委派、事件驅(qū)動(dòng)協(xié)作等。對(duì)應(yīng)到 CrewAI 里順序模式對(duì)應(yīng) Sequential Process主從委派對(duì)應(yīng) Hierarchical Process事件驅(qū)動(dòng)模式對(duì)應(yīng)基于 Flow 的編排方式并行分組可以通過(guò)多個(gè)異步 Task 來(lái)組合實(shí)現(xiàn)。換句話(huà)說(shuō)你不需要把這些模式當(dāng)作孤立術(shù)語(yǔ)它們的本質(zhì)是任務(wù)關(guān)系圖的結(jié)構(gòu)差異。2.3 Flow比 Process 更靈活的工作流層Process 解決了一個(gè) Crew 內(nèi)部任務(wù)的線(xiàn)性和層級(jí)調(diào)度問(wèn)題但真實(shí)業(yè)務(wù)往往沒(méi)有這么規(guī)整。你會(huì)發(fā)現(xiàn)很多自動(dòng)化流程是循環(huán)的、條件是跳轉(zhuǎn)的、不同 Crew 之間需要嵌套調(diào)用。CrewAI 的 Flow 組件就是為這種場(chǎng)景設(shè)計(jì)的。Flow 允許你定義一個(gè)帶狀態(tài)的數(shù)據(jù)類(lèi)通過(guò)start()裝飾器標(biāo)注流程的起點(diǎn)通過(guò)listen()裝飾器監(jiān)聽(tīng)某個(gè)方法完成后觸發(fā)下一個(gè)動(dòng)作。這種事件驅(qū)動(dòng)機(jī)制可以處理?xiàng)l件分流根據(jù)某個(gè)步驟輸出決定走 A 分支還是 B 分支流程合并幾個(gè)獨(dú)立結(jié)果匯聚到一個(gè)最終總結(jié)步驟父子流程一個(gè) Flow 內(nèi)部調(diào)用另一個(gè)已經(jīng)定義好的 Crew。如果你之前用過(guò)自動(dòng)化測(cè)試框架或者數(shù)據(jù)管道調(diào)度框架Flow 的概念不會(huì)陌生。它本質(zhì)上就是用裝飾器和狀態(tài)對(duì)象來(lái)描述有向無(wú)環(huán)圖DAG。2.4 一個(gè)容易被忽略的設(shè)計(jì)Agent 的 Post-Tools很多新手用 CrewAI 時(shí)會(huì)有一個(gè)誤區(qū)Agent 收到任務(wù)后會(huì)自動(dòng)“思考”然后調(diào)用工具。實(shí)際上Agent 是否調(diào)用工具、調(diào)用什么工具取決于你在創(chuàng)建 Agent 時(shí)傳給它的tools參數(shù)以及任務(wù)的描述是否明確提示它需要使用工具。CrewAI 官方還有一個(gè)Agent的post_tools參數(shù)策略就是讓 Agent 在正式回答前先調(diào)用一組工具來(lái)增強(qiáng)信息避免“不知道答案也硬編”。這里不展開(kāi)細(xì)節(jié)但你要記住一個(gè)原則在這類(lèi)多智能體系統(tǒng)里工具的掛載位置會(huì)直接影響任務(wù)質(zhì)量——工具掛得太少Agent 只能靠模型幻覺(jué)補(bǔ)充信息工具掛得太多Agent 容易在無(wú)關(guān)工具上浪費(fèi) Token 和時(shí)間。3. 適用場(chǎng)景與框架選型CrewAI 到底適合什么多智能體框架目前不是一個(gè)贏者通吃的賽道。選型錯(cuò)誤往往不是框架的問(wèn)題而是需求和框架的匹配出了問(wèn)題。因此在寫(xiě)代碼之前值得先把選型問(wèn)題理清楚。先看 LangChain。LangChain 是 Agent 開(kāi)發(fā)的“瑞士軍刀”它提供了組件化的工具鏈和大量第三方集成但它本身不定義任務(wù)協(xié)作模型。如果你想基于 LangChain 寫(xiě)多智能體協(xié)作自己需要設(shè)計(jì) Agent 之間的通信協(xié)議、記憶共享、任務(wù)分配機(jī)制實(shí)際上是從零搭一套框架。再看 AutoGen 或 Semantic Kernel。這類(lèi)框架擅長(zhǎng)對(duì)話(huà)驅(qū)動(dòng)的多智能體交互多個(gè) Agent 通過(guò)消息傳遞完成合作。這在研究、對(duì)話(huà)式推理場(chǎng)景里很有優(yōu)勢(shì)但業(yè)務(wù)落地上Agent 之間自由對(duì)話(huà)往往意味著不確定性高、調(diào)試?yán)щy輸出格式也較難約束。CrewAI 的定位恰好介于兩者之間。它更接近“結(jié)構(gòu)化團(tuán)隊(duì)協(xié)作”用 Crew、Task、Process 這種有邊界的模型把任務(wù)編排固化成代碼。你定義角色定義任務(wù)框架幫你執(zhí)行任務(wù)結(jié)果結(jié)構(gòu)化可控性強(qiáng)容易復(fù)用。對(duì)比維度LangChain AgentAutoGenCrewAI核心抽象Chain Agent ToolConversable Agent 對(duì)話(huà)流Crew Agent Task Process多智能體協(xié)作方式需要自行設(shè)計(jì)對(duì)話(huà)驅(qū)動(dòng)聲明 流程驅(qū)動(dòng)任務(wù)結(jié)果可控性中等偏低較高上手難度中等偏高較低適合業(yè)務(wù)場(chǎng)景工具鏈復(fù)雜、組件化集成研究探索、開(kāi)放對(duì)話(huà)企業(yè)流程自動(dòng)化、內(nèi)容生產(chǎn)流水線(xiàn)那 CrewAI 最適合哪些場(chǎng)景根據(jù)實(shí)際項(xiàng)目經(jīng)驗(yàn)我可以給出幾個(gè)比較明確的場(chǎng)景清單。第一個(gè)是內(nèi)容與研究報(bào)告生產(chǎn)流水線(xiàn)。比如收集資料、整理觀點(diǎn)、撰寫(xiě)初稿、校對(duì)優(yōu)化如果把這幾個(gè)環(huán)節(jié)拆成專(zhuān)職 Agent配合固定的任務(wù)輸出格式產(chǎn)出質(zhì)量會(huì)明顯高于單 Agent 長(zhǎng)文本生成。第二個(gè)是企業(yè)業(yè)務(wù)運(yùn)營(yíng)自動(dòng)化。例如客服工單分類(lèi)、競(jìng)品監(jiān)控日?qǐng)?bào)、銷(xiāo)售線(xiàn)索初篩。這類(lèi)任務(wù)有清晰輸入輸出有固定流程非常適合用 Crew 封裝成可重復(fù)調(diào)用的服務(wù)。第三個(gè)是多工具編排場(chǎng)景。CrewAI Agent 支持掛載工具你能把搜索工具、數(shù)據(jù)庫(kù)查詢(xún)工具、內(nèi)部 API 工具掛到不同 Agent 上讓它們各司其職。不太適合 CrewAI 的場(chǎng)景也有一個(gè)典型高實(shí)時(shí)性、強(qiáng)交互的對(duì)話(huà)助手。CrewAI 本身不是對(duì)話(huà)狀態(tài)管理框架它有 Memory 和短期上下文設(shè)計(jì)但面向用戶(hù)的多輪對(duì)話(huà)系統(tǒng)還是應(yīng)該用專(zhuān)門(mén)對(duì)話(huà) Agent 框架來(lái)做把 CrewAI 作為服務(wù)端內(nèi)部任務(wù)編排組件。換言之不要讓用戶(hù)直接和 CrewAI 的 Agent 自由對(duì)話(huà)而是通過(guò) API 去觸發(fā)一個(gè)明確的 Crew 工作流。4. 環(huán)境準(zhǔn)備與工程目錄設(shè)計(jì)在動(dòng)手寫(xiě)代碼之前先把運(yùn)行環(huán)境說(shuō)清楚。CrewAI 是一個(gè)基于 Python 的框架底層封裝了 LangChain 的若干能力同時(shí)支持 OpenAI、Anthropic、Gemini、Ollama 等不同模型來(lái)源。我建議你在一個(gè)干凈的環(huán)境中安裝避免跟已有 LangChain 項(xiàng)目里的依賴(lài)發(fā)生版本沖突。建議環(huán)境如下Python 3.10 或更高版本推薦 3.10 到 3.12具體以官方當(dāng)前支持版本為準(zhǔn)pip 包管理器一個(gè)可選用的虛擬環(huán)境工具比如 venv 或 conda準(zhǔn)備一個(gè)大模型 API Key。如果你用 OpenAI 兼容接口可以配置OPENAI_API_KEY環(huán)境變量。安裝 CrewAI 的命令很簡(jiǎn)單pip install crewai如果計(jì)劃讓 Agent 使用瀏覽器搜索、網(wǎng)頁(yè)內(nèi)容讀取等常用工具可以一起安裝工具包pip install crewai[tools]CrewAI 生態(tài)迭代速度較快重要版本的 API 可能有調(diào)整因此creai的具體版本號(hào)建議以官方 PyPI 頁(yè)面為準(zhǔn)。本文的代碼示例以當(dāng)前主流的類(lèi)聲明式用法為主。安裝完成后可以先做一個(gè)最小驗(yàn)證python -c import crewai; print(crewai.__version__)如果這條命令能正常輸出版本號(hào)說(shuō)明框架安裝沒(méi)問(wèn)題。工程目錄方面如果你只是學(xué)習(xí)跑通建議先建一個(gè)單文件腳本如果是正式業(yè)務(wù)項(xiàng)目我更推薦這樣的目錄結(jié)構(gòu)project/ ├── agents/ │ └── researcher_agent.py # 智能體定義 ├── tasks/ │ └── research_task.py # 任務(wù)定義 ├── crews/ │ ├── research_crew.py # 組裝 Crew │ └── flow.py # 基于 Flow 的工作流 ├── tools/ │ ├── search_tool.py │ └── custom_tool.py ├── config/ │ └── llm_config.py # 模型統(tǒng)一配置 ├── output/ │ └── reports/ ├── main.py # 入口 └── requirements.txt這種拆分方式的好處是智能體、任務(wù)、流程互相解耦。一個(gè) Agent 可以參與不同 Task一個(gè) Task 也可以在不同 Crew 里復(fù)用將來(lái)接入 Web 服務(wù)時(shí)只需要在 API 層調(diào)用Crew.kickoff()整個(gè)業(yè)務(wù)能力就被封裝成函數(shù)了。實(shí)際項(xiàng)目里我更建議把智能體定義和任務(wù)描述放到配置文件里管理代碼里只負(fù)責(zé)注冊(cè)和組裝。CrewAI 也支持 YAML 配置方式對(duì)團(tuán)隊(duì)協(xié)作和后續(xù)維護(hù)更友好。不過(guò)本文為了減少認(rèn)知負(fù)擔(dān)直接用 Python 代碼描述。5. CrewAI 完整示例從最小 Crew 到事件驅(qū)動(dòng) Flow下面開(kāi)始進(jìn)入實(shí)操環(huán)節(jié)。我們從最簡(jiǎn)單的一 Crew 一 Agent 開(kāi)始逐步增加角色和任務(wù)最后用一個(gè) Flow 示例演示事件驅(qū)動(dòng)工作流。5.1 最小示例研究助手 Crew先跑通最小環(huán)境。創(chuàng)建一個(gè)first_crew.py文件代碼如下# 文件路徑first_crew.py from crewai import Agent, Task, Crew, Process # 1. 定義智能體 researcher Agent( role高級(jí)技術(shù)研究員, goal圍繞用戶(hù)給定主題調(diào)研技術(shù)原理并形成結(jié)構(gòu)化摘要, backstory( 你是一位經(jīng)驗(yàn)豐富的技術(shù)研究員 擅長(zhǎng)快速?gòu)馁Y料中提煉關(guān)鍵事實(shí) 不喜歡無(wú)依據(jù)的推測(cè)。 ), verboseTrue ) # 2. 定義任務(wù) research_task Task( description調(diào)研 CrewAI 的核心概念輸出一份面向開(kāi)發(fā)者的摘要。, expected_output( 一份包含核心概念、主要用途、適用場(chǎng)景的 Markdown 列表 每項(xiàng)不超過(guò) 50 字。 ), agentresearcher, ) # 3. 組裝 Crew crew Crew( agents[researcher], tasks[research_task], processProcess.sequential, verboseTrue, ) if __name__ __main__: result crew.kickoff() print( 最終輸出 ) print(result)這里需要解釋幾個(gè)關(guān)鍵參數(shù)。Agent里的role設(shè)置了智能體的角色身份goal設(shè)定了總體目標(biāo)backstory是給大模型的背景補(bǔ)全信息這三者拼在一起實(shí)際構(gòu)成了 Agent 系統(tǒng)提示詞的核心。verboseTrue表示在命令行輸出任務(wù)執(zhí)行的中間過(guò)程排錯(cuò)時(shí)非常有用。Task里的description是任務(wù)內(nèi)容expected_output是期望的輸出結(jié)構(gòu)和風(fēng)格。多智能體系統(tǒng)里任務(wù)描述寫(xiě)得好不好決定了大模型和下游協(xié)作者能不能理解結(jié)果。這塊不要偷懶。Crew接收agents列表和tasks列表processProcess.sequential表示順序執(zhí)行。kickoff()是 Crew 的入口函數(shù)調(diào)用后框架會(huì)自動(dòng)拉起整個(gè)流程。運(yùn)行方式python first_crew.py如果配置好了大模型 API你會(huì)看到控制臺(tái)依次輸出 Agent 的思考步驟、工具調(diào)用和最終結(jié)果。kickoff()返回的對(duì)象是 CrewOutput直接print(result)可以看見(jiàn)任務(wù)輸出正文。5.2 順序編排內(nèi)容生產(chǎn)流水線(xiàn)下面把場(chǎng)景升級(jí)用三個(gè) Agent 組成一條內(nèi)容生產(chǎn)流水線(xiàn)分工做“選題策劃 → 初稿撰寫(xiě) → 校對(duì)潤(rùn)色”。# 文件路徑content_crew.py from crewai import Agent, Task, Crew, Process planner Agent( role內(nèi)容策劃編輯, goal根據(jù)主題規(guī)劃文章大綱和核心觀點(diǎn), backstory你是一位資深內(nèi)容策劃善于把復(fù)雜技術(shù)問(wèn)題拆解成清晰的文章結(jié)構(gòu)。, ) writer Agent( role技術(shù)文章作者, goal根據(jù)大綱撰寫(xiě)技術(shù)教程正文, backstory你是一位有一線(xiàn)開(kāi)發(fā)經(jīng)驗(yàn)的技術(shù)作者擅長(zhǎng)用示例和步驟講清楚概念。, ) reviewer Agent( role質(zhì)量審核編輯, goal從準(zhǔn)確性、結(jié)構(gòu)完整性和表達(dá)清晰度方面審核文章輸出修改建議, backstory你是一位嚴(yán)格的編輯重點(diǎn)檢查文章是否存在術(shù)語(yǔ)誤用、邏輯斷裂和缺少示例。, ) plan_task Task( description( 主題如何使用 Python 實(shí)現(xiàn)定時(shí)任務(wù)。 請(qǐng)輸出文章大綱包括引言、環(huán)境準(zhǔn)備、核心示例、常見(jiàn)問(wèn)題四部分。 ), expected_output結(jié)構(gòu)化的 Markdown 大綱每個(gè)章節(jié)下寫(xiě)清楚要點(diǎn)。, agentplanner, ) write_task Task( description( 基于以下大綱撰寫(xiě)技術(shù)教程正文\n {plan_output}\n 要求每段給出可運(yùn)行的代碼示例語(yǔ)言風(fēng)格平實(shí)、專(zhuān)業(yè)。 ), expected_output完整的 Markdown 技術(shù)文章正文包含代碼塊。, agentwriter, context[plan_task] ) review_task Task( description( 審核以下技術(shù)文章檢查內(nèi)容準(zhǔn)確性和結(jié)構(gòu)\n {write_output}\n 輸出具體修改建議不要直接重寫(xiě)全文。 ), expected_output按嚴(yán)重程度排序的修改建議列表。, agentreviewer, context[write_task] ) content_crew Crew( agents[planner, writer, reviewer], tasks[plan_task, write_task, review_task], processProcess.sequential, verboseTrue, ) if __name__ __main__: result content_crew.kickoff() print( 審核建議 ) print(result)這個(gè)示例里有幾個(gè)關(guān)鍵點(diǎn)值得展開(kāi)。第一個(gè)是context參數(shù)。write_task聲明了context[plan_task]意思是它執(zhí)行時(shí)會(huì)把plan_task的輸出作為上下文傳入。review_task同理依賴(lài)write_task的輸出。相比直接使用{plan_output}這種變量占位context更明確地建立了任務(wù)級(jí)依賴(lài)關(guān)系。實(shí)際上CrewAI 在 Task 執(zhí)行時(shí)會(huì)把 context 中任務(wù)的輸出拼到當(dāng)前任務(wù)描述后面因此你可以在任務(wù)描述里用大括號(hào)引用。如果任務(wù)之間沒(méi)有顯式依賴(lài)就不要亂加context減少不必要的 Token 消耗。第二個(gè)是任務(wù)描述里的占位符寫(xiě)法。{plan_output}是引用前序任務(wù)輸出的快捷方式。用不熟悉的開(kāi)發(fā)者很容易忽略這一點(diǎn)導(dǎo)致下游任務(wù)拿不到上游結(jié)果。第三點(diǎn)是Process.sequential只負(fù)責(zé)按列表順序執(zhí)行任務(wù)它不代表“每個(gè) Agent 都只執(zhí)行一次任務(wù)”。框架內(nèi)部會(huì)協(xié)調(diào)上下文你只需要定義清楚哪些角色、哪些任務(wù)、哪些依賴(lài)。運(yùn)行內(nèi)容生產(chǎn) Crew 后你會(huì)看到作者 Agent 產(chǎn)出初稿審核 Agent 對(duì)初稿給出意見(jiàn)。如果你希望把審核意見(jiàn)直接應(yīng)用到文章里只需要再增加一個(gè)編輯 Agent 和對(duì)應(yīng) Task承接修改任務(wù)即可。這就是流水線(xiàn)編排的威力每增加一個(gè)環(huán)節(jié)只是新增一個(gè)角色和一條任務(wù)。5.3 層級(jí)流程Manager 統(tǒng)籌模式業(yè)務(wù)場(chǎng)景里還有一種更常見(jiàn)的情況任務(wù)不是一開(kāi)始就能寫(xiě)死成固定步驟的需要根據(jù)實(shí)際內(nèi)容動(dòng)態(tài)拆解。比如“調(diào)研某技術(shù)方向的趨勢(shì)并輸出報(bào)告”具體要訪問(wèn)哪些網(wǎng)站、要看哪些材料不應(yīng)該是我們預(yù)先硬編碼的而應(yīng)該由一個(gè)統(tǒng)管 Agent 來(lái)判斷。這種場(chǎng)景適合用 Hierarchical Process。# 文件路徑hierarchical_crew.py from crewai import Agent, Task, Crew, Process researcher Agent( role前沿技術(shù)觀察員, goal搜集指定技術(shù)方向的最新動(dòng)態(tài)與發(fā)展趨勢(shì), backstory你長(zhǎng)期跟蹤 AI 工程化領(lǐng)域動(dòng)態(tài)善于發(fā)現(xiàn)關(guān)鍵信號(hào)。, ) analyst Agent( role商業(yè)技術(shù)分析師, goal對(duì)收集到的信息進(jìn)行結(jié)構(gòu)化分析并形成判斷, backstory你擅長(zhǎng)從分散信息中歸納趨勢(shì)給技術(shù)決策者提供可執(zhí)行的結(jié)論。, ) report_task Task( description調(diào)研多智能體編排框架的行業(yè)采用趨勢(shì)并輸出一份分析簡(jiǎn)報(bào)。, expected_output包含關(guān)鍵趨勢(shì)、代表項(xiàng)目、落地建議的 Markdown 簡(jiǎn)報(bào)。, ) hierarchical_crew Crew( agents[researcher, analyst], tasks[report_task], processProcess.hierarchical, manager_llmNone, # 不顯式指定時(shí)會(huì)復(fù)用默認(rèn) LLM manager_agentNone, # 也可以指定一個(gè) Agent 作為 Manager verboseTrue, ) if __name__ __main__: result hierarchical_crew.kickoff() print( 層級(jí)流程輸出 ) print(result)注意在層級(jí)流程的寫(xiě)法里report_task沒(méi)有綁定agent參數(shù)。這是因?yàn)樵?Hierarchical Process 中負(fù)責(zé)任務(wù)分配的 Manager 會(huì)動(dòng)態(tài)決定把 Task 交給哪個(gè) Agent 執(zhí)行不需要預(yù)先綁定。你需要提供的是 Agent 池Manager 從池中選擇合適的執(zhí)行者。如果你希望 Manager 既當(dāng)裁判又當(dāng)運(yùn)動(dòng)員可以顯式傳入一個(gè)manager_agent如果只告訴 Crew 用哪個(gè)模型做管理就傳manager_llm。二者選擇其一即可。實(shí)際生產(chǎn)環(huán)境中為避免 Manager 模型和執(zhí)行 Agent 模型混用導(dǎo)致成本難以核算更推薦用manager_llm指定一個(gè)更高配置的模型執(zhí)行 Agent 使用相對(duì)輕量的模型。用層級(jí)流程時(shí)要注意 Token 消耗。Manager 的每一步規(guī)劃、審查、總結(jié)都會(huì)調(diào)用大模型。任務(wù)一多成本會(huì)顯著上升。如果業(yè)務(wù)步驟固定、拆解明確優(yōu)先使用順序流程層級(jí)流程作為兜底和補(bǔ)充。5.4 自定義工具讓 Agent 不再只靠記憶多智能體 Agent 真正落地一般離不開(kāi)工具調(diào)用能力。一個(gè)只靠模型內(nèi)部知識(shí)回答問(wèn)題的 Agent本質(zhì)上還是一個(gè)高級(jí)聊天機(jī)器人只有讓它可以查詢(xún)數(shù)據(jù)庫(kù)、調(diào)內(nèi)部接口、搜索網(wǎng)頁(yè)它才算進(jìn)入工作流。CrewAI 的 Agent 通過(guò)tools參數(shù)掛載工具工具可以是內(nèi)置的serper_dev_tool、scrape_website_tool也可以是自己寫(xiě)的一個(gè)普通 Python 函數(shù)再包裝成tool裝飾器。演示一個(gè)自定義工具。假設(shè)我們需要讓 Agent 查詢(xún)本地配置好的知識(shí)庫(kù) API# 文件路徑knowledge_tool.py from crewai_tools import tool tool(知識(shí)庫(kù)搜索) def search_knowledge_base(query: str) - str: 在內(nèi)部知識(shí)庫(kù)中搜索與 query 相關(guān)的知識(shí)內(nèi)容。 如果未找到返回 NO_RESULT。 # 實(shí)際項(xiàng)目中這里會(huì)調(diào)用內(nèi)部知識(shí)庫(kù) API 或向量數(shù)據(jù)庫(kù) # 這里只做演示使用一個(gè)簡(jiǎn)單映射表 knowledge { 部署: 生產(chǎn)環(huán)境部署前必須備份數(shù)據(jù)庫(kù)并執(zhí)行回歸測(cè)試。, 回滾: 回滾操作優(yōu)先使用上一穩(wěn)定版本鏡像并觀察監(jiān)控指標(biāo)。, } for key, value in knowledge.items(): if key in query: return value return NO_RESULT然后掛載到 Agent 上# 文件路徑tool_crew.py from crewai import Agent, Task, Crew, Process from knowledge_tool import search_knowledge_base ops_agent Agent( role運(yùn)維知識(shí)顧問(wèn), goal回答基于內(nèi)部知識(shí)庫(kù)的運(yùn)維問(wèn)題, backstory你只能依據(jù)內(nèi)部知識(shí)庫(kù)回答不要憑空補(bǔ)充沒(méi)有來(lái)源的操作步驟。, tools[search_knowledge_base], ) answer_task Task( description請(qǐng)回答生產(chǎn)環(huán)境部署時(shí)的注意事項(xiàng)有哪些, expected_output一段不超過(guò) 100 字的安全操作建議。, agentops_agent, ) tool_crew Crew( agents[ops_agent], tasks[answer_task], verboseTrue, ) if __name__ __main__: result tool_crew.kickoff() print(result)這里一個(gè)關(guān)鍵細(xì)節(jié)是tool裝飾器里的函數(shù)文檔字符串。大模型并不是靠你的“函數(shù)名”理解工具的它靠的是函數(shù)簽名、參數(shù)說(shuō)明、文檔字符串綜合判斷何時(shí)調(diào)用該工具。因此工具描述要寫(xiě)清楚“什么場(chǎng)景用、輸入什么、返回什么、找不到時(shí)返回什么”。一個(gè)含糊的工具描述很可能讓 Agent 在無(wú)關(guān)請(qǐng)求上頻繁調(diào)用工具消耗大量 Token。這里也回應(yīng)一個(gè)網(wǎng)絡(luò)熱詞很多人問(wèn)“如何把小龍蝦或者愛(ài)馬仕集成到多智能體系統(tǒng)中”其實(shí)當(dāng)一個(gè) Agent 能通過(guò) MCPModel Context Protocol等協(xié)議掛載外部工具時(shí)重點(diǎn)不是對(duì)象本身叫什么名字而是它暴露了什么工具接口、返回什么格式的數(shù)據(jù)。真正值得研究的是 MCP 服務(wù)器如何把業(yè)務(wù)數(shù)據(jù)抽象成 Agent 可調(diào)用的工具。5.5 事件驅(qū)動(dòng)工作流基于 Flow 實(shí)現(xiàn)動(dòng)態(tài)編排前幾個(gè)示例里的 Process 都是把一個(gè) Crew 內(nèi)部的任務(wù)按固定方式跑完。如果業(yè)務(wù)包含多個(gè) Crew、條件分支或循環(huán)處理就要用 Flow。下面這段代碼演示一個(gè)“熱點(diǎn)內(nèi)容自動(dòng)加工”流程收到主題后先生成研究摘要如果摘要長(zhǎng)度不夠走增強(qiáng)補(bǔ)充路徑最后匯總輸出。# 文件路徑research_flow.py from typing import Any from pydantic import BaseModel from crewai.flow import Flow, listen, start from crewai import Agent, Task, Crew, Process class ResearchState(BaseModel): topic: str 人工智能編排框架 raw_summary: str final_summary: str need_expand: bool False class ResearchFlow(Flow[ResearchState]): start() def initiate_research(self): # 首輪 Agent 執(zhí)行快速生成摘要 agent Agent( role行業(yè)研究員, goal快速生成指定主題的研究摘要, backstory你擅長(zhǎng)快速判斷主題的核心脈絡(luò)。, ) task Task( descriptionf圍繞主題《{self.state.topic}》生成 150 字以?xún)?nèi)摘要。, expected_output一段簡(jiǎn)潔摘要。, agentagent, ) crew Crew(agents[agent], tasks[task], processProcess.sequential) self.state.raw_summary crew.kickoff().raw # 判斷是否需要擴(kuò)展比如摘要是否過(guò)短 self.state.need_expand len(self.state.raw_summary) 50 listen(initiate_research) def expand_if_needed(self): if not self.state.need_expand: return # 第二輪覆蓋針對(duì)缺失細(xì)節(jié)做補(bǔ)充 agent Agent( role細(xì)節(jié)補(bǔ)充編輯, goal對(duì)短摘要進(jìn)行事實(shí)擴(kuò)充, backstory你是嚴(yán)謹(jǐn)?shù)木庉嬔a(bǔ)充內(nèi)容必須與摘要主題一致。, ) task Task( descriptionf基于摘要《{self.state.raw_summary}》擴(kuò)展成 300 字左右的完整段落。, expected_output一段內(nèi)容完整、信息密度高的文字。, agentagent, ) crew Crew(agents[agent], tasks[task], processProcess.sequential) self.state.final_summary crew.kickoff().raw listen(expand_if_needed) def finalize(self, output: Any): # 如果沒(méi)有經(jīng)過(guò)擴(kuò)展final_summary 為空這里兜底賦值 if not self.state.final_summary: self.state.final_summary self.state.raw_summary print( 最終研究結(jié)果 ) print(self.state.final_summary) if __name__ __main__: flow ResearchFlow() flow.kickoff()這段代碼里Flow 的用法主要通過(guò)裝飾器和狀態(tài)對(duì)象完成繼承Flow[ResearchState]ResearchState繼承了pydantic.BaseModel用來(lái)定義整個(gè) Flow 運(yùn)行期間的狀態(tài)字段。start()標(biāo)記的initiate_research是入口方法任何流程只能有一個(gè)或多個(gè)入口它們是 Flow 的開(kāi)始。listen(initiate_research)表示監(jiān)聽(tīng)某個(gè)方法執(zhí)行完后的結(jié)果。只有前一個(gè)方法執(zhí)行成功被監(jiān)聽(tīng)的方法才會(huì)執(zhí)行。狀態(tài)對(duì)象self.state負(fù)責(zé)在多個(gè)方法之間傳遞數(shù)據(jù)。這樣一來(lái)MCP 調(diào)用、Crew 執(zhí)行、分支判斷等都變成了方法之間的數(shù)據(jù)流動(dòng)整體更接近傳統(tǒng)后端工程師熟悉的 Service 代碼。Flow 是 CrewAI 新版本里力推的編排層但不是說(shuō)每個(gè)項(xiàng)目都必須用它。如果是固定順序的 3 到 5 個(gè)步驟直接用Crew.kickoff()就夠了如果流程里有分支、循環(huán)、嵌套多個(gè) Crew建議升級(jí)到 Flow。6. 運(yùn)行驗(yàn)證與判斷標(biāo)準(zhǔn)跑通代碼只是第一步。真正需要注意的是你怎么判斷多智能體系統(tǒng)的運(yùn)行結(jié)果是“成功”的。6.1 命令行運(yùn)行觀察什么當(dāng)verboseTrue時(shí)CrewAI 會(huì)在控制臺(tái)打印每個(gè) Agent 的執(zhí)行過(guò)程。不同 Agent 完成任務(wù)后你會(huì)看到類(lèi)似這樣的輸出結(jié)構(gòu)任務(wù)開(kāi)始提示Agent 正在處理的任務(wù)描述思考過(guò)程Agent 如何理解任務(wù)工具調(diào)用與觀察結(jié)果如果調(diào)用了工具會(huì)顯示工具輸入和返回值任務(wù)最終輸出Agent 的最終回答。如果某個(gè)環(huán)節(jié)的輸出明顯不符合任務(wù)描述中的要求比如“本應(yīng)輸出 Markdown 列表實(shí)際輸出了純文本”這就說(shuō)明任務(wù)描述不夠嚴(yán)格。所有任務(wù)描述都必須顯式聲明 expected_output否則大模型不知道交付標(biāo)準(zhǔn)結(jié)果會(huì)非常不穩(wěn)定。6.2 結(jié)果判斷的三種方式第一種是人工閱讀。適合調(diào)研報(bào)告、內(nèi)容生產(chǎn)判斷標(biāo)準(zhǔn)是信息準(zhǔn)確、邏輯清晰、沒(méi)有幻覺(jué)。第二種是結(jié)構(gòu)化字段校驗(yàn)。適合數(shù)據(jù)抽取、分類(lèi)、工單處理?？梢园裈ask配置output_pydantic或output_json讓 Agent 輸出 JSON 格式然后在Crew.kickoff()返回結(jié)果中用 Pydantic 模型校驗(yàn)字段完整性和類(lèi)型。第三種是外部斷言。適合自動(dòng)化任務(wù)比如 Agent 判斷“某事件風(fēng)險(xiǎn)等級(jí)為高危”下游系統(tǒng)再拿著這個(gè)結(jié)論觸發(fā)不同告警通過(guò)業(yè)務(wù)規(guī)則確保輸出被正確消費(fèi)。6.3 第一優(yōu)先級(jí)看的失敗點(diǎn)如果運(yùn)行失敗不要急著改 Prompt。先按以下順序排查看 API Key 是否配置、是否欠費(fèi)或限流。這是大多數(shù)第一次運(yùn)行失敗的根因。看依賴(lài)版本。CrewAI 與 LangChain 生態(tài)版本耦合較緊升級(jí)某個(gè)包可能導(dǎo)致內(nèi)部接口不兼容?？慈蝿?wù)之間的上下文變量名是否正確。占位符寫(xiě)錯(cuò)不會(huì)直接報(bào)錯(cuò)但會(huì)輸出原始字符串到下游?？磛erbose日志里 Agent 最后執(zhí)行到哪個(gè)節(jié)點(diǎn)。如果某個(gè) Agent 從頭到尾沒(méi)有輸出大概率是它的任務(wù)描述沒(méi)有進(jìn)到 Agent 的執(zhí)行上下文。7. CrewAI 常見(jiàn)問(wèn)題與排查思路我整理了多智能體開(kāi)發(fā)過(guò)程中出現(xiàn)頻率最高的幾個(gè)問(wèn)題。這張表可以直接作為你排錯(cuò)時(shí)的檢查單。問(wèn)題現(xiàn)象可能原因排查方式解決方案第一次運(yùn)行報(bào)錯(cuò) 401/429API Key 錯(cuò)誤、額度不足或觸發(fā)限流單獨(dú)調(diào)用模型 SDK 驗(yàn)證 Key檢查賬號(hào)余額更新 Key提高限流閾值或切換模型供應(yīng)商Agent 沒(méi)有調(diào)用工具工具描述不清晰或任務(wù)描述未提示工具查看 verbose 日志中 Agent 是否“考慮”過(guò)工具調(diào)用的可能性?xún)?yōu)化工具描述在任務(wù)描述里明確“允許使用知識(shí)庫(kù)搜索”流程中途報(bào)錯(cuò)“Could not parse LLM output”大模型返回內(nèi)容不滿(mǎn)足 JSON、代碼塊等結(jié)構(gòu)化要求查看報(bào)錯(cuò)前后 LLM 原文確認(rèn)是否超過(guò)上下文長(zhǎng)度縮小任務(wù)粒度配置output_json或output_pydantic更換更強(qiáng)模型下游任務(wù)引用了空上下文context 任務(wù)未執(zhí)行或任務(wù)描述中變量名寫(xiě)錯(cuò)先獨(dú)立運(yùn)行上游任務(wù)確認(rèn)輸出非空檢查引用變量名檢查 Task 列表順序和 context 關(guān)系任務(wù)結(jié)果很好但耗時(shí)太長(zhǎng)/費(fèi)用過(guò)高任務(wù)鏈過(guò)長(zhǎng)、層級(jí) Manager 反復(fù)調(diào)度、Agent 反復(fù)重試在 verbose 日志中統(tǒng)計(jì)每個(gè)環(huán)節(jié)步數(shù)查看 API 用量面板減少 Agent 數(shù)量用順序流程替代層級(jí)流程降低重試次數(shù)不同 Agent 之間格式不統(tǒng)一每個(gè) Task 都未規(guī)定 expected_output查看多個(gè) Task 的返回結(jié)果在 expected_output 中規(guī)定 Markdown/JSON/列表等格式Flow 中l(wèi)isten方法不執(zhí)行監(jiān)聽(tīng)的方法名寫(xiě)錯(cuò)或監(jiān)聽(tīng)方法拋異常被吞掉檢查裝飾器中的函數(shù)引用是否與實(shí)際情況一致添加 try/except 打印異常修正監(jiān)聽(tīng)參數(shù)對(duì)異常做顯式捕獲生產(chǎn)環(huán)境頻繁變更導(dǎo)致流程不可用模型版本、提示詞、Agent 配置沒(méi)有版本管理檢查是否有配置文件和流程代碼的版本標(biāo)簽將 Agent/Task 配置納入 Git對(duì) Prompt 變更做回歸測(cè)試這里單獨(dú)強(qiáng)調(diào)兩個(gè)新手最容易出的問(wèn)題。第一個(gè)是任務(wù)越寫(xiě)越大。很多人覺(jué)得一個(gè) Agent 一次做多個(gè)步驟能省錢(qián)實(shí)際結(jié)果往往相反——大模型在長(zhǎng)任務(wù)里的注意力和指令遵循能力會(huì)下降一步錯(cuò)步步錯(cuò)。更合理的拆法是一個(gè) Agent 只完成“一個(gè)思維動(dòng)作”檢索就檢索分析就分析寫(xiě)就寫(xiě)審就審。第二個(gè)是沒(méi)有給 Agent 定義清晰的“不做什么”。一個(gè) Agent 的 backstory 里只寫(xiě)了“你擅長(zhǎng)寫(xiě)文章”它就可能在需要調(diào)用工具時(shí)選擇自己“編內(nèi)容”。所以在 backstory 中要明確加一句邊界比如“你只能依據(jù)資料輸出不臆造事實(shí)”“如果缺少必要信息明確說(shuō)明缺少哪些信息”。8. 多智能體系統(tǒng)開(kāi)發(fā)最佳實(shí)踐與工程建議從“代碼能跑”到“系統(tǒng)能上線(xiàn)”中間還差著一整套工程化約束。下面是我認(rèn)為在多智能體系統(tǒng)開(kāi)發(fā)中比較重要的幾條建議。8.1 為任務(wù)設(shè)計(jì)明確的外部上下文邊界多智能體系統(tǒng)穩(wěn)定性的最大隱患是上下文污染。當(dāng) Agent 數(shù)量變多、任務(wù)鏈變長(zhǎng)如果一個(gè)早期任務(wù)的輸出含錯(cuò)誤信息后續(xù) Agent 可能會(huì)在錯(cuò)誤前提上繼續(xù)生成而且錯(cuò)誤會(huì)被逐步放大。因此不要把所有歷史結(jié)果都傳給下游。每個(gè) Task 的 description 只保留完成任務(wù)所需的關(guān)鍵上下文即可。必要時(shí)可以在任務(wù)間加入“信息抽取”環(huán)節(jié)讓一個(gè)專(zhuān)門(mén) Agent 從上游長(zhǎng)文本中抽取出精煉的結(jié)構(gòu)化信息再傳給下游。這會(huì)讓 Token 成本更可控也會(huì)顯著提高結(jié)果穩(wěn)定性。8.2 用最小授權(quán)和沙箱隔離工具權(quán)限如果你給 Agent 掛載了能執(zhí)行代碼、訪問(wèn)數(shù)據(jù)庫(kù)或調(diào)用內(nèi)部 API 的工具必須遵循最小權(quán)限原則。一個(gè)做內(nèi)容分類(lèi)的 Agent 不需要?jiǎng)h除數(shù)據(jù)庫(kù)的權(quán)限一個(gè)做數(shù)據(jù)查詢(xún)的 Agent 不應(yīng)獲得生產(chǎn)環(huán)境的寫(xiě)權(quán)限默認(rèn)只讀。工具調(diào)用應(yīng)該有三層護(hù)欄第一層是在代碼層做好參數(shù)校驗(yàn)和權(quán)限校驗(yàn)第二層是在工具描述中明確邊界第三層是核心操作前加入人工審批或條件約束。8.3 日志、追蹤和評(píng)估是生產(chǎn)上線(xiàn)的前提傳統(tǒng)的單元測(cè)試很難覆蓋自然語(yǔ)言輸出的不確定性。多智能體項(xiàng)目上線(xiàn)前需要至少做到每個(gè)任務(wù)的輸入、輸出、Token 用量、延遲都記錄到日志里對(duì)結(jié)果做結(jié)構(gòu)化評(píng)估例如 JSON 字段校驗(yàn)、關(guān)鍵詞規(guī)則、核心指標(biāo)是否出現(xiàn)準(zhǔn)備一組典型用例作為回歸集修改 Prompt 或任務(wù)步驟后用同一組用例重新跑一遍數(shù)據(jù)敏感時(shí)做脫敏后再記錄日志。8.4 Prompt 和配置要納入版本管理多智能體系統(tǒng)的核心其實(shí)是提示詞工程和任務(wù)編排。Agent 的 role、goal、backstory、Task 的 description本質(zhì)上都是代碼的一部分需要走 Git 管理。實(shí)際操作中可以把 Agent 和 Task 配置抽成 YAML 文件再通過(guò) CrewAI 的配置加載機(jī)制讀取避免把大量自然語(yǔ)言配置散落在 Python 類(lèi)的文件里。8.5 固定模型版本和 Provider 配置同一個(gè) Prompt 在不同模型上的表現(xiàn)差異很大。團(tuán)隊(duì)在開(kāi)發(fā)階段如果用高配模型驗(yàn)證效果但生產(chǎn)環(huán)境為了省錢(qián)換了小模型很可能出現(xiàn)規(guī)則不穩(wěn)定的現(xiàn)象。更穩(wěn)妥的做法是在配置中心統(tǒng)一管理模型選擇評(píng)估階段固定一組模型輸出結(jié)果全部保留對(duì)比記錄生產(chǎn)切換模型時(shí)必須做回歸。8.6 控制并行度和異步任務(wù)粒度CrewAI 支持任務(wù)異步執(zhí)行。當(dāng)多個(gè)相互獨(dú)立的任務(wù)存在時(shí)可以用async_executionTrue讓它們?cè)谕粋€(gè) Crew 內(nèi)并行執(zhí)行減少總耗時(shí)。但并行并不是越多越好并行度太高短時(shí)間內(nèi)的 Token 消耗會(huì)猛增同一個(gè)模型供應(yīng)商的限流也會(huì)導(dǎo)致大面積失敗。建議從 2 到 3 個(gè)并行任務(wù)開(kāi)始觀察 API 每分鐘請(qǐng)求數(shù)和 Token 消耗再逐步調(diào)高。9. 總結(jié)與后續(xù)學(xué)習(xí)方向回到這篇文章開(kāi)頭提出的判斷CrewAI 的真正價(jià)值是把多智能體系統(tǒng)從“研究玩具”推進(jìn)到“工程化任務(wù)編排工具”的位置。它用 Crew、Agent、Task、Process、Flow 這幾個(gè)清晰的概念讓開(kāi)發(fā)者能用聲明式代碼搭建一條可運(yùn)行的自動(dòng)化工作流。從實(shí)際項(xiàng)目經(jīng)驗(yàn)來(lái)看這不只是省掉了一部分調(diào)度代碼更是改變了多智能體系統(tǒng)的維護(hù)方式——你不再需要讀完幾千行調(diào)度邏輯才能理解系統(tǒng)在干什么看配置就能知道哪些角色、按什么順序、完成哪些任務(wù)。如果你是第一次接觸 CrewAI下一步可以按這個(gè)路徑實(shí)踐-先復(fù)現(xiàn)第 5.1 節(jié)的最小示例跑通環(huán)境把第 5.2 節(jié)的內(nèi)容生產(chǎn)流水線(xiàn)改成你自己的業(yè)務(wù)場(chǎng)景找一個(gè)小型工具按第 5.4 節(jié)的方式把它封裝成 Agent 工具如果流程進(jìn)入分支和循環(huán)再開(kāi)始用 Flow。值得繼續(xù)深入研究的方向有三個(gè)一是 CrewAI 與 MCP 協(xié)議的集成方式這決定 Agent 能否接入企業(yè)內(nèi)外部豐富的工具生態(tài)二是多智能體系統(tǒng)的評(píng)測(cè)體系因?yàn)樗苯佑绊懩隳懿荒馨严到y(tǒng)從開(kāi)發(fā)環(huán)境穩(wěn)定遷移到生產(chǎn)環(huán)境三是記憶機(jī)制的設(shè)計(jì)什么時(shí)候需要短期記憶、什么時(shí)候用長(zhǎng)期記憶、什么時(shí)候干脆不要記憶需要基于業(yè)務(wù)做取舍。建議你把這篇文章收藏下來(lái)作為一個(gè)從零搭建多智能體系統(tǒng)的索引。遇到具體問(wèn)題比如模型調(diào)用失敗、任務(wù)上下文丟失、Agent 輸出格式不對(duì)優(yōu)先查第 7 節(jié)的排查表再回來(lái)看對(duì)應(yīng)章節(jié)的示例代碼。多智能體開(kāi)發(fā)是一條需要反復(fù)調(diào)試的路但只要你把基本概念和最小示例跑通了往后加角色、加任務(wù)、加工具都只是在這個(gè)框架里做增量擴(kuò)展而已。 CrewAI實(shí)戰(zhàn)指南：從零搭建多智能體協(xié)作工作流
如果你最近在關(guān)注 AI Agent 方向大概率會(huì)注意到一個(gè)現(xiàn)象ChatGPT 這類(lèi)單一大模型已經(jīng)不能滿(mǎn)足復(fù)雜任務(wù)的落地需求了。真正要做一份行業(yè)研究報(bào)告、一套競(jìng)品分析、一個(gè)自動(dòng)化運(yùn)營(yíng) SOP如果只靠一次 Prompt模型很快就會(huì)出現(xiàn)上下文丟失、步驟遺漏、結(jié)果深度不夠的問(wèn)題。于是“多智能體系統(tǒng)”這個(gè)概念被推到了臺(tái)前。但說(shuō)實(shí)話(huà)多智能體這個(gè)概念在業(yè)界的討論熱度遠(yuǎn)遠(yuǎn)超過(guò)了實(shí)際落地進(jìn)度。原因很簡(jiǎn)單大模型本身只是“大腦”而多智能體系統(tǒng)要解決的是“多個(gè)大腦如何分工、如何協(xié)作、如何把任務(wù)跑完”的系統(tǒng)工程問(wèn)題。很多人看完概念覺(jué)得懂了一寫(xiě)代碼就發(fā)現(xiàn)智能體怎么定義、任務(wù)怎么拆分、角色之間怎么交接、失敗怎么重試全是難題。這篇文章要寫(xiě)的 CrewAI就是目前開(kāi)源社區(qū)里把“多智能體協(xié)作”這個(gè)概念落地得比較完整的一套 Python 框架。它不要求你從零實(shí)現(xiàn) Agent 調(diào)度邏輯而是用類(lèi)聲明式的方式把智能體、任務(wù)、流程、協(xié)作工具組裝成一個(gè)可運(yùn)行的 Crew團(tuán)隊(duì)。文章的定位很明確不堆概念直接給你一條能跑通的主線(xiàn)——從 CrewAI 的核心設(shè)計(jì)講起到環(huán)境搭建、代碼示例、運(yùn)行驗(yàn)證、常見(jiàn)問(wèn)題最后給出工程落地建議。讀完你應(yīng)該能做到自己定義一個(gè)多角色智能體團(tuán)隊(duì)編排任務(wù)流程跑出一個(gè)真實(shí)可用的自動(dòng)化工作流。1. 這篇文章真正要解決的問(wèn)題先花一點(diǎn)時(shí)間搞清楚為什么在多智能體這個(gè)方向上我們特別需要 CrewAI 這種框架如果你自己嘗試過(guò)用 LangChain 或者直接調(diào)用 OpenAI SDK 寫(xiě) Agent你會(huì)發(fā)現(xiàn)真正的痛點(diǎn)不是讓模型“變聰明”而是把復(fù)雜任務(wù)結(jié)構(gòu)化。比如要做一個(gè)企業(yè)輿情分析報(bào)告任務(wù)天然包含以下環(huán)節(jié)采集信息源篩選高價(jià)值信息判斷情緒和風(fēng)險(xiǎn)等級(jí)撰寫(xiě)分析正文整理成固定格式的報(bào)告。如果只讓一個(gè) Agent 完成全部工作它既要會(huì)搜索、又要會(huì)寫(xiě)作、還要會(huì)判斷不僅系統(tǒng) Prompt 會(huì)寫(xiě)得非常長(zhǎng)而且任何一個(gè)環(huán)節(jié)失敗都會(huì)導(dǎo)致整條鏈路不可用。更麻煩的是這種單體 Agent 出現(xiàn)錯(cuò)誤時(shí)你很難定位是采集的問(wèn)題還是判斷邏輯的問(wèn)題還是生成格式的問(wèn)題。多智能體系統(tǒng)的核心價(jià)值就是把這種“大而全”的任務(wù)拆成多個(gè)“小而專(zhuān)”的角色任務(wù)。每個(gè)智能體只把自己負(fù)責(zé)的環(huán)節(jié)做到位再通過(guò)流程機(jī)制實(shí)現(xiàn)任務(wù)上下文傳遞和結(jié)果匯總。CrewAI 解決的問(wèn)題概括起來(lái)就是三件事智能體定義如何用清晰的角色Role、目標(biāo)Goal和背景故事Backstory定義一個(gè)專(zhuān)職智能體。任務(wù)編排如何把多個(gè)任務(wù)按順序、按層級(jí)或者按事件驅(qū)動(dòng)的方式串起來(lái)形成完整工作流?？蛇\(yùn)行的自動(dòng)化流程如何讓這套多智能體系統(tǒng)不僅存在于文檔里還能真正跑出結(jié)果并接入大模型 API、外部工具和企業(yè)數(shù)據(jù)。所以這篇文章適合的讀者有三類(lèi)。第一類(lèi)是剛開(kāi)始了解 Agent 開(kāi)發(fā)、想找一套能快速跑通的腳手架的人第二類(lèi)是已經(jīng)用 LangChain 寫(xiě)過(guò) Agent但覺(jué)得直接編排多角色太痛苦的人第三類(lèi)是團(tuán)隊(duì)里要評(píng)估多智能體框架選型需要看 CrewAI 到底能做什么、不能做什么的技術(shù)負(fù)責(zé)人。一句話(huà)總結(jié)我的判斷CrewAI 不是讓 AI 從“單打獨(dú)斗”變成“一堆 Agent 聊天”而是把多智能體協(xié)作變成了可配置、可復(fù)用、可維護(hù)的工程代碼。這種變化才是它真正值得關(guān)注的原因。2. CrewAI 核心概念與設(shè)計(jì)思想CrewAI 之所以上手門(mén)檻比從零寫(xiě)調(diào)度器低是因?yàn)樗讯嘀悄荏w系統(tǒng)中的幾個(gè)高頻抽象概念直接做成了框架的基礎(chǔ)組件。理解這幾個(gè)概念勝過(guò)背誦十篇 API 文檔。2.1 Crew、Agent、Task 是三大基礎(chǔ)組件CrewAI 的頂層抽象是 Crew團(tuán)隊(duì)/劇組它定義了一個(gè)多智能體組織負(fù)責(zé)管理這個(gè)系統(tǒng)里有哪些智能體、要執(zhí)行哪些任務(wù)、任務(wù)之間以什么方式流轉(zhuǎn)。Agent智能體是 Crew 里的執(zhí)行單元。每個(gè) Agent 是一個(gè)“帶角色設(shè)定的大模型實(shí)例”它擁有獨(dú)立的角色、目標(biāo)和背景信息。CrewAI 里的 Agent 還有一個(gè)重要特性它可以配置工具Tools比如搜索、網(wǎng)頁(yè)訪問(wèn)、自定義 Python 函數(shù)這樣它在執(zhí)行任務(wù)時(shí)就有能力調(diào)用外部資源。Task任務(wù)是分配給 Agent 的、明確要輸出結(jié)果的工作單元。Task 包含任務(wù)描述、期望輸出格式、負(fù)責(zé)任務(wù)的 Agent 等信息。多個(gè) Task 之間允許有依賴(lài)關(guān)系后置任務(wù)可以把前置任務(wù)的輸出作為輸入上下文。下面用一個(gè)表格把這幾個(gè)概念對(duì)照一下概念通俗理解解決的核心問(wèn)題CrewAI 中的關(guān)鍵配置Agent團(tuán)隊(duì)里的一個(gè)“員工”每個(gè)角色只做專(zhuān)業(yè)的事role、goal、backstory、llm、toolsTask安排給員工的一條工作指令工作邊界和輸出標(biāo)準(zhǔn)description、expected_output、agentCrew一條完整的業(yè)務(wù)流水線(xiàn)把角色和任務(wù)組裝成可運(yùn)行流程agents、tasks、processProcess流水線(xiàn)的執(zhí)行方式?jīng)Q定任務(wù)串行還是分級(jí)管理sequential、hierarchicalFlow基于事件驅(qū)動(dòng)的工作流控制器更靈活的編排與狀態(tài)管理start、listen、狀態(tài)對(duì)象只看表格可能還不夠“切膚”。要理解這些概念最好的方式是把 CrewAI 比作一個(gè)劇組導(dǎo)演Flow 或 Hierarchical Process 中的 Manager不親自演戲但決定哪個(gè)演員在什么節(jié)點(diǎn)上場(chǎng)。編劇和攝影師Agent是不同的執(zhí)行單元編劇寫(xiě)腳本攝影師拍畫(huà)面。每個(gè)拍攝任務(wù)Task都有明確交付物。整部電影Crew是以上所有元素的集合。當(dāng)然這個(gè)類(lèi)比只是為了幫新手建立心智模型。真正寫(xiě)代碼時(shí)Agent 不會(huì)像人一樣“商量”著干活它靠的是結(jié)構(gòu)化 Prompt、工具調(diào)用和任務(wù)上下文傳遞。2.2 Process 決定協(xié)作是順序還是分級(jí)多智能體系統(tǒng)里最容易讓人困惑的一點(diǎn)是多個(gè)智能體到底怎么協(xié)作是我命令你、你命令他還是大家各干各的最后拼在一起CrewAI 提供兩種內(nèi)置 ProcessSequential Process順序流程。所有任務(wù)按聲明順序依次執(zhí)行Agent 像流水線(xiàn)工人一樣逐個(gè)處理自己負(fù)責(zé)的環(huán)節(jié)。優(yōu)點(diǎn)是好理解、好排錯(cuò)、成本和延遲可控。適合上下文強(qiáng)依賴(lài)、不適合并行的任務(wù)鏈。比如“先生成大綱再根據(jù)大綱寫(xiě)正文再基于正文配摘要”。Hierarchical Process層級(jí)流程。Crew 里會(huì)安排一個(gè) Manager Agent 或指定 manager_llm由它負(fù)責(zé)任務(wù)規(guī)劃、分配、審查和交接普通 Task 不預(yù)先綁定 Agent而是由 Manager 動(dòng)態(tài)決定。優(yōu)點(diǎn)是有全局統(tǒng)籌適合任務(wù)拆解不固定、依賴(lài)關(guān)系相對(duì)動(dòng)態(tài)的場(chǎng)景。缺點(diǎn)是多一次管理調(diào)度會(huì)引入額外的大模型調(diào)用開(kāi)銷(xiāo)和不確定性。社區(qū)里經(jīng)常討論“多智能體的四種交互模式”典型分類(lèi)包括順序鏈、并行分組、主從委派、事件驅(qū)動(dòng)協(xié)作等。對(duì)應(yīng)到 CrewAI 里順序模式對(duì)應(yīng) Sequential Process主從委派對(duì)應(yīng) Hierarchical Process事件驅(qū)動(dòng)模式對(duì)應(yīng)基于 Flow 的編排方式并行分組可以通過(guò)多個(gè)異步 Task 來(lái)組合實(shí)現(xiàn)。換句話(huà)說(shuō)你不需要把這些模式當(dāng)作孤立術(shù)語(yǔ)它們的本質(zhì)是任務(wù)關(guān)系圖的結(jié)構(gòu)差異。2.3 Flow比 Process 更靈活的工作流層Process 解決了一個(gè) Crew 內(nèi)部任務(wù)的線(xiàn)性和層級(jí)調(diào)度問(wèn)題但真實(shí)業(yè)務(wù)往往沒(méi)有這么規(guī)整。你會(huì)發(fā)現(xiàn)很多自動(dòng)化流程是循環(huán)的、條件是跳轉(zhuǎn)的、不同 Crew 之間需要嵌套調(diào)用。CrewAI 的 Flow 組件就是為這種場(chǎng)景設(shè)計(jì)的。Flow 允許你定義一個(gè)帶狀態(tài)的數(shù)據(jù)類(lèi)通過(guò)start()裝飾器標(biāo)注流程的起點(diǎn)通過(guò)listen()裝飾器監(jiān)聽(tīng)某個(gè)方法完成后觸發(fā)下一個(gè)動(dòng)作。這種事件驅(qū)動(dòng)機(jī)制可以處理?xiàng)l件分流根據(jù)某個(gè)步驟輸出決定走 A 分支還是 B 分支流程合并幾個(gè)獨(dú)立結(jié)果匯聚到一個(gè)最終總結(jié)步驟父子流程一個(gè) Flow 內(nèi)部調(diào)用另一個(gè)已經(jīng)定義好的 Crew。如果你之前用過(guò)自動(dòng)化測(cè)試框架或者數(shù)據(jù)管道調(diào)度框架Flow 的概念不會(huì)陌生。它本質(zhì)上就是用裝飾器和狀態(tài)對(duì)象來(lái)描述有向無(wú)環(huán)圖DAG。2.4 一個(gè)容易被忽略的設(shè)計(jì)Agent 的 Post-Tools很多新手用 CrewAI 時(shí)會(huì)有一個(gè)誤區(qū)Agent 收到任務(wù)后會(huì)自動(dòng)“思考”然后調(diào)用工具。實(shí)際上Agent 是否調(diào)用工具、調(diào)用什么工具取決于你在創(chuàng)建 Agent 時(shí)傳給它的tools參數(shù)以及任務(wù)的描述是否明確提示它需要使用工具。CrewAI 官方還有一個(gè)Agent的post_tools參數(shù)策略就是讓 Agent 在正式回答前先調(diào)用一組工具來(lái)增強(qiáng)信息避免“不知道答案也硬編”。這里不展開(kāi)細(xì)節(jié)但你要記住一個(gè)原則在這類(lèi)多智能體系統(tǒng)里工具的掛載位置會(huì)直接影響任務(wù)質(zhì)量——工具掛得太少Agent 只能靠模型幻覺(jué)補(bǔ)充信息工具掛得太多Agent 容易在無(wú)關(guān)工具上浪費(fèi) Token 和時(shí)間。3. 適用場(chǎng)景與框架選型CrewAI 到底適合什么多智能體框架目前不是一個(gè)贏者通吃的賽道。選型錯(cuò)誤往往不是框架的問(wèn)題而是需求和框架的匹配出了問(wèn)題。因此在寫(xiě)代碼之前值得先把選型問(wèn)題理清楚。先看 LangChain。LangChain 是 Agent 開(kāi)發(fā)的“瑞士軍刀”它提供了組件化的工具鏈和大量第三方集成但它本身不定義任務(wù)協(xié)作模型。如果你想基于 LangChain 寫(xiě)多智能體協(xié)作自己需要設(shè)計(jì) Agent 之間的通信協(xié)議、記憶共享、任務(wù)分配機(jī)制實(shí)際上是從零搭一套框架。再看 AutoGen 或 Semantic Kernel。這類(lèi)框架擅長(zhǎng)對(duì)話(huà)驅(qū)動(dòng)的多智能體交互多個(gè) Agent 通過(guò)消息傳遞完成合作。這在研究、對(duì)話(huà)式推理場(chǎng)景里很有優(yōu)勢(shì)但業(yè)務(wù)落地上Agent 之間自由對(duì)話(huà)往往意味著不確定性高、調(diào)試?yán)щy輸出格式也較難約束。CrewAI 的定位恰好介于兩者之間。它更接近“結(jié)構(gòu)化團(tuán)隊(duì)協(xié)作”用 Crew、Task、Process 這種有邊界的模型把任務(wù)編排固化成代碼。你定義角色定義任務(wù)框架幫你執(zhí)行任務(wù)結(jié)果結(jié)構(gòu)化可控性強(qiáng)容易復(fù)用。對(duì)比維度LangChain AgentAutoGenCrewAI核心抽象Chain Agent ToolConversable Agent 對(duì)話(huà)流Crew Agent Task Process多智能體協(xié)作方式需要自行設(shè)計(jì)對(duì)話(huà)驅(qū)動(dòng)聲明 流程驅(qū)動(dòng)任務(wù)結(jié)果可控性中等偏低較高上手難度中等偏高較低適合業(yè)務(wù)場(chǎng)景工具鏈復(fù)雜、組件化集成研究探索、開(kāi)放對(duì)話(huà)企業(yè)流程自動(dòng)化、內(nèi)容生產(chǎn)流水線(xiàn)那 CrewAI 最適合哪些場(chǎng)景根據(jù)實(shí)際項(xiàng)目經(jīng)驗(yàn)我可以給出幾個(gè)比較明確的場(chǎng)景清單。第一個(gè)是內(nèi)容與研究報(bào)告生產(chǎn)流水線(xiàn)。比如收集資料、整理觀點(diǎn)、撰寫(xiě)初稿、校對(duì)優(yōu)化如果把這幾個(gè)環(huán)節(jié)拆成專(zhuān)職 Agent配合固定的任務(wù)輸出格式產(chǎn)出質(zhì)量會(huì)明顯高于單 Agent 長(zhǎng)文本生成。第二個(gè)是企業(yè)業(yè)務(wù)運(yùn)營(yíng)自動(dòng)化。例如客服工單分類(lèi)、競(jìng)品監(jiān)控日?qǐng)?bào)、銷(xiāo)售線(xiàn)索初篩。這類(lèi)任務(wù)有清晰輸入輸出有固定流程非常適合用 Crew 封裝成可重復(fù)調(diào)用的服務(wù)。第三個(gè)是多工具編排場(chǎng)景。CrewAI Agent 支持掛載工具你能把搜索工具、數(shù)據(jù)庫(kù)查詢(xún)工具、內(nèi)部 API 工具掛到不同 Agent 上讓它們各司其職。不太適合 CrewAI 的場(chǎng)景也有一個(gè)典型高實(shí)時(shí)性、強(qiáng)交互的對(duì)話(huà)助手。CrewAI 本身不是對(duì)話(huà)狀態(tài)管理框架它有 Memory 和短期上下文設(shè)計(jì)但面向用戶(hù)的多輪對(duì)話(huà)系統(tǒng)還是應(yīng)該用專(zhuān)門(mén)對(duì)話(huà) Agent 框架來(lái)做把 CrewAI 作為服務(wù)端內(nèi)部任務(wù)編排組件。換言之不要讓用戶(hù)直接和 CrewAI 的 Agent 自由對(duì)話(huà)而是通過(guò) API 去觸發(fā)一個(gè)明確的 Crew 工作流。4. 環(huán)境準(zhǔn)備與工程目錄設(shè)計(jì)在動(dòng)手寫(xiě)代碼之前先把運(yùn)行環(huán)境說(shuō)清楚。CrewAI 是一個(gè)基于 Python 的框架底層封裝了 LangChain 的若干能力同時(shí)支持 OpenAI、Anthropic、Gemini、Ollama 等不同模型來(lái)源。我建議你在一個(gè)干凈的環(huán)境中安裝避免跟已有 LangChain 項(xiàng)目里的依賴(lài)發(fā)生版本沖突。建議環(huán)境如下Python 3.10 或更高版本推薦 3.10 到 3.12具體以官方當(dāng)前支持版本為準(zhǔn)pip 包管理器一個(gè)可選用的虛擬環(huán)境工具比如 venv 或 conda準(zhǔn)備一個(gè)大模型 API Key。如果你用 OpenAI 兼容接口可以配置OPENAI_API_KEY環(huán)境變量。安裝 CrewAI 的命令很簡(jiǎn)單pip install crewai如果計(jì)劃讓 Agent 使用瀏覽器搜索、網(wǎng)頁(yè)內(nèi)容讀取等常用工具可以一起安裝工具包pip install crewai[tools]CrewAI 生態(tài)迭代速度較快重要版本的 API 可能有調(diào)整因此creai的具體版本號(hào)建議以官方 PyPI 頁(yè)面為準(zhǔn)。本文的代碼示例以當(dāng)前主流的類(lèi)聲明式用法為主。安裝完成后可以先做一個(gè)最小驗(yàn)證python -c import crewai; print(crewai.__version__)如果這條命令能正常輸出版本號(hào)說(shuō)明框架安裝沒(méi)問(wèn)題。工程目錄方面如果你只是學(xué)習(xí)跑通建議先建一個(gè)單文件腳本如果是正式業(yè)務(wù)項(xiàng)目我更推薦這樣的目錄結(jié)構(gòu)project/ ├── agents/ │ └── researcher_agent.py # 智能體定義 ├── tasks/ │ └── research_task.py # 任務(wù)定義 ├── crews/ │ ├── research_crew.py # 組裝 Crew │ └── flow.py # 基于 Flow 的工作流 ├── tools/ │ ├── search_tool.py │ └── custom_tool.py ├── config/ │ └── llm_config.py # 模型統(tǒng)一配置 ├── output/ │ └── reports/ ├── main.py # 入口 └── requirements.txt這種拆分方式的好處是智能體、任務(wù)、流程互相解耦。一個(gè) Agent 可以參與不同 Task一個(gè) Task 也可以在不同 Crew 里復(fù)用將來(lái)接入 Web 服務(wù)時(shí)只需要在 API 層調(diào)用Crew.kickoff()整個(gè)業(yè)務(wù)能力就被封裝成函數(shù)了。實(shí)際項(xiàng)目里我更建議把智能體定義和任務(wù)描述放到配置文件里管理代碼里只負(fù)責(zé)注冊(cè)和組裝。CrewAI 也支持 YAML 配置方式對(duì)團(tuán)隊(duì)協(xié)作和后續(xù)維護(hù)更友好。不過(guò)本文為了減少認(rèn)知負(fù)擔(dān)直接用 Python 代碼描述。5. CrewAI 完整示例從最小 Crew 到事件驅(qū)動(dòng) Flow下面開(kāi)始進(jìn)入實(shí)操環(huán)節(jié)。我們從最簡(jiǎn)單的一 Crew 一 Agent 開(kāi)始逐步增加角色和任務(wù)最后用一個(gè) Flow 示例演示事件驅(qū)動(dòng)工作流。5.1 最小示例研究助手 Crew先跑通最小環(huán)境。創(chuàng)建一個(gè)first_crew.py文件代碼如下# 文件路徑first_crew.py from crewai import Agent, Task, Crew, Process # 1. 定義智能體 researcher Agent( role高級(jí)技術(shù)研究員, goal圍繞用戶(hù)給定主題調(diào)研技術(shù)原理并形成結(jié)構(gòu)化摘要, backstory( 你是一位經(jīng)驗(yàn)豐富的技術(shù)研究員 擅長(zhǎng)快速?gòu)馁Y料中提煉關(guān)鍵事實(shí) 不喜歡無(wú)依據(jù)的推測(cè)。 ), verboseTrue ) # 2. 定義任務(wù) research_task Task( description調(diào)研 CrewAI 的核心概念輸出一份面向開(kāi)發(fā)者的摘要。, expected_output( 一份包含核心概念、主要用途、適用場(chǎng)景的 Markdown 列表 每項(xiàng)不超過(guò) 50 字。 ), agentresearcher, ) # 3. 組裝 Crew crew Crew( agents[researcher], tasks[research_task], processProcess.sequential, verboseTrue, ) if __name__ __main__: result crew.kickoff() print( 最終輸出 ) print(result)這里需要解釋幾個(gè)關(guān)鍵參數(shù)。Agent里的role設(shè)置了智能體的角色身份goal設(shè)定了總體目標(biāo)backstory是給大模型的背景補(bǔ)全信息這三者拼在一起實(shí)際構(gòu)成了 Agent 系統(tǒng)提示詞的核心。verboseTrue表示在命令行輸出任務(wù)執(zhí)行的中間過(guò)程排錯(cuò)時(shí)非常有用。Task里的description是任務(wù)內(nèi)容expected_output是期望的輸出結(jié)構(gòu)和風(fēng)格。多智能體系統(tǒng)里任務(wù)描述寫(xiě)得好不好決定了大模型和下游協(xié)作者能不能理解結(jié)果。這塊不要偷懶。Crew接收agents列表和tasks列表processProcess.sequential表示順序執(zhí)行。kickoff()是 Crew 的入口函數(shù)調(diào)用后框架會(huì)自動(dòng)拉起整個(gè)流程。運(yùn)行方式python first_crew.py如果配置好了大模型 API你會(huì)看到控制臺(tái)依次輸出 Agent 的思考步驟、工具調(diào)用和最終結(jié)果。kickoff()返回的對(duì)象是 CrewOutput直接print(result)可以看見(jiàn)任務(wù)輸出正文。5.2 順序編排內(nèi)容生產(chǎn)流水線(xiàn)下面把場(chǎng)景升級(jí)用三個(gè) Agent 組成一條內(nèi)容生產(chǎn)流水線(xiàn)分工做“選題策劃 → 初稿撰寫(xiě) → 校對(duì)潤(rùn)色”。# 文件路徑content_crew.py from crewai import Agent, Task, Crew, Process planner Agent( role內(nèi)容策劃編輯, goal根據(jù)主題規(guī)劃文章大綱和核心觀點(diǎn), backstory你是一位資深內(nèi)容策劃善于把復(fù)雜技術(shù)問(wèn)題拆解成清晰的文章結(jié)構(gòu)。, ) writer Agent( role技術(shù)文章作者, goal根據(jù)大綱撰寫(xiě)技術(shù)教程正文, backstory你是一位有一線(xiàn)開(kāi)發(fā)經(jīng)驗(yàn)的技術(shù)作者擅長(zhǎng)用示例和步驟講清楚概念。, ) reviewer Agent( role質(zhì)量審核編輯, goal從準(zhǔn)確性、結(jié)構(gòu)完整性和表達(dá)清晰度方面審核文章輸出修改建議, backstory你是一位嚴(yán)格的編輯重點(diǎn)檢查文章是否存在術(shù)語(yǔ)誤用、邏輯斷裂和缺少示例。, ) plan_task Task( description( 主題如何使用 Python 實(shí)現(xiàn)定時(shí)任務(wù)。 請(qǐng)輸出文章大綱包括引言、環(huán)境準(zhǔn)備、核心示例、常見(jiàn)問(wèn)題四部分。 ), expected_output結(jié)構(gòu)化的 Markdown 大綱每個(gè)章節(jié)下寫(xiě)清楚要點(diǎn)。, agentplanner, ) write_task Task( description( 基于以下大綱撰寫(xiě)技術(shù)教程正文\n {plan_output}\n 要求每段給出可運(yùn)行的代碼示例語(yǔ)言風(fēng)格平實(shí)、專(zhuān)業(yè)。 ), expected_output完整的 Markdown 技術(shù)文章正文包含代碼塊。, agentwriter, context[plan_task] ) review_task Task( description( 審核以下技術(shù)文章檢查內(nèi)容準(zhǔn)確性和結(jié)構(gòu)\n {write_output}\n 輸出具體修改建議不要直接重寫(xiě)全文。 ), expected_output按嚴(yán)重程度排序的修改建議列表。, agentreviewer, context[write_task] ) content_crew Crew( agents[planner, writer, reviewer], tasks[plan_task, write_task, review_task], processProcess.sequential, verboseTrue, ) if __name__ __main__: result content_crew.kickoff() print( 審核建議 ) print(result)這個(gè)示例里有幾個(gè)關(guān)鍵點(diǎn)值得展開(kāi)。第一個(gè)是context參數(shù)。write_task聲明了context[plan_task]意思是它執(zhí)行時(shí)會(huì)把plan_task的輸出作為上下文傳入。review_task同理依賴(lài)write_task的輸出。相比直接使用{plan_output}這種變量占位context更明確地建立了任務(wù)級(jí)依賴(lài)關(guān)系。實(shí)際上CrewAI 在 Task 執(zhí)行時(shí)會(huì)把 context 中任務(wù)的輸出拼到當(dāng)前任務(wù)描述后面因此你可以在任務(wù)描述里用大括號(hào)引用。如果任務(wù)之間沒(méi)有顯式依賴(lài)就不要亂加context減少不必要的 Token 消耗。第二個(gè)是任務(wù)描述里的占位符寫(xiě)法。{plan_output}是引用前序任務(wù)輸出的快捷方式。用不熟悉的開(kāi)發(fā)者很容易忽略這一點(diǎn)導(dǎo)致下游任務(wù)拿不到上游結(jié)果。第三點(diǎn)是Process.sequential只負(fù)責(zé)按列表順序執(zhí)行任務(wù)它不代表“每個(gè) Agent 都只執(zhí)行一次任務(wù)”。框架內(nèi)部會(huì)協(xié)調(diào)上下文你只需要定義清楚哪些角色、哪些任務(wù)、哪些依賴(lài)。運(yùn)行內(nèi)容生產(chǎn) Crew 后你會(huì)看到作者 Agent 產(chǎn)出初稿審核 Agent 對(duì)初稿給出意見(jiàn)。如果你希望把審核意見(jiàn)直接應(yīng)用到文章里只需要再增加一個(gè)編輯 Agent 和對(duì)應(yīng) Task承接修改任務(wù)即可。這就是流水線(xiàn)編排的威力每增加一個(gè)環(huán)節(jié)只是新增一個(gè)角色和一條任務(wù)。5.3 層級(jí)流程Manager 統(tǒng)籌模式業(yè)務(wù)場(chǎng)景里還有一種更常見(jiàn)的情況任務(wù)不是一開(kāi)始就能寫(xiě)死成固定步驟的需要根據(jù)實(shí)際內(nèi)容動(dòng)態(tài)拆解。比如“調(diào)研某技術(shù)方向的趨勢(shì)并輸出報(bào)告”具體要訪問(wèn)哪些網(wǎng)站、要看哪些材料不應(yīng)該是我們預(yù)先硬編碼的而應(yīng)該由一個(gè)統(tǒng)管 Agent 來(lái)判斷。這種場(chǎng)景適合用 Hierarchical Process。# 文件路徑hierarchical_crew.py from crewai import Agent, Task, Crew, Process researcher Agent( role前沿技術(shù)觀察員, goal搜集指定技術(shù)方向的最新動(dòng)態(tài)與發(fā)展趨勢(shì), backstory你長(zhǎng)期跟蹤 AI 工程化領(lǐng)域動(dòng)態(tài)善于發(fā)現(xiàn)關(guān)鍵信號(hào)。, ) analyst Agent( role商業(yè)技術(shù)分析師, goal對(duì)收集到的信息進(jìn)行結(jié)構(gòu)化分析并形成判斷, backstory你擅長(zhǎng)從分散信息中歸納趨勢(shì)給技術(shù)決策者提供可執(zhí)行的結(jié)論。, ) report_task Task( description調(diào)研多智能體編排框架的行業(yè)采用趨勢(shì)并輸出一份分析簡(jiǎn)報(bào)。, expected_output包含關(guān)鍵趨勢(shì)、代表項(xiàng)目、落地建議的 Markdown 簡(jiǎn)報(bào)。, ) hierarchical_crew Crew( agents[researcher, analyst], tasks[report_task], processProcess.hierarchical, manager_llmNone, # 不顯式指定時(shí)會(huì)復(fù)用默認(rèn) LLM manager_agentNone, # 也可以指定一個(gè) Agent 作為 Manager verboseTrue, ) if __name__ __main__: result hierarchical_crew.kickoff() print( 層級(jí)流程輸出 ) print(result)注意在層級(jí)流程的寫(xiě)法里report_task沒(méi)有綁定agent參數(shù)。這是因?yàn)樵?Hierarchical Process 中負(fù)責(zé)任務(wù)分配的 Manager 會(huì)動(dòng)態(tài)決定把 Task 交給哪個(gè) Agent 執(zhí)行不需要預(yù)先綁定。你需要提供的是 Agent 池Manager 從池中選擇合適的執(zhí)行者。如果你希望 Manager 既當(dāng)裁判又當(dāng)運(yùn)動(dòng)員可以顯式傳入一個(gè)manager_agent如果只告訴 Crew 用哪個(gè)模型做管理就傳manager_llm。二者選擇其一即可。實(shí)際生產(chǎn)環(huán)境中為避免 Manager 模型和執(zhí)行 Agent 模型混用導(dǎo)致成本難以核算更推薦用manager_llm指定一個(gè)更高配置的模型執(zhí)行 Agent 使用相對(duì)輕量的模型。用層級(jí)流程時(shí)要注意 Token 消耗。Manager 的每一步規(guī)劃、審查、總結(jié)都會(huì)調(diào)用大模型。任務(wù)一多成本會(huì)顯著上升。如果業(yè)務(wù)步驟固定、拆解明確優(yōu)先使用順序流程層級(jí)流程作為兜底和補(bǔ)充。5.4 自定義工具讓 Agent 不再只靠記憶多智能體 Agent 真正落地一般離不開(kāi)工具調(diào)用能力。一個(gè)只靠模型內(nèi)部知識(shí)回答問(wèn)題的 Agent本質(zhì)上還是一個(gè)高級(jí)聊天機(jī)器人只有讓它可以查詢(xún)數(shù)據(jù)庫(kù)、調(diào)內(nèi)部接口、搜索網(wǎng)頁(yè)它才算進(jìn)入工作流。CrewAI 的 Agent 通過(guò)tools參數(shù)掛載工具工具可以是內(nèi)置的serper_dev_tool、scrape_website_tool也可以是自己寫(xiě)的一個(gè)普通 Python 函數(shù)再包裝成tool裝飾器。演示一個(gè)自定義工具。假設(shè)我們需要讓 Agent 查詢(xún)本地配置好的知識(shí)庫(kù) API# 文件路徑knowledge_tool.py from crewai_tools import tool tool(知識(shí)庫(kù)搜索) def search_knowledge_base(query: str) - str: 在內(nèi)部知識(shí)庫(kù)中搜索與 query 相關(guān)的知識(shí)內(nèi)容。 如果未找到返回 NO_RESULT。 # 實(shí)際項(xiàng)目中這里會(huì)調(diào)用內(nèi)部知識(shí)庫(kù) API 或向量數(shù)據(jù)庫(kù) # 這里只做演示使用一個(gè)簡(jiǎn)單映射表 knowledge { 部署: 生產(chǎn)環(huán)境部署前必須備份數(shù)據(jù)庫(kù)并執(zhí)行回歸測(cè)試。, 回滾: 回滾操作優(yōu)先使用上一穩(wěn)定版本鏡像并觀察監(jiān)控指標(biāo)。, } for key, value in knowledge.items(): if key in query: return value return NO_RESULT然后掛載到 Agent 上# 文件路徑tool_crew.py from crewai import Agent, Task, Crew, Process from knowledge_tool import search_knowledge_base ops_agent Agent( role運(yùn)維知識(shí)顧問(wèn), goal回答基于內(nèi)部知識(shí)庫(kù)的運(yùn)維問(wèn)題, backstory你只能依據(jù)內(nèi)部知識(shí)庫(kù)回答不要憑空補(bǔ)充沒(méi)有來(lái)源的操作步驟。, tools[search_knowledge_base], ) answer_task Task( description請(qǐng)回答生產(chǎn)環(huán)境部署時(shí)的注意事項(xiàng)有哪些, expected_output一段不超過(guò) 100 字的安全操作建議。, agentops_agent, ) tool_crew Crew( agents[ops_agent], tasks[answer_task], verboseTrue, ) if __name__ __main__: result tool_crew.kickoff() print(result)這里一個(gè)關(guān)鍵細(xì)節(jié)是tool裝飾器里的函數(shù)文檔字符串。大模型并不是靠你的“函數(shù)名”理解工具的它靠的是函數(shù)簽名、參數(shù)說(shuō)明、文檔字符串綜合判斷何時(shí)調(diào)用該工具。因此工具描述要寫(xiě)清楚“什么場(chǎng)景用、輸入什么、返回什么、找不到時(shí)返回什么”。一個(gè)含糊的工具描述很可能讓 Agent 在無(wú)關(guān)請(qǐng)求上頻繁調(diào)用工具消耗大量 Token。這里也回應(yīng)一個(gè)網(wǎng)絡(luò)熱詞很多人問(wèn)“如何把小龍蝦或者愛(ài)馬仕集成到多智能體系統(tǒng)中”其實(shí)當(dāng)一個(gè) Agent 能通過(guò) MCPModel Context Protocol等協(xié)議掛載外部工具時(shí)重點(diǎn)不是對(duì)象本身叫什么名字而是它暴露了什么工具接口、返回什么格式的數(shù)據(jù)。真正值得研究的是 MCP 服務(wù)器如何把業(yè)務(wù)數(shù)據(jù)抽象成 Agent 可調(diào)用的工具。5.5 事件驅(qū)動(dòng)工作流基于 Flow 實(shí)現(xiàn)動(dòng)態(tài)編排前幾個(gè)示例里的 Process 都是把一個(gè) Crew 內(nèi)部的任務(wù)按固定方式跑完。如果業(yè)務(wù)包含多個(gè) Crew、條件分支或循環(huán)處理就要用 Flow。下面這段代碼演示一個(gè)“熱點(diǎn)內(nèi)容自動(dòng)加工”流程收到主題后先生成研究摘要如果摘要長(zhǎng)度不夠走增強(qiáng)補(bǔ)充路徑最后匯總輸出。# 文件路徑research_flow.py from typing import Any from pydantic import BaseModel from crewai.flow import Flow, listen, start from crewai import Agent, Task, Crew, Process class ResearchState(BaseModel): topic: str 人工智能編排框架 raw_summary: str final_summary: str need_expand: bool False class ResearchFlow(Flow[ResearchState]): start() def initiate_research(self): # 首輪 Agent 執(zhí)行快速生成摘要 agent Agent( role行業(yè)研究員, goal快速生成指定主題的研究摘要, backstory你擅長(zhǎng)快速判斷主題的核心脈絡(luò)。, ) task Task( descriptionf圍繞主題《{self.state.topic}》生成 150 字以?xún)?nèi)摘要。, expected_output一段簡(jiǎn)潔摘要。, agentagent, ) crew Crew(agents[agent], tasks[task], processProcess.sequential) self.state.raw_summary crew.kickoff().raw # 判斷是否需要擴(kuò)展比如摘要是否過(guò)短 self.state.need_expand len(self.state.raw_summary) 50 listen(initiate_research) def expand_if_needed(self): if not self.state.need_expand: return # 第二輪覆蓋針對(duì)缺失細(xì)節(jié)做補(bǔ)充 agent Agent( role細(xì)節(jié)補(bǔ)充編輯, goal對(duì)短摘要進(jìn)行事實(shí)擴(kuò)充, backstory你是嚴(yán)謹(jǐn)?shù)木庉嬔a(bǔ)充內(nèi)容必須與摘要主題一致。, ) task Task( descriptionf基于摘要《{self.state.raw_summary}》擴(kuò)展成 300 字左右的完整段落。, expected_output一段內(nèi)容完整、信息密度高的文字。, agentagent, ) crew Crew(agents[agent], tasks[task], processProcess.sequential) self.state.final_summary crew.kickoff().raw listen(expand_if_needed) def finalize(self, output: Any): # 如果沒(méi)有經(jīng)過(guò)擴(kuò)展final_summary 為空這里兜底賦值 if not self.state.final_summary: self.state.final_summary self.state.raw_summary print( 最終研究結(jié)果 ) print(self.state.final_summary) if __name__ __main__: flow ResearchFlow() flow.kickoff()這段代碼里Flow 的用法主要通過(guò)裝飾器和狀態(tài)對(duì)象完成繼承Flow[ResearchState]ResearchState繼承了pydantic.BaseModel用來(lái)定義整個(gè) Flow 運(yùn)行期間的狀態(tài)字段。start()標(biāo)記的initiate_research是入口方法任何流程只能有一個(gè)或多個(gè)入口它們是 Flow 的開(kāi)始。listen(initiate_research)表示監(jiān)聽(tīng)某個(gè)方法執(zhí)行完后的結(jié)果。只有前一個(gè)方法執(zhí)行成功被監(jiān)聽(tīng)的方法才會(huì)執(zhí)行。狀態(tài)對(duì)象self.state負(fù)責(zé)在多個(gè)方法之間傳遞數(shù)據(jù)。這樣一來(lái)MCP 調(diào)用、Crew 執(zhí)行、分支判斷等都變成了方法之間的數(shù)據(jù)流動(dòng)整體更接近傳統(tǒng)后端工程師熟悉的 Service 代碼。Flow 是 CrewAI 新版本里力推的編排層但不是說(shuō)每個(gè)項(xiàng)目都必須用它。如果是固定順序的 3 到 5 個(gè)步驟直接用Crew.kickoff()就夠了如果流程里有分支、循環(huán)、嵌套多個(gè) Crew建議升級(jí)到 Flow。6. 運(yùn)行驗(yàn)證與判斷標(biāo)準(zhǔn)跑通代碼只是第一步。真正需要注意的是你怎么判斷多智能體系統(tǒng)的運(yùn)行結(jié)果是“成功”的。6.1 命令行運(yùn)行觀察什么當(dāng)verboseTrue時(shí)CrewAI 會(huì)在控制臺(tái)打印每個(gè) Agent 的執(zhí)行過(guò)程。不同 Agent 完成任務(wù)后你會(huì)看到類(lèi)似這樣的輸出結(jié)構(gòu)任務(wù)開(kāi)始提示Agent 正在處理的任務(wù)描述思考過(guò)程Agent 如何理解任務(wù)工具調(diào)用與觀察結(jié)果如果調(diào)用了工具會(huì)顯示工具輸入和返回值任務(wù)最終輸出Agent 的最終回答。如果某個(gè)環(huán)節(jié)的輸出明顯不符合任務(wù)描述中的要求比如“本應(yīng)輸出 Markdown 列表實(shí)際輸出了純文本”這就說(shuō)明任務(wù)描述不夠嚴(yán)格。所有任務(wù)描述都必須顯式聲明 expected_output否則大模型不知道交付標(biāo)準(zhǔn)結(jié)果會(huì)非常不穩(wěn)定。6.2 結(jié)果判斷的三種方式第一種是人工閱讀。適合調(diào)研報(bào)告、內(nèi)容生產(chǎn)判斷標(biāo)準(zhǔn)是信息準(zhǔn)確、邏輯清晰、沒(méi)有幻覺(jué)。第二種是結(jié)構(gòu)化字段校驗(yàn)。適合數(shù)據(jù)抽取、分類(lèi)、工單處理?？梢园裈ask配置output_pydantic或output_json讓 Agent 輸出 JSON 格式然后在Crew.kickoff()返回結(jié)果中用 Pydantic 模型校驗(yàn)字段完整性和類(lèi)型。第三種是外部斷言。適合自動(dòng)化任務(wù)比如 Agent 判斷“某事件風(fēng)險(xiǎn)等級(jí)為高危”下游系統(tǒng)再拿著這個(gè)結(jié)論觸發(fā)不同告警通過(guò)業(yè)務(wù)規(guī)則確保輸出被正確消費(fèi)。6.3 第一優(yōu)先級(jí)看的失敗點(diǎn)如果運(yùn)行失敗不要急著改 Prompt。先按以下順序排查看 API Key 是否配置、是否欠費(fèi)或限流。這是大多數(shù)第一次運(yùn)行失敗的根因。看依賴(lài)版本。CrewAI 與 LangChain 生態(tài)版本耦合較緊升級(jí)某個(gè)包可能導(dǎo)致內(nèi)部接口不兼容?？慈蝿?wù)之間的上下文變量名是否正確。占位符寫(xiě)錯(cuò)不會(huì)直接報(bào)錯(cuò)但會(huì)輸出原始字符串到下游?？磛erbose日志里 Agent 最后執(zhí)行到哪個(gè)節(jié)點(diǎn)。如果某個(gè) Agent 從頭到尾沒(méi)有輸出大概率是它的任務(wù)描述沒(méi)有進(jìn)到 Agent 的執(zhí)行上下文。7. CrewAI 常見(jiàn)問(wèn)題與排查思路我整理了多智能體開(kāi)發(fā)過(guò)程中出現(xiàn)頻率最高的幾個(gè)問(wèn)題。這張表可以直接作為你排錯(cuò)時(shí)的檢查單。問(wèn)題現(xiàn)象可能原因排查方式解決方案第一次運(yùn)行報(bào)錯(cuò) 401/429API Key 錯(cuò)誤、額度不足或觸發(fā)限流單獨(dú)調(diào)用模型 SDK 驗(yàn)證 Key檢查賬號(hào)余額更新 Key提高限流閾值或切換模型供應(yīng)商Agent 沒(méi)有調(diào)用工具工具描述不清晰或任務(wù)描述未提示工具查看 verbose 日志中 Agent 是否“考慮”過(guò)工具調(diào)用的可能性?xún)?yōu)化工具描述在任務(wù)描述里明確“允許使用知識(shí)庫(kù)搜索”流程中途報(bào)錯(cuò)“Could not parse LLM output”大模型返回內(nèi)容不滿(mǎn)足 JSON、代碼塊等結(jié)構(gòu)化要求查看報(bào)錯(cuò)前后 LLM 原文確認(rèn)是否超過(guò)上下文長(zhǎng)度縮小任務(wù)粒度配置output_json或output_pydantic更換更強(qiáng)模型下游任務(wù)引用了空上下文context 任務(wù)未執(zhí)行或任務(wù)描述中變量名寫(xiě)錯(cuò)先獨(dú)立運(yùn)行上游任務(wù)確認(rèn)輸出非空檢查引用變量名檢查 Task 列表順序和 context 關(guān)系任務(wù)結(jié)果很好但耗時(shí)太長(zhǎng)/費(fèi)用過(guò)高任務(wù)鏈過(guò)長(zhǎng)、層級(jí) Manager 反復(fù)調(diào)度、Agent 反復(fù)重試在 verbose 日志中統(tǒng)計(jì)每個(gè)環(huán)節(jié)步數(shù)查看 API 用量面板減少 Agent 數(shù)量用順序流程替代層級(jí)流程降低重試次數(shù)不同 Agent 之間格式不統(tǒng)一每個(gè) Task 都未規(guī)定 expected_output查看多個(gè) Task 的返回結(jié)果在 expected_output 中規(guī)定 Markdown/JSON/列表等格式Flow 中l(wèi)isten方法不執(zhí)行監(jiān)聽(tīng)的方法名寫(xiě)錯(cuò)或監(jiān)聽(tīng)方法拋異常被吞掉檢查裝飾器中的函數(shù)引用是否與實(shí)際情況一致添加 try/except 打印異常修正監(jiān)聽(tīng)參數(shù)對(duì)異常做顯式捕獲生產(chǎn)環(huán)境頻繁變更導(dǎo)致流程不可用模型版本、提示詞、Agent 配置沒(méi)有版本管理檢查是否有配置文件和流程代碼的版本標(biāo)簽將 Agent/Task 配置納入 Git對(duì) Prompt 變更做回歸測(cè)試這里單獨(dú)強(qiáng)調(diào)兩個(gè)新手最容易出的問(wèn)題。第一個(gè)是任務(wù)越寫(xiě)越大。很多人覺(jué)得一個(gè) Agent 一次做多個(gè)步驟能省錢(qián)實(shí)際結(jié)果往往相反——大模型在長(zhǎng)任務(wù)里的注意力和指令遵循能力會(huì)下降一步錯(cuò)步步錯(cuò)。更合理的拆法是一個(gè) Agent 只完成“一個(gè)思維動(dòng)作”檢索就檢索分析就分析寫(xiě)就寫(xiě)審就審。第二個(gè)是沒(méi)有給 Agent 定義清晰的“不做什么”。一個(gè) Agent 的 backstory 里只寫(xiě)了“你擅長(zhǎng)寫(xiě)文章”它就可能在需要調(diào)用工具時(shí)選擇自己“編內(nèi)容”。所以在 backstory 中要明確加一句邊界比如“你只能依據(jù)資料輸出不臆造事實(shí)”“如果缺少必要信息明確說(shuō)明缺少哪些信息”。8. 多智能體系統(tǒng)開(kāi)發(fā)最佳實(shí)踐與工程建議從“代碼能跑”到“系統(tǒng)能上線(xiàn)”中間還差著一整套工程化約束。下面是我認(rèn)為在多智能體系統(tǒng)開(kāi)發(fā)中比較重要的幾條建議。8.1 為任務(wù)設(shè)計(jì)明確的外部上下文邊界多智能體系統(tǒng)穩(wěn)定性的最大隱患是上下文污染。當(dāng) Agent 數(shù)量變多、任務(wù)鏈變長(zhǎng)如果一個(gè)早期任務(wù)的輸出含錯(cuò)誤信息后續(xù) Agent 可能會(huì)在錯(cuò)誤前提上繼續(xù)生成而且錯(cuò)誤會(huì)被逐步放大。因此不要把所有歷史結(jié)果都傳給下游。每個(gè) Task 的 description 只保留完成任務(wù)所需的關(guān)鍵上下文即可。必要時(shí)可以在任務(wù)間加入“信息抽取”環(huán)節(jié)讓一個(gè)專(zhuān)門(mén) Agent 從上游長(zhǎng)文本中抽取出精煉的結(jié)構(gòu)化信息再傳給下游。這會(huì)讓 Token 成本更可控也會(huì)顯著提高結(jié)果穩(wěn)定性。8.2 用最小授權(quán)和沙箱隔離工具權(quán)限如果你給 Agent 掛載了能執(zhí)行代碼、訪問(wèn)數(shù)據(jù)庫(kù)或調(diào)用內(nèi)部 API 的工具必須遵循最小權(quán)限原則。一個(gè)做內(nèi)容分類(lèi)的 Agent 不需要?jiǎng)h除數(shù)據(jù)庫(kù)的權(quán)限一個(gè)做數(shù)據(jù)查詢(xún)的 Agent 不應(yīng)獲得生產(chǎn)環(huán)境的寫(xiě)權(quán)限默認(rèn)只讀。工具調(diào)用應(yīng)該有三層護(hù)欄第一層是在代碼層做好參數(shù)校驗(yàn)和權(quán)限校驗(yàn)第二層是在工具描述中明確邊界第三層是核心操作前加入人工審批或條件約束。8.3 日志、追蹤和評(píng)估是生產(chǎn)上線(xiàn)的前提傳統(tǒng)的單元測(cè)試很難覆蓋自然語(yǔ)言輸出的不確定性。多智能體項(xiàng)目上線(xiàn)前需要至少做到每個(gè)任務(wù)的輸入、輸出、Token 用量、延遲都記錄到日志里對(duì)結(jié)果做結(jié)構(gòu)化評(píng)估例如 JSON 字段校驗(yàn)、關(guān)鍵詞規(guī)則、核心指標(biāo)是否出現(xiàn)準(zhǔn)備一組典型用例作為回歸集修改 Prompt 或任務(wù)步驟后用同一組用例重新跑一遍數(shù)據(jù)敏感時(shí)做脫敏后再記錄日志。8.4 Prompt 和配置要納入版本管理多智能體系統(tǒng)的核心其實(shí)是提示詞工程和任務(wù)編排。Agent 的 role、goal、backstory、Task 的 description本質(zhì)上都是代碼的一部分需要走 Git 管理。實(shí)際操作中可以把 Agent 和 Task 配置抽成 YAML 文件再通過(guò) CrewAI 的配置加載機(jī)制讀取避免把大量自然語(yǔ)言配置散落在 Python 類(lèi)的文件里。8.5 固定模型版本和 Provider 配置同一個(gè) Prompt 在不同模型上的表現(xiàn)差異很大。團(tuán)隊(duì)在開(kāi)發(fā)階段如果用高配模型驗(yàn)證效果但生產(chǎn)環(huán)境為了省錢(qián)換了小模型很可能出現(xiàn)規(guī)則不穩(wěn)定的現(xiàn)象。更穩(wěn)妥的做法是在配置中心統(tǒng)一管理模型選擇評(píng)估階段固定一組模型輸出結(jié)果全部保留對(duì)比記錄生產(chǎn)切換模型時(shí)必須做回歸。8.6 控制并行度和異步任務(wù)粒度CrewAI 支持任務(wù)異步執(zhí)行。當(dāng)多個(gè)相互獨(dú)立的任務(wù)存在時(shí)可以用async_executionTrue讓它們?cè)谕粋€(gè) Crew 內(nèi)并行執(zhí)行減少總耗時(shí)。但并行并不是越多越好并行度太高短時(shí)間內(nèi)的 Token 消耗會(huì)猛增同一個(gè)模型供應(yīng)商的限流也會(huì)導(dǎo)致大面積失敗。建議從 2 到 3 個(gè)并行任務(wù)開(kāi)始觀察 API 每分鐘請(qǐng)求數(shù)和 Token 消耗再逐步調(diào)高。9. 總結(jié)與后續(xù)學(xué)習(xí)方向回到這篇文章開(kāi)頭提出的判斷CrewAI 的真正價(jià)值是把多智能體系統(tǒng)從“研究玩具”推進(jìn)到“工程化任務(wù)編排工具”的位置。它用 Crew、Agent、Task、Process、Flow 這幾個(gè)清晰的概念讓開(kāi)發(fā)者能用聲明式代碼搭建一條可運(yùn)行的自動(dòng)化工作流。從實(shí)際項(xiàng)目經(jīng)驗(yàn)來(lái)看這不只是省掉了一部分調(diào)度代碼更是改變了多智能體系統(tǒng)的維護(hù)方式——你不再需要讀完幾千行調(diào)度邏輯才能理解系統(tǒng)在干什么看配置就能知道哪些角色、按什么順序、完成哪些任務(wù)。如果你是第一次接觸 CrewAI下一步可以按這個(gè)路徑實(shí)踐-先復(fù)現(xiàn)第 5.1 節(jié)的最小示例跑通環(huán)境把第 5.2 節(jié)的內(nèi)容生產(chǎn)流水線(xiàn)改成你自己的業(yè)務(wù)場(chǎng)景找一個(gè)小型工具按第 5.4 節(jié)的方式把它封裝成 Agent 工具如果流程進(jìn)入分支和循環(huán)再開(kāi)始用 Flow。值得繼續(xù)深入研究的方向有三個(gè)一是 CrewAI 與 MCP 協(xié)議的集成方式這決定 Agent 能否接入企業(yè)內(nèi)外部豐富的工具生態(tài)二是多智能體系統(tǒng)的評(píng)測(cè)體系因?yàn)樗苯佑绊懩隳懿荒馨严到y(tǒng)從開(kāi)發(fā)環(huán)境穩(wěn)定遷移到生產(chǎn)環(huán)境三是記憶機(jī)制的設(shè)計(jì)什么時(shí)候需要短期記憶、什么時(shí)候用長(zhǎng)期記憶、什么時(shí)候干脆不要記憶需要基于業(yè)務(wù)做取舍。建議你把這篇文章收藏下來(lái)作為一個(gè)從零搭建多智能體系統(tǒng)的索引。遇到具體問(wèn)題比如模型調(diào)用失敗、任務(wù)上下文丟失、Agent 輸出格式不對(duì)優(yōu)先查第 7 節(jié)的排查表再回來(lái)看對(duì)應(yīng)章節(jié)的示例代碼。多智能體開(kāi)發(fā)是一條需要反復(fù)調(diào)試的路但只要你把基本概念和最小示例跑通了往后加角色、加任務(wù)、加工具都只是在這個(gè)框架里做增量擴(kuò)展而已。