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

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

框架介绍

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

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

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

接入方式

容器服务 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名称，如未指定则使用默认工作空间。

手动接入探针

步骤一：下载探针安装器 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={worksapce}

## 原有环境

步骤三：使用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

示例代码

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

async def main():
    options = ClaudeAgentOptions(
        model="qwen3-coder-plus",
        permission_mode="bypassPermissions",
        allowed_tools=["Bash", "Glob", "Grep", "Read"],
    )
    async for msg in query(
        prompt="List Python files in the current directory and count total lines",
        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())

查看监控详情

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

接入 Claude Agent SDK 应用