用 Datadog Agent Observability…

当需要评估一次 LLM Agent 会话或 trace 是否真正解决了用户意图、给数据打满意度标签、或为评测流水线生成信号时，用 trace 内容 + RUM 行为 + 审计日志三层证据给出 yes/partial/no 判定。

适用场景

解决思路

1. 先确定后端：若调用参数里出现 --backend pup 就直接用 pup 模式；否则检查工具列表里是否有 mcp__datadog-llmo-mcp__search_llmobs_spans，有则用 MCP 模式；没有则用 Bash 跑 `pup --version`，返回含 "version" 的 JSON 说明可用 pup；两者都没有就停下并提示用户连接 MCP 服务器（`claude mcp add --scope user --transport http datadog-llmo-mcp 'https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=llmobs,rum'`）或安装 pup。
2. pup 模式调用规则：用 Bash 执行 `pup llm-obs <subcommand> [flags]`；pup 直接输出 JSON，无需解包 content block；遇到鉴权错误提示用户运行 `pup auth login` 并停止；多条命令放在同一条消息里并行发出；时间参数用裸时长（1h/7d/30m）或 RFC3339，不要用 now- 前缀（把 now-7d 转成 7d）；批量搜索阶段加 --summary 只保留元数据。
3. 每次调用开始时生成一个 8 位十六进制 invocation ID（如 3a9f1c2b）并在整次调用中保持不变；每次 MCP 调用都在 telemetry.intent 前加 `skill:agent-observability-session-classify[<inv_id>] — ` 加调用原因，仅第一次调用用 `:start[<inv_id>] — ` 前缀。
4. 判断入口模式：给了 session_id 走会话模式；只给 trace_id 走 trace 模式；只给 ml_app 走应用模式；三者都没给立即返回 {"error":"missing_input","detail":"Provide one of: session_id, trace_id, or ml_app."}。
5. 内容读取级联（所有模式通用，必须对每个 turn 跑完才能下判定）：C1 先调 get_llmobs_agent_loop(trace_id, span_id, from="now-90d", to="now", max_content_length=2000) 拿完整系统提示、用户消息、工具调用参数与结果、助手回复；若返回 iterations: [] 或 404 或内容被 REDACTED 则降级。
6. C1 结果过大被落盘时不要直接 Read 整个文件（会超 token 限制），改用 Python 脚本做定向提取：json.loads(json.load(f)[0]['text']) 后遍历 iterations，打印 iteration、status、tool_calls 名称、error_message 和 content 前 300 字符，遇到以 # 开头且超 4000 字符的 content 标记为 [system prompt]。
7. C2 当 C1 返回空 iterations 时，用 expand_llmobs_spans(trace_id, span_ids=[根 agent span], max_depth=2, from="now-90d", to="now") 导航到嵌套在 workflow 包装层下的 LLM span（如 anthropic.request），再对每个 span_kind=llm 且 has_input=true 的节点调 get_llmobs_span_content(field="messages")。
8. C2 的 JSONPath 截断陷阱：path 是在 max_tokens 截断之后才应用的，所以先不带 path 调一次读 total_tokens_approx，再用 path="$.[-5:]" 和 max_tokens=total_tokens_approx+500 重调，拿到最后 5 条消息（用户查询、推理、助手文本、工具调用、工具结果）。
9. C3 当消息被 REDACTED 或 content_info 不含 messages 时，对根 span 调 get_llmobs_span_content(field="input") 和 field="output"，读取应用写入的合成摘要（原始用户查询、最终回复、或 "Investigation completed with status: completed"）。
10. C4 内容全不可得时只用结构信号分类：status（ok/error）、stop_reason、response_truncated、子 span 名称（工具名、workflow 步骤名）、iteration 标签数、时长与 token 数。
11. 完整性门槛：search_llmobs_spans 返回的 input.preview/output.preview（约 200 字符截断）只能用来识别 turn 边界，不能作为判定依据；≤20 轮的会话对每个 turn 跑 C1/C2，>20 轮的会话跑前 5 轮和后 5 轮，外加任何 preview 里出现异常（错误、纠正循环、重复意图、意外工具）的 turn。
12. 并行化：所有 get_llmobs_agent_loop 调用放在同一条消息里一次性发出（N 轮就是 N 个并发调用），不要串行处理，也不要在结果收齐前形成部分判定；只有某个 turn 的 C1 返回 iterations: [] 时才对该 turn 走 C2。
13. 对可疑工具结果做定向下钻：客户端渲染工具（show_content、create_datadog_notebook、edit_datadog_notebook）必须检查——返回 "This tool is handled by the client application..." 表示委托给浏览器、服务端无确认，需看下一轮是否有 client_tool_response，缺失或下一轮用户困惑则视为输出不可见（强负面信号）。
14. 写操作（call_datadog_api、upsert_datadog_dashboard、upsert_widget）要核对结果：403/"not allowlisted" 表示写入被拦截、改动从未生效；404 表示资产不存在；500 表示写入不确定；"Session not found" 表示资源已过期；200/201 带 payload 才是确认成功。
15. 数据查询返回空（search_datadog_metrics、get_datadog_metric、search_datadog_logs、search_datadog_spans）且同一工具迭代超过 5 次时，检查结果是否为空——助手基于 NO_DATA/空数组推理可能产生看似合理但编造的分析（hallucination 失败模式）。
16. 错误迭代：任何 error_message 非空的 iteration 都要确认具体错误、触发工具、以及助手是重试成功还是放弃；瞬时重试属中性，永久 API 限制或重复相同失败属负面。
17. 用 Python 脚本批量筛查：定义 CLIENT_TOOLS、WRITE_TOOLS、FAIL_STRINGS（含 '403','404','500','not allowlisted','not found','session not found','error'），遍历 iterations 打印 error_message、客户端工具结果前 300 字符、以及写操作或命中失败字符串的结果。
18. 会话模式 Step 1：调 search_llmobs_spans(tags={"session_id": "<SESSION_ID>"}, root_spans_only=True, from="now-90d", to="now", limit=500)（pup 模式：`pup llm-obs spans search --query "@session.id:<SESSION_ID>" --root-spans-only --limit 500 --from 90d`）；必须用 tags 参数而非 query 字符串，否则触发全文检索返回整包 span 并耗尽行预算；超过 500 轮用 next_cursor 翻页。
19. 会话模式 Step 1 记录每个根 span 的 trace_id、span_id、start_ms、duration_ms、user_handle、user_id、org_id、product_area、message_id、name、span_kind、input.preview、output.preview，按 start_ms 升序排序，从第一轮标签取会话级身份信息；若无结果则返回 llmobs_not_found。
20. 会话模式 Step 2：调 get_llmobs_span_details(trace_id, span_ids=[agent_span_id]) 读取 evaluations 映射（遍历所有 key，记录 .value/.reasoning/.tags）和 content_info.metadata（query_string、referrer_path、referrer_url、entities_json、user_info_json）；失败或为空则静默跳过；若 metadata 存在则用 get_llmobs_span_content(field="metadata") 取实际 query_string 和 referrer_path。
21. 会话模式 Step 3：对 Step 1 枚举的每个 turn 根 span 跑内容读取级联，所有 C1 调用并行发出，C1 返回空的 turn 再走 C2。
22. 会话模式 Step 4a：先做 ±2 分钟的窄查询定位浏览器会话——analyze_rum_events(event_type="action", filter="@usr.email:<user_handle> @action.type:custom", from=start_ms-120000, to=start_ms+120000, sql_query='SELECT DISTINCT session_id FROM rum LIMIT 10')（pup：`pup rum aggregate --user-email <user_handle> --query "@action.type:custom" --from <start_ms-120000> --to <start_ms+120000> --compute count --group-by @session.id`）；0 条结果则 rum_filter 回退为 @usr.email:<user_handle>，1 条用 @session.id:<id>，多条用 @session.id:(<id1> OR <id2>)。
23. 会话模式 Step 4：以 start_ms 和 rum_filter 定义 pre（start_ms−30min 到 start_ms）、during（start_ms 到 start_ms+session_duration_ms）、post（到 +60min）三个窗口，并行跑 RUM 查询 A（event_type="view"，SQL 取 timestamp、view_url、"@view.time_spent"，注意 time_spent 单位是纳秒）和查询 B（event_type="action"，filter="@action.type:custom <rum_filter>"，用 LIKE 过滤 command-assistant%/workbench%/ai-experiences% 及 'click on Bad response'/'click on Incorrect result'/'click on Submit'）。
24. RUM 缺失或报错时不要中止分类：0 行且用户 30 天内有 RUM 数据 → 降级，标注 rum_coverage: partial — web RUM gap on session date；鉴权/权限错误 → 降级，标注 rum_coverage: partial — auth error on <query>；0 行且 30 天内完全无 RUM → 降级，标注 rum_coverage: unavailable — no RUM data for user；硬规则：绝不能把 RUM 缺失当作负面证据，rum_unavailable 错误码只保留给「协议要求必须有 RUM 且确实没有」的不可恢复场景。
25. RUM 信号分层解读：Tier-A 可单独翻转判定（流式中断/取消、流式期间关闭面板且 1 秒内未重开、导航到助手明确提到的资产 URL、会话结束 60 秒内对产出物做导出/保存/修改/分享、15 分钟内同意图新会话、整体拒绝助手方案）；Tier-B 仅作佐证（停留 <30 秒、会话后跳外部帮助文档、响应前反复开面板、停留 >60 秒、点击助手渲染的 markdown 链接、跳转到主题相邻资源）；Ambiguous 不可单独作证据（展开中间态/推理块、单个工具调用 accept 算弱正面、单个 reject 仅在用户停止发消息或后续全被拒时才算负面、无流式上下文的关闭面板）。
26. 会话模式 Step 4b（当助手创建或编辑了资产时）：用 `pup audit-logs search` 查审计日志（MCP 无等价工具，两种后端都走 Bash）。按优先级：① `--query '@asset.id:<asset_id>' --from "<session_start - 30d, ISO>" --to now --limit 50` 拿修改/删除历史与完整 diff；② Q3 定向 HTTP 路径 `--query '@usr.email:<u> @http.url_details.path:/api/v1/dashboard/<id>'`（notebook 用 /api/v2/notebook/<id>）统计写入次数与时机；③ Q1/Q2 广谱兜底（Q2 需剔除 /api/ui/query/scalar 和 /api/ui/query/timeseries 等高噪声路径）。
27. 审计日志解析：每行正文在 row["attributes"]["attributes"]，字段有 action（created/modified/deleted/accessed）、usr.email、asset.type/id/name、asset.new_value/prev_value（已是嵌套 dict，无需再解析 JSON）、timestamp（ISO8601）；pup 默认降序，用 sorted(..., key=lambda r: r["attributes"]["attributes"]["timestamp"]) 转升序。
28. 审计信号解读：会话后出现 deleted → 强负面；用户 modified 且 widget/cell 数量少于 prev_value → 负面（撤销了助手改动）；数量更多 → 正面（用户扩展了成果）；改了查询/阈值 → 负面；只改 message/tag → 中性；无事件 → 中性偏正面。仪表盘最有用的是 widget 数量差：len(nv["dashboard_definition"]["widgets"]) - len(pv["dashboard_definition"]["widgets"])。
29. Q3 事件按阶段分桶：用 Counter 按 (phase, method, status) 统计，phase 依据 timestamp 落在 pre-session / during / session_end->feedback / post；每个 PUT 是一次写入，200/201 为确认成功，status_code 0 表示浏览器提前离开但服务端几乎肯定已处理，按 200 计。during 的 PUT 200 数应与 trace 的 upsert 工具调用数吻合；session_end 后 10–30 秒且数量匹配的写入是异步工具延迟而非用户操作；超过 30 秒的是用户手动编辑，小簇爆发（约 1 分钟内 5–10 个 PUT）算微调（轻微正面），零个 post-session PUT 算干净接受；被取消的会话 during PUT 为零。
30. 审计日志优雅降级：查询返回 0 行且会话属于外部客户组织时不要报错，在 verbose 输出里标 audit_unavailable 并继续用 trace + RUM 判定（部分外部客户审计轨迹# 如 AP1/SOC2 隔离组织无法通过 pup 访问）。
31. 审计信号不要过度解读：审计衡量的是后端正确性而非用户满意度，缺失写入或没有事件本身不能证明不满意；只有显式用户动作（deleted、手动 modified 删除 widget/cell、手动写入覆盖助手产出）才能翻转判定，后端症状类信号只能佐证。
32. 会话模式 Step 5 判定：yes = 最终回复直接回答用户意图、无负面反馈、无放弃信号；partial = 部分正确，或用户需额外努力才脱困；no = 给出负面反馈、用户放弃、或核心意图结构性不可达。失败模式码（yes 时省略）：wrong_answer、incomplete_answer、broke_existing_state、excessive_turns、context_loss、wrong_tool_use、hallucination、other: <describe>。
33. 默认输出紧凑格式：`verdict: yes | partial | no` 加 `reason: <一句话>`；只有被要求 verbose 时才输出完整 markdown 报告（含会话元数据、用户意图、助手做了什么、核心意图是否满足、失败模式、RUM 行为信号表、审计发现、修正后判定）。
34. trace 模式 Step T1：调 search_llmobs_spans(query="trace_id:<TRACE_ID>", from="now-30d", to="now", limit=50)，找出 parent_id 为 undefined 的根 span，记录其 span_kind（可能是 agent/workflow/llm/其他），提取所有 span kind 和标签（ml_app、service、session_id、investigation.id、issue_id、user_handle、org_id、matched_model_name、stop_reason、current_turn、iteration）。
35. trace 模式按 span 结构判断应用类型：根只有 embedding → 走不可分类守卫；任意位置有 span_kind=agent → Agent 应用；只有 llm span → LLM/chat 应用；根是 retrieval/workflow 且带 LLM 子节点 → 流水线应用。agent span 不一定是根，要在所有 span 里搜 span_kind=agent（可能嵌在 workflow 根下）。
36. trace 模式不可分类守卫：若所有 span 都是 span_kind=embedding 且无 messages 内容，返回 {"error":"unclassifiable_app_type","detail":"All spans are embedding kind with no conversational content. Use status:ok/error rates instead."}；无 span 则返回 llmobs_not_found。
37. trace 模式 Step T2：对根 span（以及不同于根的 agent span）调 get_llmobs_span_details，提取 children_ids、evaluations 映射（遍历所有 key，WARN 状态的 eval 视为不适用）、content_info。
38. trace 模式 Step T3：按内容读取级联依次尝试 agent span（C1）→ LLM 子 span（C2）→ 根 span（C3）→ 结构信号（C4）。已知模式：service:ai_gateway 的 chat_completion-call/messages-call span 用 get_llmobs_span_content(messages) 可靠；generate-summary agent span 内容常被 REDACTED，退回结构信号（子 span 名 classify/suggest-action/add-markdown-links、工具调用、current_turn 标签、status）；assistant agent span 的 agent loop 返回空，改用 get_llmobs_span_content(metadata) 取 query_string、get_llmobs_span_content(output) 取回复。
39. trace 模式 Step T4 判定：yes = 输出直接且完整地完成任务，无错误/截断/拒答；partial = 只完成部分、正确但不完整、或质量下降；no = 未完成任务（幻觉、错误、空响应、错误工具使用、结构性不可达）；内容全 REDACTED 时按结构信号判定（status:error → no；干净完成且子 span 名符合预期 → 倾向 yes）并标注低置信度。紧凑输出在内容部分或完全不可得时加 `confidence: high | medium | low`。
40. 应用模式 Step M1：调 search_llmobs_spans(query="@ml_app:\"<ml_app>\" @status:ok", root_spans_only=true, from="<timeframe>", to="now", limit=100)；无结果返回 no_traces_found；全是 embedding span 返回 unclassifiable_app_type；分类前先扫一遍采样根 span 确认 service、span 名、标签符合预期，剔除明显无关的离群项。
41. 应用模式按根 span kind 决定分类单元：agent → 直接作为单元；workflow/task → 对样本 trace 调 search_llmobs_spans(trace_id=<id>) 找嵌套 agent span；llm → 直接用 LLM span；只有 embedding → 不可分类；混合 → 按 service: 标签分组分别处理。若根 span 是 span_kind: experiment 且带 input/output/expected_output 结构化字段，说明是 LLM Experiments trace，直接用 get_llmobs_span_content(field="input"/"output"/"expected_output") 读根 span，不要走 C1/C2 消息级联。
42. 应用模式确定分组粒度：优先 Option A 用 aggregate_spans(query="service:<service> resource_name:<root_span>", computes=[{field:"*",aggregation:COUNT,output:"count"}], group_by={fields:["@session_id"],limit:1000}) 一次拿到最多 1000 个唯一 ID（pup 模式无此工具，直接跳到 Option B）；Option B 用 search_llmobs_spans 翻页（limit=50，用 cursor）客户端去重业务 ID 标签。
43. 应用模式粒度决策：有 UUID 格式的 session_id → 按 session 分组；有稳定业务 ID（investigation.id、chatid、correlation_id）→ 当作 session 等价物；都没有 → 按 trace 粒度（一个根 span 一个分类单元）。采样最多 sample_limit 个唯一 ID（默认 20，上限 50）。
44. 应用模式 Step M2：所有内容读取调用放在同一条消息里并行发出；session 粒度对每个 session_id 跑会话模式 Step 1–5（有 user_handle 才带 RUM，没有则优雅跳过）；trace 粒度对每个 trace 跑 trace 模式 T1–T4；结果完成即输出，不要等全部完成。每个单元输出紧凑块：`[session|trace]: <id_short> verdict: yes | partial | no reason: <一句话> content: <agent_loop|messages|io|structural>`。
45. 应用模式 Step M3：全部完成后输出汇总，`# Session Classification Summary` 标题是下游技能（eval-trace-rca、eval-pipeline）的检测哨兵，必须原样输出；包含 App/Timeframe/Granularity/Sampled、Root span kind、Content source、Verdict Distribution 表、Failure Mode Frequency 表、Per-Unit Details 表（ID 列显示为 <first8>...<last8> 并链接到 https://app.datadoghq.com/llm/traces?query=session_id:<full_id> 或 trace_id:<full_id>，Reason 列对 yes 用 none）。
46. 错误输出统一 schema：{"mode":"session_id | trace_id | ml_app","id":"<输入 id 或应用名>","error":"<error_code>","detail":"<说明>"}；错误码包括 missing_input、llmobs_not_found、llmobs_content_expired、llmobs_content_masked、rum_unavailable（仅限协议要求 RUM 且确实没有时）、audit_unavailable（非硬错误）、no_traces_found、unclassifiable_app_type。
47. MCP 结果解析安全：写任何遍历 MCP 结果的脚本前，先检查 type(result)、顶层 key、以及 payload 是否嵌在 content block 里（如 [{'type': 'text', 'text': '<json>'}]），需要时先取出内层再 json.loads()，绝不假设 MCP 结果是裸 dict 或 list。
48. pup 工具映射（仅 pup 模式）：search_llmobs_spans → `pup llm-obs spans search --query "@ml_app:A [其他过滤]"`（务必用 --query 过滤 ml_app，--ml-app 标志不可靠会静默返回其他应用的 span）；get_llmobs_span_details → `pup llm-obs spans get-details --trace-id T --span-ids S1,S2`；get_llmobs_span_content → `pup llm-obs spans get-content --trace-id T --span-id S --field F [--path P]`；get_llmobs_trace → `pup llm-obs spans get-trace --trace-id T [--include-tree]`；get_llmobs_agent_loop → `pup llm-obs spans get-agent-loop --trace-id T [--span-id S]`；find_llmobs_error_spans → `pup llm-obs spans find-errors --trace-id T`；expand_llmobs_spans → `pup llm-obs spans expand --trace-id T --span-ids S1,S2 [--max-depth N] [--filter-kind K]`。
49. pup 模式无等价工具的处理：get_llmobs_bits_session 直接跳过；aggregate_spans（Step M1 Option A）不可用，跳过 Option A 直接走 Option B。

适用边界 · 注意事项

• 没有 Datadog 账号、未连接 datadog-llmo-mcp MCP 服务器、也未安装并登录 pup CLI 时无法使用（属于特定工具依赖）。
• 目标应用只有 embedding span、没有对话内容时不可分类，应改用 status:ok/error 比率评估。
• 当 trace 内容被完全 REDACTED 且没有任何 RUM 或审计信号可作补充时，只能给出低置信度判定，不应据此下强结论。