用途:把 Strands Agents(AWS,Python 或 TypeScript)的对话接入 Maple 追踪。每次对话对应一个 Maple Agent Session,每次 agent(...) / invoke_async / stream_async 调用对应一个 turn(一条 trace),包含对话记录、带 token 的 chat span、带参数与结果的 execute_tool span、失败工具标记,以及独立泳道的子智能体。
机制:使用 Strands 原生 OTel tracer(scope strands.telemetry.tracer,gen_ai.provider.name=strands-agents),无需额外埋点包。Maple 读取 session.id(其次 gen_ai.conversation.id)作为会话键,且只读 span 属性,不读 span 事件。
主要能力:Python 需 strands-agents >= 1.51(测试 1.57.1),span 属性内容需 1.48,工具参数/结果需 1.51;TypeScript 使用 @strands-agents/sdk(测试 1.19.0)。安装命令:pip install 'strands-agents[otel]>=1.57'。需设置 OTEL_EXPORTER_OTLP_ENDPOINT(美国 https://ingest.maple.dev,欧盟 https://ingest.eu.maple.dev)、OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <key>"、OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf、OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES 与 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental,gen_ai_span_attributes_only。后者必须在首个 Agent( 构造前写入进程环境,否则 Maple 对话记录为空。
使用方式:Python 用 StrandsTelemetry().setup_otlp_exporter() 初始化一次;TypeScript 用 setupTracer({ exporters: { otlp: true } })。会话 id 通过 trace_attributes 的 session.id 传入(TS 为 traceAttributes),须使用应用已有的对话 id,不能是每请求 uuid4 或常量;共享 Agent 不应携带会话 id。多智能体场景中,Agent 作为工具时只需在编排者上设置;Swarm 在构造时传 trace_attributes;Graph 需在 build() 后设置 graph.trace_attributes。脚本/CLI 需在 finally 中 force_flush() 与 shutdown(),Lambda 每次调用 force_flush(),TS 退出前 await provider.forceFlush() 与 shutdown()。
限制:Maple 不读取 Strands 的 gen_ai.server.time_to_first_token,也不显示成本(显示 unpriced)。脱敏需追加 gen_ai_unredacted_attributes 白名单,被脱敏的值在对话记录中留空。中断/恢复会产生同一会话内的新 trace,被中断的工具 span 会以相同 gen_ai.tool.call.id 出现两次。TS 中失败的 Graph 节点状态为 OK(上游 bug harness-sdk#4166)。不要同时启用 OpenRouter Broadcast 等网关追踪导出,否则 token 会重复计数。验证可在 Maple → Agent Sessions 或 Maple MCP 中检查。