Opik 集成 CrewAI：使用 track_crewai 追踪多智能体工作流的完整实战指南-北京尧图网络

Opik 集成 CrewAI使用 track_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-llmOpik 的 Python SDK 通过track_crewai函数为 CrewAI 框架提供全局追踪能力只需在应用入口处调用一次即可把 Crew 的启动流程、每个 Agent 的任务执行、每个 Task 的输入输出以及底层 LLM 调用与 token 用量全部上报到 Opik 平台。本文以 Python SDK 官方集成文档为骨架结合sdks/python中 CrewAI 集成的源码实现完整讲解其用法、参数语义、底层 Monkey-Patch 机制与 CrewAI v0.x / v1.0.0 的版本差异帮助你快速完成接入并在 Opik 中获得可检索、可评估的多智能体运行日志。1. 快速开始一次调用开启全局追踪官方文档integrations/crewai/index.rst给出的核心结论是Opik 与 CrewAI 的集成方式极为轻量——调用track_crewai即可开始记录 CrewAI 的活动与 LLM 调用。文档自带的完整示例如下保留原文全部代码可直接复制运行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)这个示例覆盖了典型的 CrewAI 多智能体结构两个 AgentData Analyst 与 Market Researcher、两个 Task分别绑定到各自 Agent、一个以Process.sequential顺序执行的Crew。注意track_crewai(project_namecrewai-integration-demo)放在kickoff()之前调用即可无需修改任何 CrewAI 业务代码——这正是基于 Monkey-Patch 的无侵入式接入。运行后所有数据都会落入名为crewai-integration-demo的 Opik 项目不传project_name时落入默认项目你可以直接在 Opik 前端按项目查看 Trace、Span 层级与 token 用量。仓库的文档站中另附有可交互的 Notebook 版本可作为调试参考cookbook/crewai.ipynb。2. track_crewai 的参数与使用约束track_crewai的文档页track_crewai.rst通过 Sphinxautofunction指令直接引用源码 docstring其实现位于 opik_tracker.pydef track_crewai( project_name: Optional[str] None, crew: Optional[crewai.Crew] None, ) - None:参数类型说明project_nameOptional[str]追踪数据关联到哪个 Opik 项目。None表示使用默认项目。该值会透传给所有被包装的组件Crew / Agent / Task / LLM 客户端 / Flow。crewOptional[crewai.Crew]要追踪的Crew实例。CrewAI v1.0.0 必须传入否则无法正确追踪 LLM 调用详见第 4 节的 LLM 客户端 Patch 机制。docstring 同时给出了两条重要的实践约束均值得写入团队规范追踪是全局的、且只能初始化一次Tracking is enabled globally and can only be initialized once。track_crewai通过直接替换类方法实现全局生效因此不要在请求循环或多次导入中反复调用。避免与 OpenAI Tracker 叠加使用If you use this tracker - please avoid using of OpenAI tracker to prevent duplicate logging of LLM calls and token usage。track_crewai已经接管了底层 LLM 调用的日志若再调用opik.integrations.openai.track_openai同一次 LLM 调用会被记录两次token 用量也会重复统计。此外该函数每次调用都会通过analytics.track_event(integration, crewai)记录一次集成启用事件见 opik_tracker.py属于匿名分析用途与你的业务数据无关。3. 底层机制一四大 Monkey-Patch 入口与 Span 建模track_crewai内部先构造一个CrewAITrackDecorator再用它对 CrewAI 的四个关键类方法做函数替换opik_tracker.pycrewai.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)这四个入口分别对应 Opik 中不同层级的 Span。CrewAITrackDecoratorcrewai_decorator.py继承自 Opik 通用的BaseTrackDecorator在_parse_inputs中按被包装方法的函数名识别对象类型并统一打上metadata[created_from] crewai与tags [crewai]便于后续在 Opik 中按标签过滤被 Patch 的方法metadata.object_typeSpan 名称记录的 InputCrew.kickoffcrewkickoff或装饰器指定的 namekickoff(inputs...)传入的inputs字典Agent.execute_taskagent取agent.role.strip()角色名如 Data Analystcontext Agent 白名单字段Task.execute_synctaskTask: {task.name}context之外的任务白名单字段其中 Agent 与 Task 的 Input 并非全量记录而是经过白名单过滤——这是理解 Opik 记录内容的关键。源码中的白名单常量crewai_decorator.py如下Agent 输入白名单AGENT_KWARGS_KEYS_TO_LOG_AS_INPUTSbackstory、goal、role、toolsagent_executor、llm、max_iter、verbose等字段在源码中被注释掉不记录。Task 输入白名单TASK_KWARGS_KEYS_TO_LOG_AS_INPUTSconfig、context、description、expected_output、name、prompt_context、tools。Task 输出白名单TASK_KWARGS_KEYS_TO_LOG_AS_OUTPUTname、raw、summary。也就是说在 Opik 的 Span 详情里你能看到每个 Agent 的角色/目标/背景/工具配置每个 Task 的描述与期望输出以及任务执行后的raw原始结果与summary摘要输出侧同样通过_encode_dict_and_keep_keys配合jsonable_encoder做安全序列化crewai_decorator.py这也是集成测试专门覆盖循环引用场景的原因——见下文第 6 节。对于 Crew 层的输出object_type crew记录的是kickoff()返回值经 JSON 编码后的结果但会主动pop(token_usage)crewai_decorator.py——因为 token 用量已由 LLM 调用层的 Patch 单独记录Crew 级 Span 中不再冗余携带。4. 底层机制二LLM 调用追踪与 v0.x / v1.0.0 版本分叉CrewAI 不同大版本的 LLM 调用路径差异很大track_crewai通过三层 Patcher 兼顾两种情况opik_tracker.py1LiteLLM Patch覆盖 CrewAI v0.x。CrewAI v0.x 内部通过 LiteLLM 发起 LLM 调用litellm_completion.py 直接把litellm.completion与litellm.acompletion两个全局函数替换为 Opik 的track_completion包装版本litellm.completion opik.integrations.litellm.track_completion( project_nameproject_name )(litellm.completion) litellm.acompletion opik.integrations.litellm.track_completion( project_nameproject_name )(litellm.acompletion)这是进程级全局替换因此 v0.x 下任何经由 LiteLLM 的调用包括 CrewAI 发起的都会带上项目名上报。2Flow Patch仅 CrewAI v1.0.0 提供 Flow 类。flow.py 对crewai.Flow做两处包装一是替换Flow.__init__在其内部对 Flow 注册到self._methods的每个状态方法自动套上 Opiktrack装饰器带opik_tracked标记防止重复包装并对每个 Flow 实例生效二是替换Flow.kickoff_async——注释说明同步版kickoff内部会调用异步版所以只需包装异步入口。若安装的 CrewAI 没有Flow类即 v0.x这两处 Patch 会静默跳过并打 debug 日志不会抛异常。3LLM 客户端 PatchCrewAI v1.0.0 且传入了crew参数。v1 中 CrewAI 不再统一走 LiteLLM而是按 Provider 使用各自的 SDK 客户端因此 llm_client.py 遍历crew.agents对每个 Agent 的llm实例按类型分别委托给对应的 Opik 集成OpenAI 客户端 →opik.integrations.openai.track_openaiAnthropic 客户端 →opik.integrations.anthropic.track_anthropicGemini 客户端 →opik.integrations.genai.track_genaiBedrock 客户端 →opik.integrations.bedrock.track_bedrock判断逻辑基于isinstance检查各 Provider 的 Completion 类如OpenAICompletion且对 Provider 库未安装的情况做了ImportError兜底缺失依赖只会告警而不会导致追踪失败。一个值得注意的兼容性细节在_get_client_attribute_namellm_client.pyCrewAI 1.13.0 将 LLM 类改造为 Pydantic BaseModelSDK 客户端从公开的client属性迁移到了 Pydantic PrivateAttr_client源码据此在两种属性名之间自动适配——这说明该集成对 v1 内部实现演进做过显式跟进。版本探测。上述 v1 专属逻辑由is_crewai_v1()控制opik_tracker.py通过importlib.metadata.version(crewai)读取已安装包版本用opik.semantic_version.SemanticVersion.parse与1.0.0比较任何异常包元数据缺失等都安全返回False退回到 v0.x 的 LiteLLM 追踪路径。由此得出实操结论CrewAI v0.x 用户只需track_crewai(project_name...)CrewAI v1.0.0 用户务必写成track_crewai(project_name..., crewmy_crew)否则 Agent 层的 LLM 调用输入/输出/token 用量/延迟/成本将无法被记录。5. 在 Opik 中你会看到什么综合第 3、4 节一次Crew.kickoff()在 Opik 中会形成如下可观察结构依据源码中object_type与 Span 命名规则crew 类型 Span名为kickoffinput 为你传入的inputsoutput 为最终结果agent 类型 Span以角色名命名如 Data Analystinput 含role/goal/backstory/tools与执行上下文task 类型 Span以Task: {task.name}命名input 含任务描述与期望输出output 含raw与summaryLLM 调用 Span由各 Provider 的 tracker或 LiteLLM tracker产生携带模型、token 用量等信息从而支撑 Opik 前端的成本/延迟聚合视图。所有 Span 均带tags[crewai]与metadata.created_fromcrewai配合project_name可在 Opik 项目中精确圈定本集成产生的数据。6. 集成测试版本差异与验证方式仓库为 CrewAI 集成维护了完整的 library_integration 测试套件tests/library_integration/crewai/包括test_crewai.py、test_crewai_flows.py验证第 4 节的 Flow 追踪以及test_crewai_built_from_config.py并提供了requirements_v0.txt与requirements_v1.txt两套依赖锁定文件证明该集成同时被 CI 验证于 CrewAI v0 与 v1 环境。从 test_crewai.py 的测试注释中还能读出几个有实操价值的版本细节v0 的模型选择限制v0 固定 litellm1.74.9对 gpt-5-nano 会错误地注入stoptoken 导致 OpenAI API 拒绝请求因此 v0 测试用gpt-4o-miniv1 统一用gpt-5-nanoGemini 的路由前缀不同v0 经由 LiteLLM 的vertex_ai/前缀路由v1 的 genai 集成则由GOOGLE_GENAI_USE_VERTEXAI环境变量推断测试据此按版本切换模型串序列化健壮性第一个测试用例名称即 cyclic reference inside one of the tasks / data is serialized correctly专门验证 Task 输出中出现的循环引用不会破坏上报——对应第 3 节提到的jsonable_encoder编码路径。这些测试同时覆盖了 OpenAI、Bedrock、Anthropic 四个 Provider参数化的model, opik_provider列表与第 4 节llm_client.py中四种 Provider 的 Patch 分支一一对应。7. 小结与接入检查清单把 CrewAI 应用接入 Opik 的完整路径可以归纳为四步安装并配置 Opik Python SDK指向你的 Opik 实例同时安装对应版本的 CrewAI在业务代码中构造好Crew后调用track_crewai(project_name..., crewmy_crew)v1.0.0 务必传crew该函数全局只应调用一次正常执行kickoff()/kickoff_for_each()Flow 用户执行flow.kickoff()亦可无需改动任何 CrewAI API 用法在 Opik 对应项目下验证 crew / agent / task / LLM 四层 Span 是否齐备并按crewai标签检索。需要避开的两个坑不要与track_openai等底层 tracker 叠加使用重复记录 LLM 调用与 token 用量CrewAI v0.x 的 LLM 追踪依赖进程级 LiteLLM Patch若同进程内还有其他依赖 LiteLLM 的组件其行为同样会被记录可结合project_name区分归属。更多上下文可参考CrewAI 集成文档索引、track_crewai 文档页、集成追踪器入口、Span 建模装饰器与 Python SDK 集成设计说明 INTEGRATIONS.md。【免费下载链接】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），仅供参考

Opik 集成 CrewAI：使用 track_crewai 追踪多智能体工作流的完整实战指南

相关推荐

Windows下MinGW-w64安装配置详解：从零搭建GCC编译环境

WeKnora 文档入库流水线 Worker Pool 治理：六池拓扑、并发预算与容量调优实战

RustFox：10MB秒启的Rust+Tauri+Vue API调试工具

更多资讯

Java日志安全：防止敏感信息泄露的实践指南

渗透测试面试进阶：从信息收集到内网横向移动的完整链路解析

SQL注入敏感源识别与不安全SQL请求审计日志落地实践

行测资料分析：年均增长率与等速率增长率考点精讲

Ollama API 全量响应SDK实战教程：流式/非流式对接、异常处理与生产落地

构建Async/await优先的CQRS+ES框架实践指南

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？