接入 Claude Agent SDK（Python）应用-云监控(CMS)-阿里云帮助中心

大模型可观测支持通过 Python 探针对 Claude Agent SDK 应用进行可观测。Python 探针是阿里云可观测产品自研的 Python 语言可观测采集探针，基于 OpenTelemetry 标准实现自动化埋点能力。本文介绍如何将 Claude Agent SDK（Python）应用接入云监控 2.0，实时了解 AI 应用运行状态。

框架介绍

Claude Agent SDK 是 Anthropic 推出的开源 Agent 框架，提供简洁的 API 用于构建具有工具使用能力的 AI Agent。它原生支持 Skills，内置 Bash、Glob、Grep、Read 等系统工具，适用于构建代码分析、文档问答等 Agent 应用。

云监控 2.0 大模型可观测对 Claude Agent SDK 的支持范围如下：

语言	SDK 包名	支持的版本范围
Python	`claude-agent-sdk`	3.9–3.14（Python 探针支持的组件和框架）

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

Agent query 调用（模型名称、Token 用量、输入/输出内容）
工具调用链路（Bash、Glob、Grep、Read 及自定义工具）
子 Agent 调用推理过程
错误和异常捕获

接入 Python 探针

接入方式

容器服务 ACK 和容器计算服务 ACS 接入

步骤一：探针接入助手（ack-onepilot）安装

登录容器服务管理控制台，在集群列表页面单击目标集群名称。
在左侧导航栏单击组件管理，然后在右上角通过关键字搜索ack-onepilot。
在ack-onepilot卡片上单击安装。配置相关的参数，建议使用默认值，单击确认。

说明
需要保证ack-onepilot组件版本大于等于5.1.1版本，在上述步骤3中会展示当前安装的ack-onepilot版本。如果已经安装较低版本ack-onepilot，可重复上述步骤1、2，在步骤3中点击升级即可

步骤二：修改配置以启动 AI 应用监控

登录容器服务管理控制台，在左侧导航栏选择集群列表。
在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择工作负载 > 无状态。
切换命名空间，找到待监控的工作负载，点击最右侧操作列的更多图标后，在弹出的对话框中点击YAML编辑。

在YAML文件中将以下labels添加到spec > template > metadata层级下。添加完成后点击更新。

labels:
  aliyun.com/app-language: python # Python应用必填，标明此应用是Python应用。
  armsPilotAutoEnable: 'on'
  armsPilotCreateAppName: "deployment-name"    # 应用在ARMS中的展示名称
  armsPilotAppWorkspace: "workspace"    # 替换为当前workspace名称，如未指定则使用默认工作空间。

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: arms-python-client
  name: arms-python-client
  namespace: arms-demo
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: arms-python-client
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: arms-python-client
        aliyun.com/app-language: python
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-client"
        armsPilotAppWorkspace: "workspace"
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/arms-default/python-agent:arms-python-client

手动接入探针

步骤一：下载探针安装器 aliyun-bootstrap

从PyPI仓库下载探针安装器。

pip3 install aliyun-bootstrap

步骤二：配置环境变量

您需要手动为Python应用添加以下环境变量：

# 方式一：为本SHELL中所有进程添加环境变量
export ARMS_APP_NAME=xxx   # 应用名称。
export ARMS_WORKSPACE=xxx   # 替换为当前Workspace名称。
export ARMS_REGION_ID=xxx   # 对应的阿里云账号的RegionID。
export ARMS_LICENSE_KEY=xxx   # 阿里云 LicenseKey。

# 方式二：为某个进程单独添加环境变量
ARMS_APP_NAME=xxx ARMS_WORKSPACE=xxx ARMS_REGION_ID=xxx ARMS_LICENSE_KEY=xxx aliyun-instrument xxx.py

其中LicenseKey可以通过OpenAPI获取，具体参见获取应用可观测接口返回值中的authToken字段。

（可选）Docker环境安装参考

对于Docker环境，可以参考以下Dockerfile示例修改您的Dockerfile文件。

# 添加环境变量
ENV ARMS_APP_NAME={AppName}
ENV ARMS_REGION_ID={regionId}
ENV ARMS_LICENSE_KEY={licenseKey}
ENV ARMS_WORKSPACE={workspace}

## 原有环境

步骤三：使用aliyun-bootstrap安装Python探针

为了加快安装，建议您使用如下命令先配置镜像仓库。

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && pip config set install.trusted-host mirrors.aliyun.com

安装探针。
```
aliyun-bootstrap -a install
```

步骤四：启动应用

通过ARMS Python探针启动应用

aliyun-instrument python app.py

示例代码

以下示例在完成「接入 Python 探针」步骤后运行。示例使用 claude-agent-sdk 的 query() API，通过只读工具 Glob 和 Read 产生真实的工具调用，使一次业务请求形成 Agent + LLM + Tool 调用链。接入后，云监控 2.0 将自动采集 invoke_agent（Agent 调用）、chat（LLM 推理）、execute_tool（工具调用）三类 Span，并记录 Token 用量和错误属性。

运行前，请先设置以下环境变量：

export ANTHROPIC_API_KEY=<您的 Anthropic API Key>
export ANTHROPIC_BASE_URL=<自定义接入点>      # 可选：仅在使用自定义接入点时设置
export ARMS_APP_NAME=<应用名称>
export ARMS_REGION_ID=<地域 ID>
export ARMS_LICENSE_KEY=<License Key>
export ARMS_WORKSPACE=<工作空间名称>

import asyncio
import os

from claude_agent_sdk import AssistantMessage, query
from claude_agent_sdk.types import ClaudeAgentOptions, ResultMessage


async def main():
    # 通过环境变量传入模型名称；运行前请确保已通过环境变量设置 ANTHROPIC_API_KEY
    options = ClaudeAgentOptions(
        model=os.environ.get("CLAUDE_MODEL", "claude-opus-4-5"),
        allowed_tools=["Glob", "Read"],  # 只开放只读工具，产生确定性工具调用链
    )

    async for msg in query(
        prompt="列出当前目录下的 Python 文件，并显示每个文件的行数",
        options=options,
    ):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if hasattr(block, "text"):
                    print(block.text, flush=True)
        elif isinstance(msg, ResultMessage):
            print(f"\n[Done] {msg.result}")


asyncio.run(main())

配置完成环境变量后，使用以下命令启动应用：

aliyun-instrument python app.py

说明

示例 API 语法（query 函数签名、response message 类型字段名）以 claude-agent-sdk 实际发布版本为准，请在接入时参照包文档确认。生产环境请通过操作系统环境变量或密钥管理服务注入凭证。

查看监控详情

登录云监控2.0控制台，选择目标工作空间，在左侧导航栏选择所有功能 > AI应用可观测。
在AI应用列表页面可以看到已接入的应用，单击应用名称可以查看详细的应用监控数据。

进入应用详情后，在Trace 详情页面可查看完整的 AI 调用链路。左侧筛选面板支持按Span 类型（LLM、TOOL、AGENT）和接口名称过滤；中部展示 Trace 总耗时、Total tokens 等汇总指标，以及瀑布图时间线，可直观呈现 invoke_agent（Agent 调用）、chat（LLM 推理）、execute_tool（工具调用）各 Span 的父子关系与耗时分布。

在 Trace 详情中可核对以下信息：

Agent/LLM/Tool 父子关系：瀑布图中，invoke_agent 为父 Span，chat（LLM 推理）和 execute_tool（工具调用）作为子 Span 嵌套在其下，可确认调用链路结构是否符合预期。
模型名称与 Token 用量：单击 chat 类型的 LLM Span，右侧详情面板展示实际使用的模型名称及本次调用的输入 Token 和输出 Token 数量。
工具名称与参数：单击 execute_tool 类型的 Span，右侧详情面板展示工具名称（如 Glob、Read）及实际传入的参数。
错误信息：若某个 Span 状态为错误，右侧详情面板的 Attributes 或 Events 标签页中展示错误类型和详细信息。