CrewAI框架

前提条件

• Python 环境版本 >= 3.9
• CrewAI版本 >= 1.15.0
• OpenTelemetry SDK版本 >= 1.42.0

探针初始化需要在应用启动时完成，建议在导入CrewAI模块之前初始化。

• 在AgentArts观测界面查看数据不收费。
• 但数据上报会产生费用：
  • 调用链上报到APM（应用性能管理服务），费用明细请参考APM计费说明。
  • 指标上报到AOM（应用运维管理服务），费用明细请参考AOM计费说明。

• AOM和APM都是按需计费，并有一定量的免费额度，超出后按实际使用量收费。

框架介绍

CrewAI是面向大语言模型应用的多智能体协作框架。它以“角色（Role）、目标（Goal）、任务（Task）”为核心抽象，通过编排多个具备独立职责的Agent、分配工具（Tool）与技能（Skill），协同完成复杂任务；内置规划（Planner）、任务委派与记忆（Memory）等能力，支持从单Agent到多Agent协作，以及基于事件驱动的Flow流程编排。

接入后，以下能力将被自动监控：

• Crew执行链路（crew kickoff）：Crew的完整生命周期，包括Agent编排和任务分配。
• Agent执行：每个Agent的角色执行和任务处理过程。
• Task执行：任务的分配、执行和结果汇总。
• LLM调用（chat）：模型名称、Token用量、输入/输出内容。
• 工具调用（execute_tool）：工具名称、输入参数、返回结果。

接入步骤

示例代码

以下示例展示了一个基于CrewAI的单Agent应用，包含一个Agent和一个Task，并演示了如何通过OTel Baggage注入session_id和user_id：

示例中使用华为云MaaS服务提供的大模型接口，可登录华为云MaaS服务控制台，创建API Key。在项目的.env文件中配置以下变量：

请提前确认已完成探针安装，详细操作详见接入步骤。

OPENAI_API_KEY=<MODEL_API_KEY>
OPENAI_MODEL_NAME=deepseek-v4.1-flash
OPENAI_API_BASE=https://api.modelarts-maas.com/openai/v1

Agent应用示例代码如下：

import os
import uuid

from crewai import Agent, Crew, Task
from dotenv import load_dotenv
from opentelemetry import baggage, context

load_dotenv()


def get_llm():
    from crewai import LLM

    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise RuntimeError("未找到 OPENAI_API_KEY,请在 .env 中配置。")
    model = os.getenv("OPENAI_MODEL_NAME", "gpt-4o-mini")
    base = os.getenv("OPENAI_API_BASE")
    if base:
        return LLM(model=model, base_url=base, api_key=api_key)
    return LLM(model=model, api_key=api_key)


def main() -> None:
    # 1. 注入 OTel baggage：探针据此上报 gen_ai.conversation.id / user.id
    session_id = f"demo-session-{uuid.uuid4().hex[:8]}"
    ctx = baggage.set_baggage("session_id", session_id)
    ctx = baggage.set_baggage("user_id", "demo-user", context=ctx)
    token = context.attach(ctx)
    print(f"[demo] session_id = {session_id}")

    # 2. 业务代码：一个 Agent 写一句话
    agent = Agent(
        role="文案助理",
        goal="用一句话介绍某个主题",
        backstory="你是一名简洁的文案助理。",
        llm=get_llm(),
    )
    task = Task(
        description="围绕主题「{topic}」写一句话介绍。",
        expected_output="一句 20 字以内的中文介绍。",
        agent=agent,
    )
    crew = Crew(agents=[agent], tasks=[task])

    try:
        result = crew.kickoff(inputs={"topic": "AI 在医疗领域的应用"})
    finally:
        try:
            context.detach(token)
        except Exception:
            pass

    print("\n--- 输出 ---")
    print(result.raw)


if __name__ == "__main__":
    main()

将上方示例代码保存为app.py，在项目目录下打开终端，通过探针启动应用：

opentelemetry-instrument python app.py

探针会自动采集Crew执行链路中的所有LLM调用、工具调用等数据，无需修改任何业务代码。

查看监控数据

数据上报成功后，可在 AgentArts 智能体平台的观测功能中查看监控数据。

1. 登录AgentArts 智能体平台。
2. 在左侧导航栏选择“观测与优化 > 观测”。
3. 在“智能体列表”页面，找到已接入的智能体，单击智能体名称进入详情页面。

查看业务指标

在“指标分析”页签中，可以查看关键业务指标：

• Tokens消耗：Input Tokens和Output Tokens的消耗总量
• 模型调用次数：应用调用大模型的累计次数
• 模型调用平均耗时：模型调用的平均响应时间
• 模型调用成功率：大模型调用成功的比例
• 会话数：应用产生的会话总数
• 响应成功率：服务响应的成功率

查看调用链信息

在“调用链分析”页签中，可以查看完整的Trace调用链路：

• 查看各Span类型的层级关系及各节点耗时
• 单击具体Span查看详细信息：
  • Crew节点：可查看Crew的Agent编排和任务分配情况
  • Agent节点：可查看Agent角色、目标、输入/输出消息
  • Task节点：可查看任务描述、执行过程和结果
  • LLM节点（chat）：可查看模型名称、输入/输出消息（Input/Output Messages）、Token消耗（Total tokens）
  • Tool节点：可查看工具名称、输入参数、返回结果

查看会话分析

在“会话分析”页签中，可以查看智能体与用户对话的历史数据：

• 追踪对话上下文
• 分析模型响应耗时
• 统计Token消耗
• 快速定位对话异常问题

更多参考

控制内容采集

默认情况下，探针会采集LLM的输入/输出内容。如需关闭：

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false

代码手动插桩

如果无法使用opentelemetry-instrument命令自动插桩，也可以通过创建sitecustomize.py手动初始化：

# --- 关键:在 import crewai / 构造 Agent 之前完成接入 --------------------
from opentelemetry.instrumentation.huawei_crewai import auto_instrument


_auto_instrument_ok = auto_instrument()

# 下面这些 import 必须在 auto_instrument() 之后 —— crewai 模块被 patch 过,
# 晚 import 才能拿到被包装后的类。
from crewai import Agent, Crew, Task  

## ...

if __name__ == "__main__":
    main()

常见问题

无数据上报

1. 确认agentarts_agentops_otel_agent_apm_enable和agentarts_agentops_otel_agent_aom_enable已设置为true，默认值为false不会上报任何数据。
2. 检查环境变量是否正确配置，特别是agentarts_agentops_apm_token、agentarts_agentops_apm_exporter_endpoint等关键参数是否完整且无多余空格。
3. 检查网络连接，确保运行环境能访问APM/AOM端点地址。可通过curl <endpoint>命令验证连通性。
4. 检查凭证是否有效且未过期，可在AgentArts平台的接入指南页面重新获取最新凭证。
5. 查看应用启动日志，搜索opentelemetry或instrument关键字，排查探针初始化是否报错。

部分Span缺失

1. 确认是否通过opentelemetry-instrument python app.py命令启动应用。直接使用python app.py启动将无法触发自动插桩，需改用探针命令启动或参考代码手动插桩进行初始化。
2. 确认CrewAI版本满足最低要求（>= 1.15.0），低版本框架的内部接口可能与探针不兼容。
3. 如使用手动插桩方式，确认探针初始化代码（auto_instrument()）在import crewai之前执行。若CrewAI模块先于探针加载，插桩将无法生效，导致相关Span丢失。

Token统计不准确

1. 确保使用最新版本的探针。
2. 流式场景下确认模型返回了usage字段。
3. 模型在响应中不返回usage字段或返回的Token数为近似值，此为模型侧行为，非探针问题。可在AgentArts调用链详情中确认模型节点的usage字段是否为空。