已有代码库接入 LaunchDarkly Agent…

在已有 provider 调用上接入 LaunchDarkly 配置跟踪，用最少改动捕获 Monitoring 标签页需要的 duration、输入/输出 tokens、success/error，以及流式 TTFT。

适用场景

解决思路

1. 先默认选择能匹配调用形态的最高层级；从 Tier 1 往下走，停在第一个适配的层级；不要默认降到底层手写 tracker，否则会产生漂移、漏指标、遗留模式。
2. Tier 1（Managed runner）：Python 用 `ai_client.create_model(...)` 返回 `ManagedModel`，然后 `await model.run(...)`；Node 用 `aiClient.createModel(...)` 返回 `ManagedModel`，然后 `await model.run(...)`；当调用是对话式（聊天历史、按轮次）时优先使用；它自动记录 duration、tokens、success/error，无需任何 tracker 调用。
3. Tier 2（Provider package + `trackMetricsOf`）：Node 用 `tracker.trackMetricsOf(Provider.getAIMetricsFromResponse, () => providerCall())`；Python 用 `tracker.track_metrics_of(Provider.get_ai_metrics_from_response, provider_call)`；当调用形态不是聊天循环（一次性 completion、结构化输出、agent step）且框架/provider 有对应包时使用；wrapper 记录 duration + success/error，tokens 来自包内置 `getAIMetricsFromResponse` extractor。
4. Tier 2 provider packages：Node 有 `@launchdarkly/server-sdk-ai-openai`、`-langchain`、`-vercel`；Python 有 `launchdarkly-server-sdk-ai-openai`、`-langchain`。
5. Tier 3（Custom extractor + `trackMetricsOf`）：仍用同一个 `trackMetricsOf` wrapper，但自己写一个小函数把 provider response 映射为 `LDAIMetrics`（tokens + success）；当没有 provider package 时使用（Anthropic direct、Gemini、Cohere、custom HTTP）；wrapper 记录 duration + success/error，tokens 来自自定义 extractor。
6. Tier 4（Raw manual）：分别调用 `trackDuration`、`trackTokens`、`trackSuccess` / `trackError`，流式时再加 `trackTimeToFirstToken`；当需要流式 TTFT、异常响应形态、部分跟踪、或 Tier 2–3 无法干净 wrap 时使用；只记录显式调用的内容，必须自己确保不漏。
7. 所有 provider（OpenAI、LangChain、Vercel、Bedrock、Anthropic、Gemini、custom HTTP）都使用同一通用形态：Node 为 `tracker.trackMetricsOf(getAIMetricsFromResponse, () => providerCall())`，Python 为 `tracker.track_metrics_of(get_ai_metrics_from_response, provider_call)`。
8. 每个 provider 只改变 extractor：从匹配的 `@launchdarkly/server-sdk-ai-<provider>`（或 `ldai_<provider>`）包导入 `getAIMetricsFromResponse`，或写一个小自定义函数返回 `LDAIMetrics`；不要寻找 provider-specific tracker 方法。
9. 探索现有调用点：找到 provider 调用并回答 shape：是 chat loop（history + turn-based）、one-shot completion、agent step 还是其他；这决定 Tier 1 vs Tier 2。
10. 探索 framework：是 raw provider SDK、LangChain / LangGraph、Vercel AI SDK、CrewAI、Strands 还是其他；这决定哪个 Tier-2 provider package（如有）适用。
11. 探索 provider：OpenAI、Anthropic、Bedrock、Gemini、Azure、custom HTTP？与 package availability matrix 交叉核对。
12. 探索 streaming：如果是流式，需要 TTFT tracking，因此即使其余部分是 Tier 2，TTFT 部分也要 Tier 4。
13. 探索 language：Python 还是 Node？两者的 provider-package coverage 不同。
14. 探索是否已有 config：如果没有，先转到 `configs-create`；tracking 需要 tracker，tracker 通过调用 config 对象上的 `create_tracker()` / `createTracker()` 获得，而 config 对象来自 `completion_config()` / `completionConfig()` / `createModel()`。
15. 检查是否使用当前 SDK API：如果调用点使用 `aiclient.config(...)` / `aiClient.config(...)` 或构造 `AIConfig(...)` / `LDAIConfig` default，则处于 pre-0.20 接口；在加 tracking 前先迁移。
16. 迁移 `aiclient.config(...)`：对 one-shot/chat 改为 `aiclient.completion_config(...)`，对 agent mode 改为 `aiclient.agent_config(...)`，并镜像 call signature；Node 用 camelCase。
17. 迁移 `AIConfig(...)` default：改为 `AICompletionConfigDefault(...)` 或 `AIAgentConfigDefault(...)`（Node：`LDAICompletionConfigDefault` / `LDAIAgentConfigDefault`）；`AIConfig` 是 SDK 返回的基类，不是有效的 default-value 构造函数，带类型的 `*Default` 变体才是。
18. 如果结果被 tuple-unpacking（`config, tracker = aiclient.config(...)`），去掉解包；新方法返回单个 config 对象；通过 `config.create_tracker()` / `aiConfig.createTracker()` 获取 tracker。
19. 对更深的重写（调用点还硬编码 model/prompt 等），转交 `migrate`，而不是在这里做完整迁移。
20. 使用 Tier-2 选项矩阵决定是否有 Tier 2；如果矩阵中没有，降到 Tier 3（custom extractor）；如果形态是 chat-loop，不管矩阵如何都先走 Tier 1。
21. Tier-2 矩阵：OpenAI（direct SDK）Python `launchdarkly-server-sdk-ai-openai`，Node `@launchdarkly/server-sdk-ai-openai`，参考 `references/openai-tracking.md`。
22. Tier-2 矩阵：LangChain / LangGraph Python `launchdarkly-server-sdk-ai-langchain`，Node `@launchdarkly/server-sdk-ai-langchain`，参考 `references/langchain-tracking.md`。
23. Tier-2 矩阵：Vercel AI SDK Python 无，Node `@launchdarkly/server-sdk-ai-vercel`，使用 Vercel provider docs。
24. Tier-2 矩阵：AWS Bedrock（Converse 或 InvokeModel）Python 无（用 LangChain-aws 或 custom extractor），Node 无（用 LangChain-aws 或 custom extractor），参考 `references/bedrock-tracking.md`。
25. Tier-2 矩阵：Anthropic direct SDK Python 无，Node 无，参考 `references/anthropic-tracking.md`。
26. Tier-2 矩阵：Gemini / Google GenAI Python 无，Node 无，参考 `references/gemini-tracking.md`。
27. Tier-2 矩阵：Strands Agents Python 无（Tier 3 custom extractor），Node 无（Tier 3 custom extractor），参考 `references/strands-tracking.md`。
28. Tier-2 矩阵：Cohere、Mistral、custom HTTP 无包，用 Tier 3 custom extractor。
29. Tier-2 矩阵：Any provider, streaming + TTFT Python 无（仅 Tier 4），Node `trackStreamMetricsOf`（不含 TTFT）+ manual TTFT，参考 `references/streaming-tracking.md`。
30. 确定 tier 和 provider 后，打开对应 reference 文件并遵循 pattern；reference 中 Tier 1 总是第一个示例，Tier 2/3 其次，Tier 4 最后；停在第一个与 app shape 匹配的 tier。
31. 所有 tier 的 guardrail：在做 tracked call 前始终检查 `config.enabled`；disabled config 表示用户关闭了 feature，应短路到 app 的 fallback（cached response、error、degraded path），而不是发起 provider call。
32. Guardrail：只 wrap 现有调用，不要重写它；Tier 2 和 Tier 3 设计为围绕未修改的 provider call；如果你为了适配 tracker 而重写调用，说明层级选错了，应下降一层。
33. Guardrail：错误在 `trackMetricsOf` 内部处理；wrapper 捕获异常、内部记录 `trackError()`、并重新抛出；不要在外部再加 `except: tracker.trackError()`，那是 noop 且会触发 at-most-once guard；Tier 1 自动处理两条路径；Tier 4（manual、streaming、`track_duration_of`）调用方自己负责错误跟踪调用。
34. Guardrail：关闭前始终 flush；调用 `ldClient.flush()`（Python：`ldclient.get().flush()`；Node：`await ldClient.flush()`）后再关闭 client；否则尾部事件可能丢失，短生命周期脚本和长运行服务都一样；Node 中 `ldClient.close()` 返回 Promise，要 await 它。
35. 验证：通过 instrumented path 运行一次真实请求。
36. 验证：在 LaunchDarkly 中打开 config 的 Monitoring tab；Duration、token counts、generation counts 应在 1–2 分钟内出现。
37. 验证：强制制造错误（bad API key、zero `max_tokens` 等），确认 error count 增加。
38. 验证：如果是 streaming，确认 TTFT 出现；如果没有出现，可能是你用 `trackMetricsOf` wrap 了 stream creation，但没有加手动 `trackTimeToFirstToken` 调用；见 `references/streaming-tracking.md`。
39. 获取 tracker：通过 config 对象上的 factory：Python `tracker = config.create_tracker()`，Node `const tracker = aiConfig.createTracker()`。
40. 每次执行只调用一次 factory，并对每个调用复用返回的 tracker；每次 factory 调用都会生成新的 `runId`，用来标记该 tracker 发出的每个 tracking event，以便关联同一次执行的事件（通过 exported events / downstream systems）；Monitoring tab 目前聚合事件，不按 run 分组；`runId` 在导出或 UI 外查询事件时有用，也是 SDK at-most-once guards 的 key。
41. 大多数时候不要单独调用 raw tracker methods；使用 `trackMetricsOf` 或 Tier-1 managed runner；以下列表用于识别现有代码中的方法，并真正需要 Tier 4 时选用正确方法。
42. `track_metrics_of(extractor, fn)` / `trackMetricsOf(extractor, fn)`：Tier 2/3；包装 provider call，捕获 duration + success/error，调用 extractor 获取 tokens；这是默认的通用 tracker。
43. `track_metrics_of_async(extractor, fn)`（Python）：Tier 2/3；上述的 async 变体。
44. `trackStreamMetricsOf(extractor, streamFn)`（仅 Node）：Tier 2/3；streaming 变体；当 extractor 处理 chunks 时捕获 per-chunk usage；不会自动捕获 TTFT。
45. `track_duration(ms)` / `trackDuration(ms)`：Tier 4；以毫秒记录 latency。
46. `track_duration_of(fn)` / `trackDurationOf(fn)`：Tier 4；包装 callable 并自动记录 duration；不捕获 tokens 或 success，需配合显式调用。
47. `track_tokens(TokenUsage)` / `trackTokens({input, output, total})`：Tier 4；记录 token usage。
48. `track_time_to_first_token(ms)` / `trackTimeToFirstToken(ms)`：Tier 4；为 streaming responses 记录 TTFT。
49. `track_success()` / `trackSuccess()`：Tier 4；把 generation 标为成功；Monitoring tab 计数需要它。
50. `track_error()` / `trackError()`：Tier 4；把 generation 标为失败；不要在同一请求中再调用 `trackSuccess()`。
51. `track_feedback({kind})` / `trackFeedback({kind})`：任意 tier；记录 feedback UI 的 thumbs-up / thumbs-down；独立于 success/error 路径。
52. `track_tool_call(name)` / `trackToolCall(name)`：任意 tier；按名称记录单次 tool invocation；两个 SDK 都可用。
53. `track_tool_calls([names])` / `trackToolCalls([names])`：任意 tier；批量变体，一次记录一组 tool invocations。
54. `track_judge_result(result)` / `trackJudgeResult(result)`：任意 tier；记录程序化 judge evaluation；`result.sampled` 表示 evaluation 是否运行。
55. 相关技能：如果没有 config，先使用 `configs-create`。
56. 相关技能：在 agent metrics 之上叠加业务指标（conversion、resolution、retention）时使用 `custom-metrics`。
57. 相关技能：对抽样 live requests 做自动质量评分（LLM-as-judge）时使用 `online-evals`；与本技能指标互补。
58. 相关技能：hardcoded-to-AgentControl migration 的 Stage 4 交给 `migrate` 技能。

适用边界 · 注意事项

• 没有 LaunchDarkly 服务端 AI SDK（`launchdarkly-server-sdk-ai>=0.20.0` 或 `@launchdarkly/server-sdk-ai>=0.20.0`）或没有现有 config/tracker 时，不适用；应先用 `configs-create` 创建 config。
• 如果不需要 LaunchDarkly 的 agent metrics/Monitoring，或要采集的是业务指标、在线评估而非 duration/tokens/success/error/TTFT，则不要用此技能；考虑 `custom-metrics` 或 `online-evals`。
• 如果调用点处于 pre-0.20 API 且不愿先迁移，或需要大幅重写硬编码 model/prompt，则不要在此技能内硬做；转交 `migrate`。