企业官网建设流程全解析

Strands Agents 可观测性完全指南：用 OpenTelemetry 实现模型调用与工具执行的全链路追踪

【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python & TypeScript - any model, any cloud.项目地址: https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk

Strands Agents 是可观测性开箱即用的生产级 AI Agent SDK，Python 与 TypeScript 双语言支持。它内嵌 OpenTelemetry 标准，无需手动埋点，即可自动记录 Agent 全链路轨迹——每一次模型调用、每一次工具执行、每一轮事件循环，连同 Token 用量、延迟和错误状态，都会变成可查询的 Span，让新手也能快速定位 Agent 的“黑盒”问题。

为什么 AI Agent 需要全链路追踪？

普通 Web 应用出问题时，看日志、查链路即可。但 AI Agent 的执行过程是循环 + 决策的：模型可能连续调用多次工具、经历多轮推理才给出答案。当 Agent 答非所问或响应超慢时，你至少需要回答三个问题：

1. 它调用了哪些模型？每轮用了多少 Token，哪个模型最慢？
2. 它执行了哪些工具？哪个工具入参有误、哪个工具超时或报错？
3. 循环卡在哪里？事件循环（event loop）跑到第几轮出问题的？

Strands Agents 通过内嵌的遥测模块给出答案：Agent 启动时自动创建层级化的 Span 树，一次请求就是一条完整的 Trace。核心实现在 strands-py/src/strands/telemetry/ 目录，TypeScript 端对应 strands-ts/src/telemetry/。

追踪的层级结构：一次请求如何被记录

Strands 创建的 Trace 是一个四层嵌套结构，与 Agent 真实执行流程一一对应：

每个 Span 都携带标准gen_ai.*语义属性，例如：

• gen_ai.request.model：模型标识
• gen_ai.usage.input_tokens/gen_ai.usage.output_tokens：Token 用量
• gen_ai.usage.cache_read.input_tokens：缓存命中的 Token 数
• gen_ai.tool.call.id：工具调用唯一 ID
• gen_ai.event.start_time/gen_ai.event.end_time：起止时间戳

这套属性命名遵循 OpenTelemetry GenAI 语义约定，意味着 Jaeger、Grafana、Langfuse、AWS X-Ray 等任何兼容平台都能直接读懂——不用写任何转换代码。Python 端的 Span 创建逻辑见 tracer.py，TypeScript 端等价实现在 tracer.ts。

三步开启全链路追踪：最快配置方法

第 1 步：安装 OpenTelemetry 依赖

Python 端通过可选依赖安装（一行命令）：

pip install 'strands-agents[otel]'

TypeScript 端安装 OpenTelemetry 官方包：

npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

第 2 步：两行代码初始化遥测

Python 端使用StrandsTelemetry类，它会自动创建 TracerProvider 并注册为全局实例：

from strands.telemetry import StrandsTelemetry telemetry = StrandsTelemetry() telemetry.setup_console_exporter() # 开发调试：Span 打印到控制台 telemetry.setup_otlp_exporter() # 生产环境：Span 发送到 OTLP 端点

之后正常创建Agent即可，追踪是自动启用的——所有 Agent 调用、模型请求、工具执行都会生成 Span，无需改动业务代码。

第 3 步：通过环境变量指定收集端点

# OTLP 收集器地址 export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" # 认证请求头 export OTEL_EXPORTER_OTLP_HEADERS="key1=value1,key2=value2"

本地开发时，用 Docker 拉起一个 Jaeger 即可在浏览器中实时查看 Trace 瀑布图，官方步骤见 traces.mdx。

💡 如果你已经配置好全局的 TracerProvider（比如公司统一接入），可以直接跳过StrandsTelemetry，SDK 会自动复用现有配置。

不止于追踪：指标（Metrics）同样内置

除了 Trace，Strands 还自动导出 12 个 OpenTelemetry 指标，覆盖运维最关心的维度：

• 循环指标：事件循环次数、每轮耗时直方图
• Token 指标：输入/输出/缓存读写 Token 用量直方图
• 模型指标：整体延迟、首 Token 延迟（TTFT）
• 工具指标：调用次数、成功次数、失败次数、执行时长

指标常量定义在 metrics_constants.py，采集逻辑见 metrics.py。启用指标只需一行：

telemetry.setup_meter(enable_console_exporter=True, enable_otlp_exporter=True)

配合 Trace 里的trace_id，你可以在监控系统中把「某次请求耗时 30 秒」直接下钻到「第 3 轮的某个工具执行了 28 秒」，这正是全链路追踪的价值所在。

进阶技巧：采样、自定义属性与敏感数据脱敏

高流量场景的采样控制

生产环境 QPS 较高时，用标准 OpenTelemetry 变量控制采样率，降低存储成本：

export OTEL_TRACES_SAMPLER="traceidratio" export OTEL_TRACES_SAMPLER_ARG="0.5" # 只上报 50% 的 Trace

为 Span 打上业务标签

创建 Agent 时传入trace_attributes，把用户 ID、会话 ID 等业务字段挂到所有 Span 上，方便按维度检索：

agent = Agent( model="global.anthropic.claude-sonnet-5", system_prompt="You are a helpful assistant", trace_attributes={"session.id": "abc-1234", "user.id": "u-001"}, )

敏感内容脱敏：保护用户数据

模型输入输出可能包含隐私数据。SDK 提供白名单式脱敏——通过OTEL_SEMCONV_STABILITY_OPT_IN环境变量中的gen_ai_unredacted_attributes=<列表>指定允许明文上报的属性，其余敏感内容（gen_ai.input.messages、gen_ai.output.messages、gen_ai.system_instructions、工具入参出参）统一替换为[REDACTED]。支持*通配前缀（如gen_ai.output.*）。策略实现见 tracer.py 的 _redact 方法。

切换到最新语义约定

如果你的后端支持新版 GenAI 语义约定，可以一次性开启：

export OTEL_SEMCONV_STABILITY_OPT_IN="gen_ai_latest_experimental,gen_ai_tool_definitions"

前者更新属性命名并改用统一的事件格式，后者会把完整工具定义（JSON Schema）附加到 Agent Span 上，排查“模型为什么选错工具”时非常有用。

常见问题速查

小结

Strands Agents 把 OpenTelemetry 的接入成本降到接近于零：安装可选依赖、两行初始化代码、一个环境变量，模型调用与工具执行的全链路追踪即刻生效。它的层级化 Span 结构忠实还原了 Agent 的循环推理过程，内置指标覆盖了 Token 成本与延迟监控，再加上采样、业务标签与脱敏能力，从本地调试到生产排障都能复用同一套遥测管道。可观测性不是上线前的“补票”，而是 Agent 工程的第一课——现在就可以打开你的 Agent 项目，把第一行遥测代码加上。

【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python & TypeScript - any model, any cloud.项目地址: https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk