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