migrate

迁移到 AgentControl

你正在使用一项技能，它将引导你把应用从硬编码的大模型提示词迁移到完整的 LaunchDarkly AgentControl 实现。你的任务是分 五个阶段 运行迁移，并在每个阶段暂停，等待用户确认：

1. 审查代码 — 以只读方式扫描，生成一份结构化清单，列出所有硬编码内容（提示词、模型、参数、工具、应用级开关）。
2. 封装调用 — 安装 SDK，在 LaunchDarkly 中创建配置，并使用与硬编码值一致的回退值，然后重写调用点，使其在每次请求时都获取最新配置。
3. 迁移工具 — 提取每个工具的 JSON 架构，将其附加到配置，并替换所有引用旧工具列表的调用点。
4. 添加跟踪 — 在提供商调用周围接入逐请求跟踪器（时长、令牌、成功／错误）。
5. 附加评估器 — 通过 Playground + Datasets 进行离线评估，或使用在线评判器自动为抽样流量评分。

⚠️ 避免首次运行时的三种故障模式。

1. 跟踪器作用域错误。 对于带循环的 Agent，应在 setup_run 入口节点中，每个用户轮次创建一次 create_tracker()，而不是在 call_model 中创建。每次迭代都调用工厂函数会生成 N 个 runId，并触发至多一次保护。请参阅 agent-mode-frameworks.md § Custom StateGraph。
2. 重复使用 load_chat_model 封装器。 langchain-ai/react-agent 之类的模板会提供 load_chat_model(f"{provider}/{name}") 助手函数，该函数封装了 init_chat_model(...)，并会静默丢弃所有变体参数。删除它（不要只是避免使用），并将调用点替换为 create_langchain_model(ai_config)。
3. 运行 /configs-create 后未切换回退配置。 新创建的配置的回退配置会指向一个自动生成的禁用变体，因此在运行 /configs-targeting 之前，SDK 会返回 enabled=False。请在第 2 阶段验证之前切换它。

覆盖范围 — 哪些模式已有充分示例，哪些需要推演

此技能针对 Python 和 Node.js / TypeScript 进行了优化；其他语言仅涵盖安装。在 Python 和 Node.js 中，覆盖层级如下：

模式	Python	Node.js	参考资料
一次性补全（直接调用 OpenAI / Anthropic / Bedrock / Gemini）	✅ 已提供示例	✅ 已提供示例	before-after-examples.md，built-in-metrics/references/ 中各提供商的文档
通过托管运行器（ManagedModel）进行聊天循环	✅ Tier 1 模式	✅ Tier 1 模式	built-in-metrics SKILL.md
LangChain 单次调用	✅ 已提供示例	✅ 已提供示例	langchain-tracking.md
LangGraph 预构建 Agent（Python langchain.agents.create_agent，Node createReactAgent）	✅ 已提供示例	✅ 已提供示例	agent-mode-frameworks.md § LangGraph
使用运行范围内的跟踪器（setup_run + call_model + finalize）的 LangGraph 自定义 StateGraph	✅ 深入示例	⚠️ 仅有提及——需从 Python 示例转换	agent-mode-frameworks.md § Custom StateGraph
CrewAI Agent	✅ 已提供示例	—（不是 Node 框架）	agent-mode-frameworks.md § CrewAI
Strands Agent	✅ 已提供示例	⚠️ 仅支持 BedrockModel + OpenAIModel（不支持 Anthropic）	agent-mode-frameworks.md § Strands
自定义 ReAct 循环（手动编写，可使用任意框架或不使用框架）	✅ 已提供示例	⚠️ 应用框架无关的不变规则；从 Python 示例转换	agent-mode-frameworks.md § Custom ReAct loop
Vercel AI SDK（generateText / streamText）	—（不是 Python 框架）	⚠️ 存在提供商软件包；技能中没有示例	built-in-metrics 提供商软件包矩阵
流式处理（SSE / WebSocket）	⚠️ 委托给 built-in-metrics 流式处理文档	⚠️ 同上——使用 trackStreamMetricsOf + 手动计算 TTFT	streaming-tracking.md
多 Agent 图（监督者 + 工作节点）	⚠️ 不在主要范围内；请参阅参考资料	⚠️ 不在主要范围内；请参阅参考资料	agent-graph-reference.md
非 LangGraph Agent 框架（Pydantic AI、DSPy、AutoGen、Haystack、LlamaIndex agents、Semantic Kernel）	⚠️ 应用三条不变规则；无针对特定框架的示例	⚠️ 同上	agent-mode-frameworks.md § Framework-agnostic invariants
Go、Ruby、.NET	ℹ️ 仅提供安装命令	ℹ️ 仅提供安装命令	phase-1-analysis-checklist.md § SDK routing table

图例： ✅ = 按照技能原样操作；⚠️ = 架构适用，但需要转换惯用写法或交叉参考其他技能；ℹ️ = 技能内容不超出安装步骤。

如果目标应用位于 ⚠️ 列，请先阅读 agent-mode-frameworks.md § Framework-agnostic invariants — 这三条规则（每轮一个 agent_config、每轮一个跟踪器、至多触发一次的方法在轮次结束时触发）适用于任何框架，而本技能中的每段代码示例都是这些规则的一种具体实现。将 Python 示例的模式转换为目标框架的原语。

前置条件

此 skill 要求在环境中配置远程托管的 LaunchDarkly MCP 服务，并且应用已使用硬编码的模型、提示词和参数值调用 LLM 提供商。

所需环境：

• LD_SDK_KEY — 来自目标 LaunchDarkly 项目的服务端 SDK 密钥（以 sdk- 开头）

**此 skill 直接使用的 MCP 工具：**无 — 所有 LaunchDarkly 写入操作都由专门的同级 skill 完成。

应用任何模式前，请先检查 SDK CHANGELOG。 本 skill 全文描述的 API 表面以本 skill 最后更新时的 SDK 行为为准；SDK 发布版本可能会重命名、移除或拆分方法。开始前，请获取目标 SDK 的最新 CHANGELOG，并浏览其中是否有与即将应用的模式相矛盾的内容：

• Python：https://github.com/launchdarkly/python-server-sdk-ai/blob/main/packages/sdk/server-ai/CHANGELOG.md（以及 packages/ai-providers/server-ai-{openai,langchain}/CHANGELOG.md 下各提供商的 CHANGELOG）
• Node：https://github.com/launchdarkly/js-core/blob/main/packages/sdk/server-ai/CHANGELOG.md（以及 packages/ai-providers/server-ai-{openai,langchain,vercel}/CHANGELOG.md 下各提供商的 CHANGELOG）

如果 CHANGELOG 中有晚于本 skill 发布的条目，且修改了即将使用的 API，以 CHANGELOG 为准 — 并应更新本 skill。

交接模式。 本 skill 不会自动调用其他 skill。在每个需要执行 LaunchDarkly 写入操作的阶段，本 skill 会准备好输入（配置键、模式、模型、提示词、工具架构、评估器键），然后告知用户自行运行下一个斜杠命令。用户完成该同级 skill 后，再返回此处继续下一步。请将下方的“委派”行视为下一步说明，而非自动交接。

用户在各阶段运行的同级 skill：

• projects — 第 2 阶段前，仅当尚无项目时
• configs-create — 第 2 阶段（创建配置和首个变体）
• tools — 第 3 阶段（创建工具定义并将其附加）
• configs-targeting — 第 2 阶段与第 4 阶段之间（将新变体提升为回退变体，以便 SDK 实际提供该变体）
• online-evals — 第 5 阶段（附加评估器并创建自定义评估器）

核心原则

1. 先检查，再修改。 每个阶段都从只读审查开始。只有用户确认步骤 1 后，才能修改代码。
2. 替换配置，而非业务逻辑。 SDK 调用是对定义模型、参数和提示词的位置的直接替换 — 而不是对提供商调用本身的替换。OpenAI/Anthropic/Bedrock 调用仍保留原位。
3. 回退行为应与当前行为一致。 传给 completion_config / agent_config 的回退值必须保留已移除的硬编码值，以便 LaunchDarkly 无法访问时应用行为保持不变。
4. 阶段有先后顺序。 先封装，再添加工具；先添加工具，再跟踪；先跟踪，再添加评估。跳过步骤会导致配置没有流量、指标缺少上下文，以及评估器没有可评分的内容。
5. 手动交接给专门的 skill。 每个需要执行 LaunchDarkly 写入操作的阶段，都会告知用户运行同级斜杠命令（/configs-create、/tools、/configs-targeting、/online-evals），并等待用户返回。本 skill 不会自动调用其他 skill。

工作流

最小可行迁移

阶段 1–4（审计、封装、工具、跟踪器）均可独立交付。迁移在阶段 4 结束时就已完成，可用于生产环境，并实现了核心价值——外置提示词和模型配置、定向、变体 A/B 测试，以及「监控」标签页指标。阶段 5（评估器）是提升使用体验的补充项，并非上线门槛。不要因为评估器而阻止阶段 4 上线；先交付按运行范围跟踪器方案，验证指标正常流转，然后等团队有时间整理数据集时再完成阶段 5。

不过，不要跳过阶段 4。没有跟踪器的迁移只能外置提示词，却无法查看运行情况，这会让你错失大部分预期收益。

第 1 步：审查代码库（阶段 1）

这是第一个阶段。此阶段为只读——不写入代码，也不创建 LaunchDarkly 资源。目标是扫描仓库，生成一份结构化清单，列出所有需要迁移的硬编码值，然后将清单交给用户确认，再进入阶段 2 修改代码。

使用 phase-1-analysis-checklist.md 扫描：

1. 语言和包管理器——Python（pip/poetry/uv）、TypeScript/JavaScript（npm/pnpm/yarn）、Go、Ruby、.NET
2. LLM 提供方——OpenAI、Anthropic、Bedrock、Gemini、LangChain、LangGraph、CrewAI、Strands
3. 现有的 LaunchDarkly 用法——是否已有可复用的 LDClient 或 ldclient 初始化代码
4. 硬编码的模型配置——模型名称字符串字面量、temperature / max_tokens / top_p、系统提示词、指令字符串
5. 提示词中的模板占位符——.format() 调用、提示词常量中的 f 字符串、JS/TS 模板字面量、%(var)s、手动编写的 str.replace("__VAR__", ...)。标记每个占位符名称及其运行时值来源；在阶段 2 中，所有占位符都会改写为 Mustache {{ variable }}。
6. 外置提示词文件——扫描 YAML / JSON / TOML / Markdown / .prompt / .j2 文件，以及提示词模板注册表（langchain.hub.pull(...)、LangSmith client.pull_prompt(...)），查找运行时加载的提示词。常见形式：CrewAI agents.yaml / tasks.yaml、LangChain Promptfiles、k8s ConfigMap 覆盖项、包含 prompt_* 字段的 Pydantic Settings 类。如果占位符语法不同，同样需要按阶段 2 的第 5 个子步骤进行 Mustache 改写。参见 phase-1-analysis-checklist.md § 4。
7. 硬编码的应用级配置项——搜索结果上限、重试预算、工具超时覆盖项、功能开关，以及任何不属于提示词或模型参数、但仍会影响 Agent 行为的配置数据类字段。这些应放在变体的 model.custom 中（而不是 model.parameters 中；后者会转发给提供方 SDK，遇到未知关键字参数时会导致崩溃）。
8. 模式决策——补全模式（聊天消息数组）或 Agent 模式（单个指令字符串）。补全模式为默认模式，也是唯一支持在 UI 中附加裁判的模式。

对于审查发现的每个硬编码目标，记录：

• 文件路径和行范围
• 当前值（模型名称、完整提示词文本、参数字典）
• 目标配置字段（model.name、model.parameters.temperature、messages[].content、instructions）
• 周边调用是否使用函数调用 / 工具（决定阶段 3 的工作）
• 周边调用是否包含重试逻辑（影响阶段 4 中跟踪器调用的位置）

此清单是接下来四个阶段的约定依据。

阶段 1 输出（以结构化摘要的形式返回给用户）：

Language: Python 3.12
Package manager: uv
LLM provider: OpenAI
Existing LD SDK: none
Target mode: completion
Hardcoded targets:
  - src/chat.py:42   model="gpt-4o"
  - src/chat.py:43   temperature=0.7, max_tokens=2000
  - src/chat.py:45   system="You are a helpful assistant..."
Externalized prompt files: none (or e.g. "prompts/agents.yaml — CrewAI role/goal/backstory")
Prompt-template registries: none (or e.g. langchain.hub.pull("rlm/rag-prompt") at app.py:14)
Coverage totals: 3 hardcoded code targets · 0 externalized prompt files · 0 registry pulls
Proposed plan: single config key `chat-assistant`, mirror fallback, Stage 3 (tools) skipped (no function calling), Stage 4 (tracking) inline, Stage 5 (evals) attach built-in accuracy judge.

停止。 展示此摘要，明确说明覆盖范围统计（例如：“我发现了 N 个硬编码代码目标和 M 个外置提示词文件——这符合您的预期吗？”），并等待用户以以下四种明确形式之一回复：

• confirm——继续进入阶段 2。
• add: <files or paths>——使用新增位置重新审查，并展示更新后的摘要。
• fix: <correction>——更新列表中的目标（提供方、模式、提示词内容等），然后再次询问。
• stop——在此暂停迁移。

不要将任何其他词语——包括 skip、next、go、ok、proceed——视为确认；请让用户从上述四种形式中选择。这是工作流中最重要的检查点——如果审查有误，之后的每个阶段都会出错。用户应先将硬编码目标列表与自己了解的代码内容进行核对，再批准继续。

第 2 步：使用 AI SDK 封装调用（阶段 2）

这是第一个会写入代码的阶段。包含九个子步骤。

1. 删除审计标记的所有手写模型／工具封装。 在安装新 SDK 之前完成此操作，这样替换内容才能落在没有易混淆的回退导入的代码库中。第 1 阶段审计应当找出以下两种形式：

   • load_chat_model(f"{provider}/{name}") 或任何 init_chat_model(...) 封装。 langchain-ai/react-agent 和许多衍生代码库都自带此类封装。删除该函数及其模块；替换项是 create_langchain_model(ai_config)（将在下一子步骤中安装）。保留此封装意味着本代码库的下一次编辑会导入熟悉的辅助函数，并悄悄丢弃变化参数。
   • 手写的 resolve_tools / TOOL_REGISTRY / ALL_TOOLS 辅助函数，它们会硬编码静态工具列表。 删除它们；ldai_langchain.langchain_helper.build_structured_tools(ai_config, TOOL_REGISTRY_DICT) 是标准替代项，并将在第 3 阶段接入。如果保留手写版本，两种形式就会并存，下一位贡献者会选择熟悉的那个。

   如果代码库的审查流程有此需要，可将删除操作与 SDK 安装分开提交；否则与子步骤 2 合并。

2. 安装 AI SDK。 根据步骤 1 检测包管理器，然后安装：

   • Python：launchdarkly-server-sdk + launchdarkly-server-sdk-ai>=0.20.0
   • Node.js/TypeScript：@launchdarkly/node-server-sdk + @launchdarkly/server-sdk-ai@^0.20.0
   • Go：github.com/launchdarkly/go-server-sdk/v7 + github.com/launchdarkly/go-server-sdk-ai

   Tier-2 提供方包（在第 4 阶段安装，仅当你使用对应提供方时）：

   • OpenAI：launchdarkly-server-sdk-ai-openai>=0.4.0（Python）/ @launchdarkly/server-sdk-ai-openai@^0.5.5（Node）
   • LangChain / LangGraph：launchdarkly-server-sdk-ai-langchain>=0.5.0（Python）/ @launchdarkly/server-sdk-ai-langchain@^0.5.5（Node）
   • Vercel AI SDK（仅 Node）：@launchdarkly/server-sdk-ai-vercel@^0.5.5
   • Anthropic、Gemini、Bedrock——尚未发布提供方包；请使用 Tier-3 自定义提取器（参见 built-in-metrics）

3. 在启动时初始化一次 LDAIClient。 复用任何现有的 LDClient——不要创建第二个基础客户端。将初始化放在负责现有应用配置的同一模块中。

   Python：

   import os
   import ldclient
   from ldclient.config import Config
   from ldai.client import LDAIClient
   
   # Order matters: ldclient.get() raises if called before ldclient.set_config().
   # The set_config call is what initializes the singleton; .get() just returns it.
   sdk_key = os.environ.get("LD_SDK_KEY")
   if sdk_key:
       ldclient.set_config(Config(sdk_key))
   else:
       # Missing key: init in offline mode so the app still starts and the fallback
       # path runs on every call. Never raise at import time for a missing env var —
       # that turns a config gap into a boot failure.
       import logging
       logging.getLogger(__name__).warning(
           "LD_SDK_KEY not set; configs will use fallback values only."
       )
       ldclient.set_config(Config("", offline=True))
   
   ai_client = LDAIClient(ldclient.get())
   

   Node.js/TypeScript：

   import { init } from '@launchdarkly/node-server-sdk';
   import { initAi } from '@launchdarkly/server-sdk-ai';
   
   // The Node SDK does not have an explicit offline mode — a missing or invalid
   // key fails fast during waitForInitialization, and every agent_config /
   // completion_config call returns the fallback. Log a warning; do not throw.
   if (!process.env.LD_SDK_KEY) {
     console.warn('LD_SDK_KEY not set; configs will use fallback values only.');
   }
   const ldClient = init(process.env.LD_SDK_KEY ?? 'sdk-offline');
   await ldClient.waitForInitialization({ timeout: 10 }).catch(() => {
     // Swallow init failures in offline mode; fallback path runs.
   });
   const aiClient = initAi(ldClient);
   

4. 移交给 configs-create。 打印第 1 阶段清单中提取出的模型、提示词／指令、参数和模式，然后告诉用户：“使用这些输入运行 /configs-create，然后回到这里。” 提供你希望代码调用的配置键（例如 chat-assistant）。不要尝试自动调用同级技能——等待用户完成后再继续。

   configs-create 完成后，用户还必须运行 /configs-targeting，将新变体提升为回退值。 新创建的变体在更新定向之前，对所有使用者返回的都是 enabled=False。如果跳过此步骤，第 2 阶段验证（下方子步骤 9）将在每次请求中悄悄走回退路径。

5. 将模板占位符改写为 Mustache 语法。 如果硬编码提示词使用 Python .format()、f 字符串、JS 模板字面量或任何其他非 Mustache 语法（例如 {system_time}、${userName}、%(topic)s）插入运行时值，请将所有占位符改写为 {{ variable }} 形式的 Mustache 语法。请同时修改即将发送给 /configs-create 的文件和子步骤 6 中要编写的回退字符串。AI SDK 会通过 Mustache 渲染器，在 LD 提供的路径和回退路径中插入变量；回退路径通过 completion_config(...) / completionConfig(...) 的第四个参数 variables 字典提供变量。如果回退字符串中保留 Python 风格的 {system_time} 字面量，那么当 LaunchDarkly 无法访问时就会导致隐蔽回归——渲染器不会匹配单花括号形式，字面量 {system_time} 会作为提示词的一部分发送给提供方。

   之前：

   SYSTEM_PROMPT = "You are a helpful assistant. The time is {system_time}."
   prompt = SYSTEM_PROMPT.format(system_time=datetime.now().isoformat())
   

   迁移后（源代码中）：

   SYSTEM_PROMPT = "You are a helpful assistant. The time is {{ system_time }}."
   # .format() is removed at the call site — the SDK interpolates via `variables`
   config = ai_client.completion_config(
       CONFIG_KEY,
       context,
       fallback,
       variables={"system_time": datetime.now().isoformat()},
   )
   

   常见的改写形式：

   • Python "{var}" / "{var!s}" / "%(var)s" → "{{ var }}"
   • 提示词字符串中的 JS/TS `${var}` 模板字符串 → "{{ var }}"
   • 任何手写的 str.replace("__VAR__", value) 方案 → "{{ var }}"

   有关回退专用变体，请参阅 fallback-defaults-pattern.md § 模板占位符。

6. 构建回退配置。 将提取出的硬编码值映射到回退配置中。Python 中使用 AICompletionConfigDefault / AIAgentConfigDefault，Node 中使用普通对象字面量。有关内联、基于文件和通过引导程序生成的模式，请参阅 fallback-defaults-pattern.md。

   Python 回退配置（completion 模式）：

   from ldai.client import AICompletionConfigDefault, ModelConfig, ProviderConfig, LDMessage
   
   fallback = AICompletionConfigDefault(
       enabled=True,
       model=ModelConfig(name="gpt-4o", parameters={"temperature": 0.7, "max_tokens": 2000}),
       provider=ProviderConfig(name="openai"),
       messages=[LDMessage(role="system", content="You are a helpful assistant...")],
   )
   

7. 替换硬编码的调用位置。 将硬编码的模型／提示词／参数替换为 completion_config / completionConfig（或 agent_config / agentConfig）调用，然后将返回的字段读入现有的提供商调用中。保持提供商调用不变。

   Python — 迁移前：

   response = openai_client.chat.completions.create(
       model="gpt-4o",
       temperature=0.7,
       max_tokens=2000,
       messages=[
           {"role": "system", "content": "You are a helpful assistant..."},
           {"role": "user", "content": user_input},
       ],
   )
   

   Python — 迁移后：

   context = Context.builder(user_id).set("email", user.email).build()
   config = ai_client.completion_config("chat-assistant", context, fallback)
   
   if not config.enabled:
       return disabled_response()
   
   params = config.model.parameters or {}
   response = openai_client.chat.completions.create(
       model=config.model.name,
       temperature=params.get("temperature"),
       max_tokens=params.get("max_tokens"),
       messages=[m.to_dict() for m in (config.messages or [])] + [
           {"role": "user", "content": user_input},
       ],
   )
   

   Python — 迁移后（Agent 模式） — 适用于 LangGraph、CrewAI，或任何接收目标／指令字符串的框架：

   context = Context.builder(user_id).kind("user").build()
   config = ai_client.agent_config("support-agent", context, FALLBACK)
   
   if not config.enabled:
       return disabled_response()
   
   # config is a single AIAgentConfig object — NOT a (config, tracker) tuple.
   # Obtain the tracker once per execution via the factory: tracker = config.create_tracker()
   model_name = f"{config.provider.name}/{config.model.name}"
   instructions = config.instructions
   params = config.model.parameters or {}
   
   # Pass model_name + instructions into your framework's agent constructor.
   # Example: LangGraph prebuilt agent (Python — `from langchain.agents import create_agent`;
   # this replaces `langgraph.prebuilt.create_react_agent`, deprecated in LangGraph 1.0
   # and removed in 2.0. Same return shape; `prompt=` was renamed to `system_prompt=`.)
   # agent = create_agent(
   #     create_langchain_model(config),  # forwards every variation parameter
   #     TOOLS,                            # Stage 3 will replace this with a config.tools loader
   #     system_prompt=instructions,
   # )
   

   有关完整的 Python OpenAI、Node Anthropic 和 LangGraph Agent 模式成对代码片段，请参阅 before-after-examples.md。

8. 检查 config.enabled。 如果返回 False，请处理禁用路径，确保不会崩溃，也不会调用提供商。此项检查为必需项，不可省略。

9. 验证。 使用有效的 LD_SDK_KEY 运行应用；确认调用成功，且响应与迁移前的输出一致。然后临时设置 LD_SDK_KEY=sdk-invalid（或取消设置），并确认回退路径运行正常。进入阶段 3 前，两条路径都必须正常工作。

委派：configs-create（子步骤 4）。

第 3 步：将工具移入配置（阶段 3）

如果经过审查的应用没有函数调用/工具，则跳过此步骤。否则：

1. 列出当前已注册的工具。 常见形式包括：

   • openai.chat.completions.create(tools=[...]) — OpenAI 直连
   • anthropic.messages.create(tools=[...]) — Anthropic 直连
   • create_agent(llm, tools=[...], system_prompt=...) — LangGraph 预构建（Python，langchain.agents；取代已弃用的 langgraph.prebuilt.create_react_agent）
   • createReactAgent({ llm, tools: [...] }) — LangGraph.js 预构建（Node，@langchain/langgraph/prebuilt）
   • Agent(tools=[...]) — CrewAI
   • Agent(tools=[...]) — Strands（Python 中通过构造函数传入使用 @tool 装饰的可调用对象；TS SDK 使用 Zod 架构工具）
   • 自定义 StateGraph — 模块级 TOOLS = [...] 列表同时在 model.bind_tools(TOOLS) 和 ToolNode(TOOLS) 中引用。这是 langchain-ai/react-agent 模板的形式；该列表通常位于 tools.py 模块中。一起搜索 bind_tools( 和 ToolNode( — 它们会指向同一个列表。

   记录每个工具的名称、描述和 JSON 架构。

   对于使用 @tool 定义的 LangChain/LangGraph 工具，通过 tool.args_schema.model_json_schema()（或等效的 Pydantic model_json_schema() 调用）提取架构。对于用作工具的普通异步可调用对象（常见于自定义 StateGraph 形式），LangChain 会在绑定时根据函数签名推断架构 — 使用 StructuredTool.from_function(fn).args_schema.model_json_schema() 提取。不要手动编写架构。

2. 交接给 tools。 打印提取出的工具名称、描述和架构，然后告诉用户："使用这些工具和变体键运行 /tools，然后回到这里。" 同级技能会创建工具定义（create-ai-tool），并将其附加到变体（update-ai-config-variation）。等待用户完成后再继续子步骤 3。不要自动调用。

3. 在调用位置将硬编码的工具数组替换为从 config.tools 读取（或使用对应语言的 SDK 等效方式）。根据工具名称动态加载实际实现函数 — 参见 agent-mode-frameworks.md，了解 devrel Agents 教程中的动态工具工厂模式。

   对于自定义 StateGraph 形式，必须更新两个调用位置：.bind_tools(TOOLS) 和 ToolNode(TOOLS) 都必须读取同一个从 config.tools 派生的列表。若遗漏其中一个，LLM 看到的将是新工具，但执行器仍运行旧工具，反之亦然。

4. 验证。 运行应用，确认工具调用流程仍能正确执行。get-ai-config（通过委托）会确认工具已在服务端附加。

委托：tools（子步骤 2）。

第 4 步：为跟踪器添加埋点（阶段 4）

委托：built-in-metrics 会在提供方调用周围接入每次请求的 tracker.track_* 调用（时长、令牌、成功/错误、反馈）。如果应用需要内置 Agent 指标之外的业务指标，可同时使用 custom-metrics。注意：不要将其与 launchdarkly-metric-instrument 混淆；后者用于 ldClient.track() 功能指标，是不同的 API。请参见 sdk-ai-tracker-patterns.md，了解委托技能所依据的、涵盖每种方法的 Python + Node 完整矩阵。

交接：打印配置键、变体键、提供方，以及调用是否为流式，然后告诉用户："使用这些输入运行 /built-in-metrics，然后回到这里。" 不要自动调用。用户完成后返回此处继续子步骤 5（验证）。

1. 创建跟踪器。 通过 Stage 2 返回的配置上的工厂获取一个单次执行的跟踪器：tracker = config.create_tracker() (Python) 或 const tracker = aiConfig.createTracker(); (Node)。每轮用户交互只调用一次工厂，并在该轮的每次跟踪调用中复用返回的 tracker——每次调用都会生成一个新的 runId，用于标记该轮发出的每个事件，以便通过导出的事件或下游查询进行关联。（监控选项卡目前会聚合数据；按运行分组属于下游工作——但 runId 也是 SDK 至多一次保护机制的键，因此无论事件最终流向何处，在一轮交互中途生成新的 runId 都会破坏保护机制的语义。）

   根据调用形式，工厂的调用位置有所不同：

   • 完成模式／一次性提供商调用： 在处理请求的同一函数中，紧接着 completion_config(...) 返回后生成跟踪器。
   • 带 ReAct 循环的 Agent 模式（LangGraph、LangChain、自定义）： 在专用的 setup_run 入口节点中生成跟踪器。该节点只在循环开始前执行一次，然后将其存入图状态，并在 call_model／工具处理程序／终止 finalize 节点中从状态读取。在循环体内调用 track_duration／track_tokens／track_success 会触发至多一次保护机制。完整的 setup_run + call_model + finalize 模式，请参阅 agent-mode-frameworks.md § 自定义 StateGraph（按运行范围划分的架构）。
   • 托管运行器（Tier 1）： 完全跳过此步骤。ManagedModel 会在每次 run()／invoke() 调用时在内部生成跟踪器。如果应用使用的是这种方式，请转到第 4 个子步骤。

2. 从四层级梯度中选择一个层级。 完整表格请参阅 sdk-ai-tracker-patterns.md § 层级决策表（聊天循环 → Tier 1；提供商包调用 → Tier 2；自定义提取器 → Tier 3；流式／手动 → Tier 4）。

3. 接入所选层级。 委托技能提供了每个层级的完整 Python + Node 示例以及各提供商对应的文件。以下是精简的 Tier 2/3 示例，供参考——通过提供商包使用 OpenAI：

   Python：

   from ldai_openai import get_ai_metrics_from_response
   import openai
   
   client = openai.OpenAI()
   
   tracker = config.create_tracker()
   
   def call_openai():
       return client.chat.completions.create(
           model=config.model.name,
           messages=[{"role": "system", "content": config.messages[0].content},
                     {"role": "user", "content": user_prompt}],
       )
   
   # Exceptions are tracked automatically — track_metrics_of catches
   # exceptions, records tracker.track_error(), and re-raises. Wrap your
   # own try/except only for local handling (logging, fallback).
   response = tracker.track_metrics_of(get_ai_metrics_from_response, call_openai)
   

   Node：

   import { getAIMetricsFromResponse } from '@launchdarkly/server-sdk-ai-openai';
   
   const tracker = aiConfig.createTracker();
   // Exceptions are tracked automatically — trackMetricsOf catches
   // exceptions, records tracker.trackError(), and re-throws.
   const response = await tracker.trackMetricsOf(
     getAIMetricsFromResponse,
     () => openaiClient.chat.completions.create({
       model: aiConfig.model!.name,
       messages: [...aiConfig.messages, { role: 'user', content: userPrompt }],
     }),
   );
   

   对于 Anthropic 直连、Bedrock（无提供商包）、Gemini 和自定义 HTTP，编写一个返回 LDAIMetrics 的小型提取器——请参阅委托技能中的 anthropic-tracking.md、bedrock-tracking.md 和 gemini-tracking.md。LangChain 单节点和 LangGraph 使用 launchdarkly-server-sdk-ai-langchain／@launchdarkly/server-sdk-ai-langchain 提供商包。使用 create_langchain_model(config) (Python)／createLangChainModel(config) (Node) 构建模型——两者都会传递所有变体参数——并使用 get_ai_metrics_from_response／getAIMetricsFromResponse 进行跟踪。请参阅 langchain-tracking.md。

4. 如果应用有点赞／点踩 UI，则接入反馈跟踪。 两个 SDK 都提供了带 {kind} 参数的 trackFeedback。

   Python：

   from ldai.tracker import FeedbackKind
   tracker.track_feedback({"kind": FeedbackKind.Positive})
   

   Node：

   import { LDFeedbackKind } from '@launchdarkly/server-sdk-ai';
   tracker.trackFeedback({ kind: LDFeedbackKind.Positive });
   

   跨进程延迟反馈。 如果点赞 UI 的触发进程与生成响应的进程不同，不要在消费方再次调用 create_tracker()——这会生成新的 runId。将跟踪器的恢复令牌（Python 中的 tracker.resumption_token，Node 中的 tracker.resumptionToken）与消息一同持久化，然后在反馈处理程序中使用 LDAIConfigTracker.from_resumption_token(...) (Python) 或 aiClient.createTracker(token, context) (Node) 重新载入跟踪器。

5. 验证。 在 staging 中调用封装后的端点，然后打开 LaunchDarkly 中的配置 → Monitoring 选项卡。1–2 分钟内应显示时长、令牌和生成次数。如果没有显示，请按照 sdk-ai-tracker-patterns.md 中“故障排除”部分的检查清单进行排查。

步骤 5：添加评估（阶段 5）

1. 在三种评估路径中做出选择。 这是最常被误解的阶段——这里有三种路径，不是两种；而迁移场景下，最合适的默认选项往往是人们会跳过的那一种。

   路径	适用场景	是否支持 Agent 模式？
   离线评估（迁移的推荐默认选项）	发布前回归测试：在 LD Playground 中对新变体运行固定数据集，并与基线对比评分。最适合迁移，因为你需要在发布前证明新配置的表现至少不逊于硬编码版本。	是——所有模式
   附加到 UI 的自动评审器	在 LD UI 中将一个或多个评审器附加到变体；评审器会自动对抽样的实时请求运行。无需更改代码。	仅完成模式（目前 UI 控件仅支持完成模式）
   程序化直接评审器	在请求处理程序中调用 ai_client.create_judge(...)，并对每次调用执行 judge.evaluate(input, output)。会增加每个请求的成本和代码复杂度。最适合在抽样自动评审器不够用时，对工作流进行持续的实时评分。	是——所有模式（SDK 对两者的处理方式相同）

   大多数迁移用户应从离线评估开始，然后仅在需要于发布稳定后持续进行实时评分时，才添加程序化直接评审器。

2. 对于 Agent 模式迁移，默认使用离线评估。 目前，附加到 UI 的自动评审器仅支持完成模式。Agent 模式的文档化路径有两种：(a) 通过 LD Playground + Datasets 进行离线回归测试（适用于所有模式），或 (b) 在调用位置接入程序化直接评审器。根据审计清单生成一个入门数据集 CSV（每行一个有代表性的输入），并指引用户参阅离线评估指南，了解 Playground 操作流程。仅当用户明确要求持续进行实时评分时，才将程序化直接评审器接入生产代码。

   迁移时推荐的离线评估方案：

   • 先用数据集运行 default 变体（或其他与迁移前硬编码行为一致的变体）——这就是基线。
   • 将其克隆为第二个变体，并指定一个不同的模型系列（例如，如果基线是 anthropic/claude-sonnet-4-5，则克隆为 openai/gpt-4o 或 openai/gpt-4o-mini）。跨模型系列的对比比同系列模型之间的对比更有参考价值。
   • 附加内置的 Accuracy 评审器，将通过阈值设为 0.85，然后用同一数据集运行这两个变体。
   • 仅当胜出者的 Accuracy 高于基线，且 Relevance 或 Toxicity 没有退步时，才通过 /configs-targeting 将其提升为回退变体。

   将此方案写入项目的 datasets/README.md（或同等文件），以便迁移发布后能够复现这一对比模式。

3. 委派给 online-evals——仅用于附加到 UI 的评审器（完成模式），或创建程序化路径将引用的自定义评审器配置。告知用户：“使用这些输入运行 /online-evals，然后返回这里。” 不要自动调用。传递以下内容：

   • 父配置键和变体键
   • 要创建或附加的内置评审器（Accuracy、Relevance、Toxicity）列表，或自定义评审器键列表
   • 目标环境

   委派任务会创建自定义评审器配置，通过变体 PATCH 端点附加它们，并在每个评审器配置上设置回退。离线评估不会通过此委派任务进行——它是 Playground 工作流，而不是 API 写入操作。

4. 对于程序化直接评审：连接 create_judge、evaluate 和 track_judge_result。 这是 Stage 5 中唯一需要编写代码的路径。Python 形式：

   from ldai.client import AIJudgeConfigDefault
   
   judge = ai_client.create_judge(
       judge_key,                               # judge config key in LD
       ld_context,
       AIJudgeConfigDefault(enabled=False),     # fallback: skip eval on SDK miss
   )
   
   if judge and judge.enabled:
       result = await judge.evaluate(
           input_text,
           output_text,
           sampling_rate=0.25,                  # optional; default 1.0 (always eval)
       )
       if result.sampled:
           tracker.track_judge_result(result)
   

   四条规则：

   • create_judge 返回 Optional[Judge]。 始终使用 if judge and judge.enabled: 进行保护——如果该上下文的评审配置已禁用，或缺少提供方，它就会返回 None。对 None 返回值直接调用 .evaluate() 会引发 AttributeError。
   • 传入 AIJudgeConfigDefault，而不是 AICompletionConfigDefault。create_judge 的 default 参数类型为 Optional[AIJudgeConfigDefault]；传入 completion 类型无法通过类型检查，而且一些较旧示例中存在文档级错误。
   • sampling_rate 是 evaluate() 的参数，而不是 create_judge 的参数。它默认为 1.0（评估每次调用）。对于线上路径，传入较低的值（0.1–0.25）来控制成本。
   • evaluate() 返回 JudgeResult（绝不会是 None）。检查 result.sampled，以确认是否实际运行了评估，并调用 track_judge_result(result)。Node 使用 trackJudgeResult(result) 和带有相同 sampled 字段的 LDJudgeResult。

   询问用户要使用哪个评审配置键。 LaunchDarkly 内置了三个评审——Accuracy、Relevance 和 Toxicity——但这些内置评审的实际配置键不是 SDK 中的标准常量，也没有相关文档。让用户在 LD UI 中打开 AgentControl > Library，复制他们想要引用的评审键，或者先通过 configs-create 创建自定义评审配置。

5. 验证。

   • 附加到 UI 的自动评审： 在 staging 中触发请求，打开 Monitoring 选项卡 →“Evaluator metrics”下拉菜单。按配置的采样率，分数会在 1–2 分钟内显示。
   • 程序化直接评审： 调用封装后的端点，并确认 track_judge_result 出现在父配置的 Monitoring 选项卡中。
   • 离线评估： 通过 LD Playground 运行数据集，并并排比较基线与新变体的分数。无需进行运行时连接。

委派：online-evals（第 3 个子步骤，可选——仅适用于附加到 UI 的评审或创建自定义评审；离线评估不需要委派）。

边缘情况

情况	操作
应用已为功能标志初始化 LDClient	复用它——将现有客户端传给 LDAIClient() / initAi()，不要创建第二个客户端
应用使用 LangChain ChatOpenAI(model=...)	将手动构建模型的代码替换为 create_langchain_model(config)（Python）或 createLangChainModel(config)（Node）。不要读取 config.model.name 并手动将其传给 ChatOpenAI(model=...)——这种做法会丢弃所有变化参数，只保留你明确指定的参数
提供方调用外层包有重试逻辑	跟踪器在用户轮次开始时创建一次；重试循环位于该作用域内。每次重试尝试共用同一个 runId。跟踪器调用（track_duration / track_tokens / track_success / track_error）放在重试代码块的外部——在轮次结束时调用一次，成功时或最终失败时调用
应用没有工具——跳过 Stage 3	从 Stage 2 验证直接进入 Stage 4（跟踪）
模式不匹配：用户说是 Agent，但审查显示是单次聊天	选择补全模式，除非应用使用 LangGraph 预构建 Agent（Python 中的 langchain.agents.create_agent 或 Node 中的 createReactAgent）、CrewAI Agent、Strands Agent，或类似的目标驱动框架
应用使用 Strands Agents（Python）	使用 Agent 模式。构建一个以 agent_config.provider.name 为键的 create_strands_model 分发器，返回 AnthropicModel(model_id=..., max_tokens=...) 或 OpenAIModel(model_id=..., params=...)。将 parameters.tools 从传给模型类的 params 中移除——Strands 通过 Agent(tools=[...]) 接收工具。跟踪属于 Tier 3：使用 tracker.track_duration_of(...) 包装 invoke_async，并从 result.metrics.accumulated_usage 记录令牌数。参见 agent-mode-frameworks.md § Strands Agent 和 strands-tracking.md
TypeScript 应用使用 Strands	TS SDK 仅提供 BedrockModel 和 OpenAIModel——无法支持由 Anthropic 驱动的变化。如需多提供方变化，请使用 Python SDK
TypeScript 应用使用 Anthropic SDK	不存在 trackAnthropicMetrics 助手。使用 Tier 3：通过一个小型自定义提取器调用 trackMetricsOf，读取 response.usage.input_tokens / response.usage.output_tokens 并返回 LDAIMetrics。确切的提取器请参见 built-in-metrics 技能中的 anthropic-tracking.md
由于缺少 LD_SDK_KEY，回退方案会静默崩溃	记录启动警告；继续使用回退方案。切勿在导入时引发异常
多 Agent 图（主管 + 工作节点）	单个 Agent 迁移完成后即停止。两种 SDK 都支持 Agent 图定义——Python 使用 launchdarkly-server-sdk-ai.agent_graph，Node 使用 @launchdarkly/server-sdk-ai 中的图 API。阅读 agent-graph-reference.md，了解图级迁移路径——这有意不属于本技能的主要范围
单 Agent（ReAct、工具循环）+ Agent 模式	Stage 5 默认使用 LD Playground + Datasets 进行离线评估。目前，附加到 UI 的评审器仅支持补全模式，而程序化直接评审会产生单次调用成本，通常不值得在迁移上线并稳定之前使用。请参阅 Offline Evals guide
工具使用 Pydantic args_schema（LangChain @tool）	使用 tool.args_schema.model_json_schema() 提取架构；不要为委托工具手写 JSON 架构
自定义 StateGraph 使用模块级 TOOLS 列表，通过 .bind_tools(TOOLS) 绑定并通过 ToolNode(TOOLS) 运行（例如 langchain-ai/react-agent 模板）	找到 TOOLS 列表（通常位于单独的 tools.py 模块中）。以相同方式提取架构。将两个调用位置——.bind_tools(...) 和 ToolNode(...)——都替换为从同一个 config.tools 派生的列表
应用已将配置外置到带环境变量回退的 Context 数据类中（例如 react-agent 模板的 context.py）	将 runtime.context.model / runtime.context.system_prompt 的使用处替换为 ai_client.agent_config(...)，并读取返回的 AIAgentConfig。清空该数据类，不要将其保留为回退结构——规范的回退值应为 Python 中的 FALLBACK = AIAgentConfigDefault(...)（位于 agent_config 调用附近的顶层常量），而不是并行的 Python 数据类。回退值有两个真相来源会导致不一致。空的 Context 仅是满足 LangGraph context_schema 要求的占位符；thread_id 和其他每个请求所需的参数应通过 config: RunnableConfig 传入（参见 agent-mode-frameworks.md § Custom StateGraph）

不要做什么

以下事项按其导致首次运行失败的可能性排序。前三条规则——关于跟踪器和配置的生命周期——涵盖了大多数“迁移看似已完成，但 Monitoring 选项卡上的数据被拆分／不正确”的问题报告。

跟踪器和配置的生命周期（最常见的失败模式）

• 不要在每个用户轮次中调用 create_tracker() / createTracker() 超过一次。 一个轮次 = 完整的请求／响应周期，包括每次 ReAct 迭代、工具调用和重试。有关各类应用形态（completion／Agent 循环／托管运行器）的标准调用位置，请参阅 Stage 4 Step 1。
• 不要在循环体内调用 track_duration / track_tokens / track_success / track_error / track_time_to_first_token。 每个跟踪器最多调用一次；第二次及之后的调用会被丢弃。应在循环内累积数据，并在终止／结束节点中一次性发送。单事件方法（track_tool_call、track_tool_calls、track_feedback、track_judge_result）可以安全地重复调用。完整矩阵见：sdk-ai-tracker-patterns.md § At-most-once guards。
• 不要在每个用户轮次中调用 agent_config() / completion_config() 超过一次。 每次调用都会执行一次标志评估，并发送一个 $ld:ai:agent:config 事件。在循环步骤或工具体内重新获取配置，会导致 Monitoring 选项卡上的 agent-config 计数虚高，还会使轮次中途发生的定向变化在同一轮次的 LLM 调用之间切换变体。应在开始时获取一次配置，将其存入状态，并让之后的所有使用者从状态中读取。需要按变体调整参数的工具应使用工具工厂模式（make_search(ai_config)，在设置时将参数闭包捕获）——参阅 agent-mode-frameworks.md § Getting knobs into tools。
• 不要在不同请求之间缓存配置对象——每个轮次获取一次配置，这一点没错；但仍然必须每个轮次都获取一次。在模块范围内缓存会完全破坏定向变化机制。
• 接入 LaunchDarkly 后，不要删除回退逻辑。它是 enabled=False 和 SDK 无法访问时的必要保障。
• 不要对 completion_config / agent_config / completionConfig / agentConfig 的返回值进行元组解包。它们返回的是单个配置对象（例如 AIAgentConfig、AICompletionConfig），而不是 (config, tracker)。应调用 config.create_tracker() / aiConfig.createTracker() 来获取跟踪器。LLM 经常会臆造元组返回形式和 config.tracker 属性——实际 API 是一个工厂。

LangChain / LangGraph 模式（第二常见的故障模式）

• 如果仓库中已有 load_chat_model(f"{provider}/{name}") 辅助函数，请将其删除，而不只是避免使用它。 这种确切的写法随 langchain-ai/react-agent 一同发布，并被复制到数十个衍生仓库中；请查找 utils.load_chat_model、utils.build_model，或任何会拆分 "provider/model" 字符串的单参数 init_chat_model 包装器。复用它会导致首次运行失败：所有变体参数（temperature、max_tokens、top_p、停止序列）都会被悄然丢弃，因为 init_chat_model 只接收名称和提供方。create_langchain_model(ai_config) 可以一对一替换它，并传递整个 model.parameters 字典。替换所有调用位置，然后从文件中删除该包装器，避免后续读者再次使用它。
• 同样的规则也适用于手写的 resolve_tools / TOOL_REGISTRY / ALL_TOOLS 辅助工具。 如果模板已有 resolve_tools(tool_keys) 或模块级 ALL_TOOLS 列表，请从 ldai_langchain.langchain_helper 导入 build_structured_tools，并删除手写版本。build_structured_tools(ai_config, TOOL_REGISTRY_DICT) 会读取 ai_config.model.parameters.tools，并将匹配的可调用对象包装为 LangChain StructuredTool，同时将 LD 工具键设为 StructuredTool.name，这样 ToolNode 无需第二次映射即可查找工具。不要在仓库中同时保留两者。
• 不要将应用级配置项直接放入 model.parameters。create_langchain_model 会通过 init_chat_model 将 parameters 中的每个键都传递给提供方 SDK，因此 max_search_results / retry_budget / feature_toggle 条目会导致提供方因意外关键字参数而报错。正确的位置是 model.custom，提供方辅助函数会忽略它，应用则通过 ai_config.model.get_custom("key") 读取它。目前 MCP update-ai-config-variation 工具不会公开顶层的 custom，因此可选择以下两种方式之一：（a）通过 REST API 对变体执行 PATCH，直接设置 model.custom；或（b）通过 MCP 将其设为 parameters.custom（嵌套字典），并使用同时读取这两个位置的防御式访问器。完整的操作说明和代码示例见 langchain-tracking.md § MCP 注意事项。
• 不要在回退方案中重新编码工具架构。当 LaunchDarkly 无法访问时，回退方案应在不使用工具的情况下运行（或使用应用保持运行所需的最少提供方参数）。构建一个复制配置中工具架构的 _FALLBACK_TOOLS 数组，会重新引入此次迁移本应从代码中移除的硬编码配置。
• 不要从 ldai.langchain 导入 LaunchDarklyCallbackHandler——该类和点分模块路径都不存在。Python LangChain 辅助包是 ldai_langchain（顶层模块，带下划线）。请使用 create_langchain_model(config) + track_metrics_of_async(get_ai_metrics_from_response, lambda: llm.ainvoke(messages)) 作为规范模式。

阶段 / 交接规范

• 即使用户说“直接封装就行”，也不要跳过步骤 1。没有审计，回退行为就会偏离硬编码逻辑。
• 提取提示词和模型之前，不要委派给 configs-create——委派时需要将它们作为输入。
• 在初始 setup-ai-config 期间，不要尝试附加工具。工具附加是由 tools 负责的独立步骤。
• 不要声称你“已委派给 configs-create”或任何其他同级技能。此技能不会自动调用其他技能。每次交接时，打印输入，并告诉用户运行同级斜杠命令，然后等待。其他说法都会误导用户，让他们以为刚才发生了实际上并未发生的操作。
• 不要跳过第 2 阶段和第 4 阶段之间的 /configs-targeting 步骤。新创建的变体在定向投放之前会返回 enabled=False——第 2 阶段的验证会在每次请求时悄悄走回退路径。
• 不要一次完成多 Agent 图迁移。先迁移单个 Agent；下一步请阅读 agent-graph-reference.md。

第 5 阶段评估

• 跟踪器就位之前，不要接入评估。评估器会对流量进行评分；没有第 4 阶段的流量，就无从评分。
• 不要把第 5 阶段描述成“UI 或编程方式二选一”。共有 三种路径：离线评估（迁移时推荐的默认方式）、附加到 UI 的自动评估器（仅限 completion 模式）以及编程式直接评估器。大多数人会跳过离线评估，但它通常是正确的起点。
• 不要将 sampling_rate 传给 create_judge——它是 Judge.evaluate() 的参数，不是 create_judge() 的参数。
• 不要对评估器配置键（"accuracy-judge"、"relevance-judge" 等）进行硬编码。内置键不是规范的 SDK 常量；请让用户在 LD UI 的 AgentControl > Library 中查找。
• 调用 create_judge 后，别忘了添加 if judge and judge.enabled: 检查。它会返回 Optional[Judge]，并且当评估器配置对当前上下文禁用时会返回 None。

API 注意事项

• 第 4 阶段（跟踪）不要使用 launchdarkly-metric-instrument。该技能用于 ldClient.track() 功能指标，而不是 Agent 的 tracker.track_* 调用——它们是不同的 API。
• 在 Python 中不要使用 track_request()——它在 launchdarkly-server-sdk-ai 中不存在。请使用带有提供方包或自定义提取器的 track_metrics_of；如果使用的是流式处理路径，也可以改用显式的 track_duration + track_tokens + track_success / track_error。
• 在 Python 中，不要将 graph_key=... 传给 tracker.track_*() 方法——它不是受支持的参数。在图遍历期间获取的跟踪器会自动配置正确的图键。

相关技能

• configs-create — 由第 2 阶段调用以创建配置
• tools — 由第 3 阶段调用以创建并附加工具定义
• online-evals — 由第 5 阶段调用以附加评估器
• configs-variations — 迁移完成后添加变体以进行 A/B 测试
• configs-targeting — 迁移完成后向用户推出新变体
• configs-update — 随着应用演进修改配置属性
• launchdarkly-metric-instrument — 用于 ldClient.track() 功能指标（不适用于 Agent 跟踪器调用）

参考资料

• phase-1-analysis-checklist.md — 第 1 步审查清单、grep 模式、SDK 路由表和模式决策树
• before-after-examples.md — Python OpenAI、Node Anthropic、Python LangGraph 中硬编码内容与封装后代码的配对示例
• sdk-ai-tracker-patterns.md — Python 和 Node 中每个 tracker.track_* 方法的并列对照、自动辅助函数矩阵和常见注意事项
• agent-mode-frameworks.md — 如何将 agent_config 接入 LangGraph、CrewAI 和自定义 react 循环；动态加载工具的模式
• fallback-defaults-pattern.md — 三种回退模式（内联、基于文件、引导生成）及各自的适用场景
• agent-graph-reference.md — 多 Agent 迁移的范围外参考文档