track_crewai 集成深度解析Opik 如何追蹤 CrewAI 的多智能體工作流【免費下載鏈接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.項目地址: https://gitcode.com/GitHub_Trending/co/comet-llm本文以opik.integrations.crewai.track_crewai這一集成入口為核心完整講解如何在 OpikComet 團隊的 LLM 可觀測平臺中追蹤 CrewAI 的多智能體活動包括 API 簽名與參數含義、一次調用背后實際打補丁monkey-patch了哪些 CrewAI 方法、每個 span 會記錄哪些 input/output 字段以及針對 CrewAI v1.0.0 的 Flow 與 LLM 客戶端追蹤機制。讀完后你可以直接在生產代碼中啟用 CrewAI 追蹤并能從源碼層面解釋平臺上看到的 span 結構與 token 數據來源。1. track_crewai 是什么API 簽名與參數語義CrewAI 集成文檔頁 track_crewai.rst 通過 Sphinx 的autofunction指令直接渲染 opik_tracker.py 中track_crewai的 docstring因此官方文檔與源碼保持逐字一致。該函數的完整簽名為def track_crewai( project_name: Optional[str] None, crew: Optional[crewai.Crew] None, ) - None: Tracks CrewAI activities by enabling tracking decorators for various critical methods. The function applies tracking decorators to key CrewAI components and methods, enabling logging or monitoring of activities. Tracking is enabled globally and can only be initialized once. If you use this tracker - please avoid using of OpenAI tracker to prevent duplicate logging of LLM calls and token usage. Parameters: project_name: The name of the project to associate with the tracking. crew: The Crew instance to track. Required for CrewAI v1.0.0 to properly track LLM calls. 兩個參數的語義要點參數類型說明project_nameOptional[str]追蹤數據歸屬的 Opik 項目名為None時使用默認項目。crewOptional[crewai.Crew]要追蹤的Crew實例。在 CrewAI v1.0.0 中必須傳入否則無法正確追蹤底層的 LLM 調用見第 5 節。docstring 同時強調了兩個關鍵約束在接入前務必理解全局生效、僅可初始化一次Tracking is enabled globally and can only be initialized once。該函數通過替換 CrewAI 類的方法實現是進程級全局副作用重復調用沒有意義。避免與 OpenAI tracker 同時使用please avoid using of OpenAI tracker to prevent duplicate logging of LLM calls and token usage。因為 CrewAI 集成本身已經接管了 LLM 調用層的埋點再疊加opik.integrations.openai會導致同一次 LLM 調用被記錄兩次token 用量重復計入成本統計。track_crewai僅由模塊的__init__.py導出見init.py 中__all__ [track_crewai]因此標準導入方式為from opik.integrations.crewai import track_crewai2. 快速上手完整可運行的接入示例CrewAI 集成索引頁 index.rst 給出了官方的最小接入示例在應用入口調用一次track_crewai(project_name...)隨后按正常方式構建并運行Crew所有活動即自動上報 Opik。完整示例如下from opik.integrations.crewai import track_crewai from crewai import Agent, Crew, Task, Process class YourCrewName: def agent_one(self) - Agent: return Agent( roleData Analyst, goalAnalyze data trends in the market, backstoryAn experienced data analyst with a background in economics, verboseTrue, ) def agent_two(self) - Agent: return Agent( roleMarket Researcher, goalGather information on market dynamics, backstoryA diligent researcher with a keen eye for detail, verboseTrue ) def task_one(self) - Task: return Task( nameCollect Data Task, descriptionCollect recent market data and identify trends., expected_outputA report summarizing key trends in the market., agentself.agent_one() ) def task_two(self) - Task: return Task( nameMarket Research Task, descriptionResearch factors affecting market dynamics., expected_outputAn analysis of factors influencing the market., agentself.agent_two() ) def crew(self) - Crew: return Crew( agents[self.agent_one(), self.agent_two()], tasks[self.task_one(), self.task_two()], processProcess.sequential, verboseTrue ) track_crewai(project_namecrewai-integration-demo) my_crew YourCrewName().crew() result my_crew.kickoff() print(result)使用前提是已配置好 Opik 的連接API key / 服務地址與對應 LLM 提供商的 key如OPENAI_API_KEY。示例中track_crewai在kickoff()之前調用由于它是全局補丁放在應用啟動階段任何 Crew 執行之前即可。3. 一次 track_crewai 調用背后打了哪些補丁理解集成的關鍵在于track_crewai并不是裝飾某個固定函數而是對 CrewAI 庫的類與方法做運行時替換。在 opik_tracker.py 中一次調用按順序完成以下動作analytics.track_event(integration, crewai) # 上報集成使用事件 decorator_factory crewai_decorator.CrewAITrackDecorator() crewai_wrapper decorator_factory.track(project_nameproject_name) # ① 核心三類對象的四個方法被替換為帶追蹤的包裝 crewai.Crew.kickoff crewai_wrapper(crewai.Crew.kickoff) crewai.Crew.kickoff_for_each crewai_wrapper(crewai.Crew.kickoff_for_each) crewai.Agent.execute_task crewai_wrapper(crewai.Agent.execute_task) crewai.Task.execute_sync crewai_wrapper(crewai.Task.execute_sync) # ② 補丁 LiteLLMCrewAI v0.x 的底層 LLM 通道 patchers.patch_litellm_completion(project_nameproject_name) # ③ 補丁 Flow 類v1.0.0 才有 patchers.patch_flow(project_nameproject_name) # ④ 補丁 Agent 持有的 LLM 客戶端v1.0.0且必須傳入 crew if crew is not None and is_crewai_v1(): patchers.patch_llm_client(crew, project_name)逐項說明① 結構層追蹤Crew / Agent / TaskCrew.kickoff、Crew.kickoff_for_each、Agent.execute_task、Task.execute_sync四個方法被CrewAITrackDecorator的track裝飾器包裝。這對應 CrewAI 工作流的三層結構——Crew 執行、Agent 執行任務、Task 同步執行——在 Opik 上會形成嵌套的 span 樹。注意kickoff_for_each批量執行多組輸入同樣被覆蓋因此批量任務也會逐組生成追蹤。② LiteLLM 層追蹤patchers/litellm_completion.py 將litellm.completion與litellm.acompletion分別替換為opik.integrations.litellm.track_completion(project_name...)的包裝版本。CrewAI v0.x 內部經由 LiteLLM 發起 LLM 請求因此這兩個補丁保證了 v0.x 下 LLM 調用含模型、token 用量也能進入 Opik。③ Flow 追蹤v1.0.0見第 5 節。④ LLM 客戶端追蹤v1.0.0見第 5 節。此外函數體開頭會調用analytics.track_event(integration, crewai)記錄一次集成使用事件屬于遙測性質不影響追蹤數據本身。4. Span 的數據采集規則記錄什么、叫什么名字span 的字段裝配邏輯集中在 crewai_decorator.py 中的CrewAITrackDecorator繼承自 Opik 通用BaseTrackDecorator見 base_track_decorator 體系。4.1 開始 span 時_start_span_inputs_preprocessor每個被追蹤方法開始執行時都會創建一個typegeneral的 span統一打上metadata[created_from] crewai—— 標識數據來源框架tags [crewai]—— 便于在 Opik 前端按 tag 過濾按方法名區分的metadata[object_type]與差異化 input被追蹤方法object_typespan 名稱input 內容Crew.kickoff/kickoff_for_eachcrew函數原名kickoffkickoff(inputs...)傳入的inputs字典Agent.execute_taskagentAgent 的role如Data Analyst{context: ..., agent: {backstory, goal, role, tools}}Task.execute_synctaskTask: {task.name}如Task: Collect Data Task{task: {config, context, description, expected_output, name, prompt_context, tools}}其中 Agent / Task 的 input 并非把整個對象序列化而是由白名單過濾——crewai_decorator.py 定義了三組常量經jsonable_encoder.encodedict_utils.split_dict_by_keys見_encode_dict_and_keep_keyscrewai_decorator.py保留指定鍵AGENT_KWARGS_KEYS_TO_LOG_AS_INPUTSbackstory、goal、role、toolsllm、max_iter、cache等其余參數被有意排除避免把不可 JSON 化或敏感的內部字段寫入 spanTASK_KWARGS_KEYS_TO_LOG_AS_INPUTSconfig、context、description、expected_output、name、prompt_context、toolsTASK_KWARGS_KEYS_TO_LOG_AS_OUTPUTname、raw、summary。這種白名單設計意味著調整 span 中記錄哪些字段只需要改這三組常量列表而不必動埋點流程。4.2 結束 span 時_end_span_inputs_preprocessor輸出側同樣按object_type分流crewai_decorator.pycrew對整個輸出CrewOutput做jsonable_encoder.encode并output_dict.pop(token_usage, None)—— 從 crew 級 span 的 output 中剝離 token 用量。因為 token 數據會由 LLM 層LiteLLM / provider 客戶端以規范的 usage 字段單獨記錄避免在結構 span 里重復冗余agent輸出統一包裝為{output: output}task僅按白名單保留name、raw、summary三個字段。另外object_type鍵在結束 span 時通過metadata.pop(object_type)從 metadata 中取出使用不會殘留到最終上報的 metadata 里。從 span 層級上看kickoff作為本次運行的根 spanAgent.execute_task與Task.execute_sync嵌套其下LLM 調用 span 又嵌套在 agent 執行之下由第 3 節 ②/④ 的補丁保證從而在 Opik 前端呈現一棵完整的執行樹。5. CrewAI v1.0.0 的增強機制版本探測、Flow 與 LLM 客戶端CrewAI v1.0.0 重構了 LLM 抽象不再一律走 LiteLLM因此集成提供了版本感知的增強路徑。5.1 版本探測is_crewai_v1() 通過importlib.metadata.version(crewai)讀取已安裝版本并用opik.semantic_version.SemanticVersion.parse(version) 1.0.0判斷讀取失敗如元數據缺失時靜默返回False退化到 v0.x 的埋點路徑。這也解釋了 docstring 中 crew: Required for CrewAI v1.0.0 to properly track LLM calls 的由來——v1 下 LLM 調用追蹤依賴patch_llm_client而它的輸入正是這個crew實例。5.2 Flow 補丁patchers/flow.pyCrewAI v1.0.0 引入的Flow類狀態機式編排在 patchers/flow.py 中被打了兩處補丁均有冪等保護_patched標記與類不存在則跳過的容錯CrewAI 舊版本下crewai.Flow不存在直接return并打 debug 日志Flow.__init__包裝在 Flow 構造完成后遍歷其注冊的方法字典self._methods對每個尚未標記opik_tracked的方法動態套用opik_tracker.track(project_name..., tags[crewai], metadata{created_from: crewai})。也就是說用戶在 Flow 中聲明的每個start/listen/router方法都會自動成為獨立 span無需逐個手動裝飾重復 patch 由opik_tracked屬性短路。Flow.kickoff_async包裝用一個名為Flow.kickoff_async的 span 包裹異步入口。代碼注釋解釋了為什么只包異步版本the sync version calls it internally——同步kickoff內部會調用kickoff_async包一處即可避免重復 span。5.3 LLM 客戶端補丁patchers/llm_client.pypatch_llm_client(crew, project_name) 遍歷crew.agents對每個agent.llm做 provider 探測與替換provider 探測目標復用的 Opik 集成OpenAICompletionopik.integrations.openai.track_openaiAnthropicCompletionopik.integrations.anthropic.track_anthropicGeminiCompletionopik.integrations.genai.track_genaiBedrockCompletionopik.integrations.bedrock.track_bedrock實現細節值得注意的兩點探測本身是防御式的每個_is_*_llm函數在對應 provider 模塊ImportError時返回False_patch_*_client整體再包一層try/except并僅LOGGER.warning——某個 provider 庫缺失或 patch 失敗不會中斷應用運行客戶端屬性名有版本兼容處理_get_client_attribute_name注釋說明 CrewAI 1.13.0 converted LLM classes to Pydantic BaseModel, moving the SDK client from a publicclientattribute to a Pydantic PrivateAttr_client因此會先探測_client、不存在再取clientllm_client.py。patch 完成后用 provider 集成返回的patched_client回寫到 LLM 實例之后 Agent 發起的所有補全請求模型名、usage、token 成本都會由對應 provider 集成規范記錄。5.4 v0.x 與 v1.x 的埋點差異小結從源碼結構看兩條 LLM 追蹤路徑是并行的v0.x 依賴 ②LiteLLM 補丁v1.x 依賴 ④provider 客戶端補丁①結構層與 ③Flow可選對所有版本生效。因此在 v1.0.0 環境中調用track_crewai(project_name...)而不傳crew時Crew/Agent/Task 層級 span 仍然生成但 LLM 調用 span 會缺失——這正是 docstring 把crew標注為 v1 Required ... to properly track LLM calls 的原因。6. 使用注意事項與常見問題只調用一次且盡早調用。補丁作用于類定義crewai.Crew.kickoff等必須在任何kickoff/ Flow 實例化之前執行Flow 的方法裝飾發生在Flow.__init__內晚于track_crewai創建的 Flow 才能被追蹤。不要疊加 OpenAI 集成。CrewAI 場景下 LLM 層已被本集成接管v0.x 走 LiteLLM 補丁、v1.x 走 provider 客戶端補丁再啟用opik.integrations.openai會對同一請求產生雙重 span 與雙重 token 統計。v1.0.0 請傳入 crew 實例track_crewai(project_namemy-project, crewmy_crew)。span 命名規則決定了前端展示Agent span 直接以role命名、Task span 以Task: {name}命名見 4.1 節。如果你希望前端出現更可讀的名稱應從 CrewAI 側的role/task.name入手而非在 Opik 側重命名。輸入/輸出字段范圍由白名單控制若需要在 span 中補充 CrewAI 對象的其他字段例如max_iter、output_file修改方向是擴展 crewai_decorator.py 中的三組鍵列表——但這是 SDK 源碼層改動實際項目中通常通過metadata或自定義 span 補充信息。7. 測試與進一步閱讀倉庫內為 CrewAI 集成配套了三層集成測試可用作期望行為的權威參照test_crewai.py —— 基礎 Crew/Agent/Task 追蹤test_crewai_flows.py —— Flow 場景的 span 結構驗證test_crewai_built_from_config.py —— 通過配置YAML/config方式構建 Crew 的追蹤路徑。其他值得深入的關鍵文件入口與版本探測sdks/python/src/opik/integrations/crewai/opik_tracker.pySpan 字段裝配與白名單sdks/python/src/opik/integrations/crewai/crewai_decorator.py通用 track 裝飾器參數結構TrackOptions/StartSpanParameterssdks/python/src/opik/decorator/arguments_helpers.py官方文檔頁本文主體來源track_crewai.rst 與 index.rst8. 小結track_crewai(project_name, crew)是 Opik 對 CrewAI 的一站式追蹤入口一次調用同時完成結構層Crew/Agent/Task 四個核心方法、LLM 層LiteLLM 或四大 provider 客戶端與 Flow 層v1.0.0的運行時補丁span 的命名、input/output 字段由明確的白名單常量控制token 用量則剝離到 LLM 層統一記錄。把握全局一次性初始化、v1 必傳 crew、勿疊加 OpenAI 集成這三條約束并對照第 4 節的字段規則理解平臺上的 span 樹即可把 CrewAI 多智能體應用的可觀測性完整接入 Opik。【免費下載鏈接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.項目地址: https://gitcode.com/GitHub_Trending/co/comet-llm創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 track_crewai 集成深度解析：Opik 如何追蹤 CrewAI 的多智能體工作流
track_crewai 集成深度解析Opik 如何追蹤 CrewAI 的多智能體工作流【免費下載鏈接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.項目地址: https://gitcode.com/GitHub_Trending/co/comet-llm本文以opik.integrations.crewai.track_crewai這一集成入口為核心完整講解如何在 OpikComet 團隊的 LLM 可觀測平臺中追蹤 CrewAI 的多智能體活動包括 API 簽名與參數含義、一次調用背后實際打補丁monkey-patch了哪些 CrewAI 方法、每個 span 會記錄哪些 input/output 字段以及針對 CrewAI v1.0.0 的 Flow 與 LLM 客戶端追蹤機制。讀完后你可以直接在生產代碼中啟用 CrewAI 追蹤并能從源碼層面解釋平臺上看到的 span 結構與 token 數據來源。1. track_crewai 是什么API 簽名與參數語義CrewAI 集成文檔頁 track_crewai.rst 通過 Sphinx 的autofunction指令直接渲染 opik_tracker.py 中track_crewai的 docstring因此官方文檔與源碼保持逐字一致。該函數的完整簽名為def track_crewai( project_name: Optional[str] None, crew: Optional[crewai.Crew] None, ) - None: Tracks CrewAI activities by enabling tracking decorators for various critical methods. The function applies tracking decorators to key CrewAI components and methods, enabling logging or monitoring of activities. Tracking is enabled globally and can only be initialized once. If you use this tracker - please avoid using of OpenAI tracker to prevent duplicate logging of LLM calls and token usage. Parameters: project_name: The name of the project to associate with the tracking. crew: The Crew instance to track. Required for CrewAI v1.0.0 to properly track LLM calls. 兩個參數的語義要點參數類型說明project_nameOptional[str]追蹤數據歸屬的 Opik 項目名為None時使用默認項目。crewOptional[crewai.Crew]要追蹤的Crew實例。在 CrewAI v1.0.0 中必須傳入否則無法正確追蹤底層的 LLM 調用見第 5 節。docstring 同時強調了兩個關鍵約束在接入前務必理解全局生效、僅可初始化一次Tracking is enabled globally and can only be initialized once。該函數通過替換 CrewAI 類的方法實現是進程級全局副作用重復調用沒有意義。避免與 OpenAI tracker 同時使用please avoid using of OpenAI tracker to prevent duplicate logging of LLM calls and token usage。因為 CrewAI 集成本身已經接管了 LLM 調用層的埋點再疊加opik.integrations.openai會導致同一次 LLM 調用被記錄兩次token 用量重復計入成本統計。track_crewai僅由模塊的__init__.py導出見init.py 中__all__ [track_crewai]因此標準導入方式為from opik.integrations.crewai import track_crewai2. 快速上手完整可運行的接入示例CrewAI 集成索引頁 index.rst 給出了官方的最小接入示例在應用入口調用一次track_crewai(project_name...)隨后按正常方式構建并運行Crew所有活動即自動上報 Opik。完整示例如下from opik.integrations.crewai import track_crewai from crewai import Agent, Crew, Task, Process class YourCrewName: def agent_one(self) - Agent: return Agent( roleData Analyst, goalAnalyze data trends in the market, backstoryAn experienced data analyst with a background in economics, verboseTrue, ) def agent_two(self) - Agent: return Agent( roleMarket Researcher, goalGather information on market dynamics, backstoryA diligent researcher with a keen eye for detail, verboseTrue ) def task_one(self) - Task: return Task( nameCollect Data Task, descriptionCollect recent market data and identify trends., expected_outputA report summarizing key trends in the market., agentself.agent_one() ) def task_two(self) - Task: return Task( nameMarket Research Task, descriptionResearch factors affecting market dynamics., expected_outputAn analysis of factors influencing the market., agentself.agent_two() ) def crew(self) - Crew: return Crew( agents[self.agent_one(), self.agent_two()], tasks[self.task_one(), self.task_two()], processProcess.sequential, verboseTrue ) track_crewai(project_namecrewai-integration-demo) my_crew YourCrewName().crew() result my_crew.kickoff() print(result)使用前提是已配置好 Opik 的連接API key / 服務地址與對應 LLM 提供商的 key如OPENAI_API_KEY。示例中track_crewai在kickoff()之前調用由于它是全局補丁放在應用啟動階段任何 Crew 執行之前即可。3. 一次 track_crewai 調用背后打了哪些補丁理解集成的關鍵在于track_crewai并不是裝飾某個固定函數而是對 CrewAI 庫的類與方法做運行時替換。在 opik_tracker.py 中一次調用按順序完成以下動作analytics.track_event(integration, crewai) # 上報集成使用事件 decorator_factory crewai_decorator.CrewAITrackDecorator() crewai_wrapper decorator_factory.track(project_nameproject_name) # ① 核心三類對象的四個方法被替換為帶追蹤的包裝 crewai.Crew.kickoff crewai_wrapper(crewai.Crew.kickoff) crewai.Crew.kickoff_for_each crewai_wrapper(crewai.Crew.kickoff_for_each) crewai.Agent.execute_task crewai_wrapper(crewai.Agent.execute_task) crewai.Task.execute_sync crewai_wrapper(crewai.Task.execute_sync) # ② 補丁 LiteLLMCrewAI v0.x 的底層 LLM 通道 patchers.patch_litellm_completion(project_nameproject_name) # ③ 補丁 Flow 類v1.0.0 才有 patchers.patch_flow(project_nameproject_name) # ④ 補丁 Agent 持有的 LLM 客戶端v1.0.0且必須傳入 crew if crew is not None and is_crewai_v1(): patchers.patch_llm_client(crew, project_name)逐項說明① 結構層追蹤Crew / Agent / TaskCrew.kickoff、Crew.kickoff_for_each、Agent.execute_task、Task.execute_sync四個方法被CrewAITrackDecorator的track裝飾器包裝。這對應 CrewAI 工作流的三層結構——Crew 執行、Agent 執行任務、Task 同步執行——在 Opik 上會形成嵌套的 span 樹。注意kickoff_for_each批量執行多組輸入同樣被覆蓋因此批量任務也會逐組生成追蹤。② LiteLLM 層追蹤patchers/litellm_completion.py 將litellm.completion與litellm.acompletion分別替換為opik.integrations.litellm.track_completion(project_name...)的包裝版本。CrewAI v0.x 內部經由 LiteLLM 發起 LLM 請求因此這兩個補丁保證了 v0.x 下 LLM 調用含模型、token 用量也能進入 Opik。③ Flow 追蹤v1.0.0見第 5 節。④ LLM 客戶端追蹤v1.0.0見第 5 節。此外函數體開頭會調用analytics.track_event(integration, crewai)記錄一次集成使用事件屬于遙測性質不影響追蹤數據本身。4. Span 的數據采集規則記錄什么、叫什么名字span 的字段裝配邏輯集中在 crewai_decorator.py 中的CrewAITrackDecorator繼承自 Opik 通用BaseTrackDecorator見 base_track_decorator 體系。4.1 開始 span 時_start_span_inputs_preprocessor每個被追蹤方法開始執行時都會創建一個typegeneral的 span統一打上metadata[created_from] crewai—— 標識數據來源框架tags [crewai]—— 便于在 Opik 前端按 tag 過濾按方法名區分的metadata[object_type]與差異化 input被追蹤方法object_typespan 名稱input 內容Crew.kickoff/kickoff_for_eachcrew函數原名kickoffkickoff(inputs...)傳入的inputs字典Agent.execute_taskagentAgent 的role如Data Analyst{context: ..., agent: {backstory, goal, role, tools}}Task.execute_synctaskTask: {task.name}如Task: Collect Data Task{task: {config, context, description, expected_output, name, prompt_context, tools}}其中 Agent / Task 的 input 并非把整個對象序列化而是由白名單過濾——crewai_decorator.py 定義了三組常量經jsonable_encoder.encodedict_utils.split_dict_by_keys見_encode_dict_and_keep_keyscrewai_decorator.py保留指定鍵AGENT_KWARGS_KEYS_TO_LOG_AS_INPUTSbackstory、goal、role、toolsllm、max_iter、cache等其余參數被有意排除避免把不可 JSON 化或敏感的內部字段寫入 spanTASK_KWARGS_KEYS_TO_LOG_AS_INPUTSconfig、context、description、expected_output、name、prompt_context、toolsTASK_KWARGS_KEYS_TO_LOG_AS_OUTPUTname、raw、summary。這種白名單設計意味著調整 span 中記錄哪些字段只需要改這三組常量列表而不必動埋點流程。4.2 結束 span 時_end_span_inputs_preprocessor輸出側同樣按object_type分流crewai_decorator.pycrew對整個輸出CrewOutput做jsonable_encoder.encode并output_dict.pop(token_usage, None)—— 從 crew 級 span 的 output 中剝離 token 用量。因為 token 數據會由 LLM 層LiteLLM / provider 客戶端以規范的 usage 字段單獨記錄避免在結構 span 里重復冗余agent輸出統一包裝為{output: output}task僅按白名單保留name、raw、summary三個字段。另外object_type鍵在結束 span 時通過metadata.pop(object_type)從 metadata 中取出使用不會殘留到最終上報的 metadata 里。從 span 層級上看kickoff作為本次運行的根 spanAgent.execute_task與Task.execute_sync嵌套其下LLM 調用 span 又嵌套在 agent 執行之下由第 3 節 ②/④ 的補丁保證從而在 Opik 前端呈現一棵完整的執行樹。5. CrewAI v1.0.0 的增強機制版本探測、Flow 與 LLM 客戶端CrewAI v1.0.0 重構了 LLM 抽象不再一律走 LiteLLM因此集成提供了版本感知的增強路徑。5.1 版本探測is_crewai_v1() 通過importlib.metadata.version(crewai)讀取已安裝版本并用opik.semantic_version.SemanticVersion.parse(version) 1.0.0判斷讀取失敗如元數據缺失時靜默返回False退化到 v0.x 的埋點路徑。這也解釋了 docstring 中 crew: Required for CrewAI v1.0.0 to properly track LLM calls 的由來——v1 下 LLM 調用追蹤依賴patch_llm_client而它的輸入正是這個crew實例。5.2 Flow 補丁patchers/flow.pyCrewAI v1.0.0 引入的Flow類狀態機式編排在 patchers/flow.py 中被打了兩處補丁均有冪等保護_patched標記與類不存在則跳過的容錯CrewAI 舊版本下crewai.Flow不存在直接return并打 debug 日志Flow.__init__包裝在 Flow 構造完成后遍歷其注冊的方法字典self._methods對每個尚未標記opik_tracked的方法動態套用opik_tracker.track(project_name..., tags[crewai], metadata{created_from: crewai})。也就是說用戶在 Flow 中聲明的每個start/listen/router方法都會自動成為獨立 span無需逐個手動裝飾重復 patch 由opik_tracked屬性短路。Flow.kickoff_async包裝用一個名為Flow.kickoff_async的 span 包裹異步入口。代碼注釋解釋了為什么只包異步版本the sync version calls it internally——同步kickoff內部會調用kickoff_async包一處即可避免重復 span。5.3 LLM 客戶端補丁patchers/llm_client.pypatch_llm_client(crew, project_name) 遍歷crew.agents對每個agent.llm做 provider 探測與替換provider 探測目標復用的 Opik 集成OpenAICompletionopik.integrations.openai.track_openaiAnthropicCompletionopik.integrations.anthropic.track_anthropicGeminiCompletionopik.integrations.genai.track_genaiBedrockCompletionopik.integrations.bedrock.track_bedrock實現細節值得注意的兩點探測本身是防御式的每個_is_*_llm函數在對應 provider 模塊ImportError時返回False_patch_*_client整體再包一層try/except并僅LOGGER.warning——某個 provider 庫缺失或 patch 失敗不會中斷應用運行客戶端屬性名有版本兼容處理_get_client_attribute_name注釋說明 CrewAI 1.13.0 converted LLM classes to Pydantic BaseModel, moving the SDK client from a publicclientattribute to a Pydantic PrivateAttr_client因此會先探測_client、不存在再取clientllm_client.py。patch 完成后用 provider 集成返回的patched_client回寫到 LLM 實例之后 Agent 發起的所有補全請求模型名、usage、token 成本都會由對應 provider 集成規范記錄。5.4 v0.x 與 v1.x 的埋點差異小結從源碼結構看兩條 LLM 追蹤路徑是并行的v0.x 依賴 ②LiteLLM 補丁v1.x 依賴 ④provider 客戶端補丁①結構層與 ③Flow可選對所有版本生效。因此在 v1.0.0 環境中調用track_crewai(project_name...)而不傳crew時Crew/Agent/Task 層級 span 仍然生成但 LLM 調用 span 會缺失——這正是 docstring 把crew標注為 v1 Required ... to properly track LLM calls 的原因。6. 使用注意事項與常見問題只調用一次且盡早調用。補丁作用于類定義crewai.Crew.kickoff等必須在任何kickoff/ Flow 實例化之前執行Flow 的方法裝飾發生在Flow.__init__內晚于track_crewai創建的 Flow 才能被追蹤。不要疊加 OpenAI 集成。CrewAI 場景下 LLM 層已被本集成接管v0.x 走 LiteLLM 補丁、v1.x 走 provider 客戶端補丁再啟用opik.integrations.openai會對同一請求產生雙重 span 與雙重 token 統計。v1.0.0 請傳入 crew 實例track_crewai(project_namemy-project, crewmy_crew)。span 命名規則決定了前端展示Agent span 直接以role命名、Task span 以Task: {name}命名見 4.1 節。如果你希望前端出現更可讀的名稱應從 CrewAI 側的role/task.name入手而非在 Opik 側重命名。輸入/輸出字段范圍由白名單控制若需要在 span 中補充 CrewAI 對象的其他字段例如max_iter、output_file修改方向是擴展 crewai_decorator.py 中的三組鍵列表——但這是 SDK 源碼層改動實際項目中通常通過metadata或自定義 span 補充信息。7. 測試與進一步閱讀倉庫內為 CrewAI 集成配套了三層集成測試可用作期望行為的權威參照test_crewai.py —— 基礎 Crew/Agent/Task 追蹤test_crewai_flows.py —— Flow 場景的 span 結構驗證test_crewai_built_from_config.py —— 通過配置YAML/config方式構建 Crew 的追蹤路徑。其他值得深入的關鍵文件入口與版本探測sdks/python/src/opik/integrations/crewai/opik_tracker.pySpan 字段裝配與白名單sdks/python/src/opik/integrations/crewai/crewai_decorator.py通用 track 裝飾器參數結構TrackOptions/StartSpanParameterssdks/python/src/opik/decorator/arguments_helpers.py官方文檔頁本文主體來源track_crewai.rst 與 index.rst8. 小結track_crewai(project_name, crew)是 Opik 對 CrewAI 的一站式追蹤入口一次調用同時完成結構層Crew/Agent/Task 四個核心方法、LLM 層LiteLLM 或四大 provider 客戶端與 Flow 層v1.0.0的運行時補丁span 的命名、input/output 字段由明確的白名單常量控制token 用量則剝離到 LLM 層統一記錄。把握全局一次性初始化、v1 必傳 crew、勿疊加 OpenAI 集成這三條約束并對照第 4 節的字段規則理解平臺上的 span 樹即可把 CrewAI 多智能體應用的可觀測性完整接入 Opik。【免費下載鏈接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.項目地址: https://gitcode.com/GitHub_Trending/co/comet-llm創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考