AgentScope框架智能体接入

前提条件

• Python 环境版本 >= 3.9
• AgentScope 版本 >= 2.0.0

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

在观测界面展示数据不收取任何费用，但智能体数据上报产生的指标及调用链数据将分别上报至AOM和APM服务，会产生相应的管理费用，请在开启前评估成本。具体计费场景如下：

• 调用链：开启后，调用链数据会上报到应用性能管理APM，费用明细请参考APM计费说明。
• 指标：开启后，指标数据会上报到应用运维管理AOM，费用明细请参考AOM计费说明。

AOM和APM服务采用按需计费，并提供一定量的免费额度，超出免费额度部分按实际使用量计费。详细计费规则可参考对应服务的计费说明。

框架介绍

AgentScope是一个面向大语言模型应用开发的全功能多智能体框架，提供了智能体构建、工具集成、中间件系统、团队协作（Leader-Follower 模式）、会话管理、消息总线调度等能力，帮助开发者快速搭建复杂的多Agent协作应用。

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

• Agent 执行链路（invoke_agent）
• LLM 调用（chat）：模型名称、Token用量、输入/输出内容
• 工具调用（execute_tool）：工具名称、输入参数、返回结果
• 流式响应场景的TTFT（首Token时延）和 TBT（Token间时延）

接入方式

示例代码

以下示例展示了一个基于AgentScope的简单Agent应用，包含工具调用：

示例中使用华为云MaaS服务提供的大模型接口，可登录华为云MaaS服务控制台，创建API Key。

图2 创建API Key

import asyncio
import os

from agentscope.credential import OpenAICredential
from agentscope.agent import Agent, ReActConfig
from agentscope.formatter import OpenAIChatFormatter
from agentscope.message import Msg, TextBlock
from agentscope.model import OpenAIChatModel
from agentscope.permission import PermissionContext, PermissionMode
from agentscope.state import AgentState
from agentscope.tool import (
    Toolkit,
    FunctionTool
)


# 定义工具函数
def search_product(keyword: str):
    """根据关键词搜索华为云产品信息"""
    products = {
        "ECS": "弹性云服务器，提供安全可靠、弹性伸缩的云服务器，支持多种规格按需选购",
        "RDS": "关系型数据库服务，支持 MySQL/PostgreSQL/SQL Server，提供高可用和自动备份",
        "OBS": "对象存储服务，海量、安全、高可靠的云存储，适用于数据湖、备份归档等场景",
    }
    return products.get(keyword.upper(), f"未找到 '{keyword}' 相关产品")

def get_product_usecase(service_name: str):
    """查询华为云产品的典型使用场景"""
    usecases = {
        "ECS": "适用场景：Web应用托管、开发测试环境搭建、企业应用迁移上云、高性能计算任务",
        "RDS": "适用场景：电商交易系统、金融业务数据库、企业ERP/CRM系统、移动应用后端存储",
        "OBS": "适用场景：静态网站托管、大数据分析存储、备份与归档、音视频内容分发",
    }
    return usecases.get(service_name.upper(), f"暂无 '{service_name}' 的场景信息")

toolkit = Toolkit(
    tools=[
        FunctionTool(
            func=search_product,
            name="search_product",
            description="根据关键词搜索华为云产品信息"
        ),
        FunctionTool(
            func=get_product_usecase,
            name="get_product_usecase",
            description="查询华为云产品的典型使用场景"
        ),
    ],
)

model = OpenAIChatModel(
    credential=OpenAICredential(
        api_key="<MODEL_API_KEY>",                      # 替换为在华为云 MaaS 控制台申请的 API Key
        base_url="https://api.modelarts-maas.com/openai/v1",
    ),
    model="deepseek-v4-flash",
    stream=False,
    formatter=OpenAIChatFormatter(),
    parameters=OpenAIChatModel.Parameters(temperature=0),
)

# 构建 Bypass 权限上下文，跳过所有工具安全检查，示例代码方便展示，生产代码慎用
perm_ctx = PermissionContext(mode=PermissionMode.BYPASS)
state = AgentState(permission_context=perm_ctx)

# 创建 Agent
agent = Agent(
    name="Friday",
    system_prompt="你是一个华为云产品助手，可以搜索产品信息和查询适用场景。根据用户问题调用合适的工具。",
    model=model,
    toolkit=toolkit,
    react_config=ReActConfig(),
    state=state
)

async def main() -> None:
    # 运行 Agent
    msg = Msg(
        role="user",
        content=[TextBlock(text="帮我介绍一下 ECS 和 OBS，以及它们分别适合用在哪些场景？")],
        name="AgentscopeUser",
    )
    msg = await agent.reply(msg)
    print(f"{agent.name}: {msg.get_text_content()}")

if __name__ == "__main__":
    asyncio.run(main())

将上方示例代码保存为app.py，在项目目录下打开终端。

启动应用：

opentelemetry-instrument python app.py 

探针会自动采集Agent执行链路中的所有LLM调用、工具调用等数据，无需修改任何业务代码。探针会在Agent.__init__ 执行时自动注入HuaweiTracingMiddleware，无需手动添加。

查看监控详情

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

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

查看业务指标

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

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

查看调用链信息

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

• 查看各Span类型的层级关系及各节点耗时
• 点击具体Span查看详细信息：
  • Agent节点（invoke_agent）：可查看Agent名称、输入/输出消息
  • LLM节点（chat）：可查看模型名称、输入/输出消息（Input/Output Messages）、Token消耗（Total tokens）
  • Tool节点：可查看工具名称、输入参数、返回结果
  • 中间件节点：可查看中间件执行耗时

查看会话分析

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

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

更多参考

传递session_id与user_id

探针通过OTel Baggage机制自动传递会话信息。AgentScope框架在Agent执行时会自动从AgentState中提取session_id并设置到Baggage，确保跨Agent调用链路的会话关联。

如需用户分析需要设置user_id手动传递，可在调用前设置 Baggage：

from opentelemetry.baggage import set_baggage
from opentelemetry import context as ctx_api

 context = set_baggage("user_id", "tester")
token = ctx_api.attach(context)
try:
    msg = Msg(
        role="user",
        content=[TextBlock(text="今天北京天气怎么样？顺便查一下 ECS 是什么产品")],
        name="User",
    )
    msg = await agent.reply(msg)
    print(f"{agent.name}: {msg.get_text_content()}")
finally:
    ctx_api.detach(token)

• session_id：会话标识，用于关联同一会话内的多轮调用。
• user_id：用户标识，用于按用户维度统计和过滤。

控制内容采集

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

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false

代码手动插桩

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

import os

os.environ["OTEL_PYTHON_LOG_CORRELATION"] = "True"
os.environ["OTEL_PYTHON_LOG_LEVEL"] = "debug"           # 设置日志级别，可根据情况调整
os.environ["OTEL_PYTHON_LOG_FORMAT"] = "%(asctime)s [%(levelname)s] [trace_id=%(otelTraceID)s span_id=%(otelSpanID)s] %(message)s"

import logging
from opentelemetry.instrumentation.logging import LoggingInstrumentor

root_logger = logging.getLogger()
root_logger.handlers.clear()
root_logger.setLevel(logging.DEBUG)                     # 设置日志级别，可根据情况调整

LoggingInstrumentor().instrument(
    set_logging_format=True,
    log_level=logging.DEBUG                             # 设置日志级别，可根据情况调整，确保 OTel 的 Handler 也接受对应日志级别
)

from opentelemetry.instrumentation.huawei_auto_instrumentation import initialize

initialize()

常见问题

无数据上报

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. 查看应用启动日志，搜索OTEL_PROBE关键字，排查探针初始化是否报错。

Token统计不准确

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

部分Span缺失

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