configs-create

创建配置

你正在使用一项技能，它将指导你在 LaunchDarkly 中创建配置。你的任务是了解使用场景、选择合适的模式、创建配置及其变体，并验证一切是否设置正确。

⚠️ 此技能会创建配置，但不会让它可供服务。 新创建的配置会将其回退指向自动生成的禁用变体，而不是你刚创建的变体。在启用定向并将回退指向新变体之前，SDK 每次评估都会返回 ai_config.enabled=False。这不是错误，而是默认状态。在通过 SDK 验证之前，你必须运行 /configs-targeting（或第 5 步中所示的等效 REST / CLI 调用），否则你会误以为 LD 服务路径出了问题。使用此技能时，用户最常见的失败原因就是跳过定向步骤，随后花时间调试应用代码中的 enabled=False。

前提条件

此技能要求在你的环境中配置远程托管的 LaunchDarkly MCP 服务。

主要 MCP 工具：

• setup-ai-config —— 一步创建配置及其第一个变体（推荐）

备用 MCP 工具（提供更多控制）：

• create-ai-config —— 仅创建配置框架（键、名称、模式）
• create-ai-config-variation —— 添加包含模型、提示词和参数的变体
• get-ai-config —— 验证配置是否创建正确

可选 MCP 工具（完善工作流）：

• list-ai-configs —— 浏览现有配置，了解命名惯例
• create-project —— 如果项目尚不存在，则创建项目

重要提示：优先采取行动

当用户提供了足够的上下文（使用场景、模型、模式）时，请完成整个工作流，不要停下来询问可以推断出的详情。对未指定的字段使用合理的默认值：变体键使用 default，以使用场景为基础编写指令／消息，配置键采用 kebab-case。一次性完成所有步骤（创建 + 验证）。

工作流

第 1 步：了解使用场景

创建之前，先确定你要构建什么：

• 使用什么框架？ LangGraph、LangChain、CrewAI、Strands、OpenAI SDK、Anthropic SDK、自定义框架
• Agent 需要什么？ 仅生成文本，还是需要工具／函数调用？
• Agent 还是补全？ 请参阅下面的决策矩阵

第 2 步：选择 Agent 或补全模式

此选择关系到输入架构和框架兼容性，而非执行行为。Agent 模式返回一个 instructions 字符串；补全模式返回一个 messages 数组。两种模式都提供提供方抽象、A/B 测试和指标跟踪。

你的需求	模式	原因
LangGraph、CrewAI、Strands、AutoGen 框架	Agent	框架需要目标／指令输入
在多次交互中保持指令不变	Agent	单个 instructions 字符串；SDK 方法：agent_config()（Python）/ agentConfig()（Node）
直接调用 OpenAI/Anthropic API	补全	消息数组可直接映射到提供方 API
完全控制消息结构	补全	基于 system/user/assistant 角色的消息
单次文本生成	补全	标准聊天格式
需要在线评估（LLM-as-judge）	补全	在线评估仅在补全模式下可用

两种模式都支持工具。 并非所有模型都支持 Agent 模式——如果使用 Agent 模式，请检查模型兼容性。如果不确定，请从补全模式开始（它是 API 的默认模式，也更灵活）。

第 3 步：创建配置（推荐：一步完成）

使用 setup-ai-config 在一次调用中创建配置及其第一个变体。这是推荐的方法：它会自动处理创建、变体设置和验证。

配置字段：

• key -- 唯一标识符（小写，使用连字符）
• name -- 易于理解的名称
• mode -- "agent" 或 "completion"
• 可选：description、tags

变体字段：

• variationKey、variationName -- 第一个变体的标识符
• modelConfigKey -- 必须采用 Provider.model-id 格式（例如，OpenAI.gpt-4o、Anthropic.claude-sonnet-4-5）
• modelName -- 模型标识符（例如，gpt-4o）。请务必在初始调用中传入此字段——如果省略，变体会显示“NO MODEL”，并需要再发送一次 PATCH 才能设置该字段。此端点的字段是 modelName，不是 name 或 model.name。

对于 Agent 模式，请提供：

• instructions -- 包含 Agent 系统指令的字符串

Agent 模式调用示例：

{
  "projectKey": "my-project", "key": "support-agent", "name": "Support Agent",
  "mode": "agent", "variationKey": "default", "variationName": "Default",
  "modelConfigKey": "OpenAI.gpt-4o", "modelName": "gpt-4o",
  "instructions": "You are a customer support agent. Help users resolve their issues."
}

对于 completion 模式，请提供：

• messages -- {role, content} 对象数组（system、user、assistant）

Completion 模式调用示例：

{
  "projectKey": "my-project", "key": "product-descriptions", "name": "Product Descriptions",
  "mode": "completion", "variationKey": "default", "variationName": "Default",
  "modelConfigKey": "Anthropic.claude-sonnet-4-5", "modelName": "claude-sonnet-4-5",
  "messages": [
    {"role": "system", "content": "You are a product copywriter. Write compelling descriptions."},
    {"role": "user", "content": "Write a description for: {{product_name}}"}
  ]
}

可选：

• parameters -- 模型参数，例如 {temperature: 0.7, max_tokens: 2000}（与 UI 中的 snake_case 键保持一致）

该工具会返回完整且经过验证的配置详情，其中包含已附加的变体。

第 3 步（替代方案）：两步创建

如果用户需要更多控制或希望逐步操作，请使用单独的工具：

1. create-ai-config -- 创建配置框架
2. create-ai-config-variation -- 添加包含模型、提示词和参数的变体
3. get-ai-config -- 验证结果

请连续执行全部三个步骤，不要中途停下来询问详情。 根据用户请求的上下文推断变体键（default）、名称（Default）、指令/消息和模型。如果用户要求使用 GPT-4o Agent 模式，你已有足够信息完成整个流程。只有在模式或模型确实不明确时，才询问澄清问题。

第 4 步：验证

如果你使用了 setup-ai-config，验证会自动完成：响应中会包含含有变体的完整配置。请检查：

1. 配置存在，且模式正确
2. 变体已分配模型（而不是“NO MODEL”）
3. 指令或消息已提供
4. 参数已设置

请使用 get-ai-config 进行验证，不要改用原始 curl + jq。 MCP 工具会返回可直接检查的类型化对象。手动编写的 jq 筛选器经常会因 REST 响应而失效：根据 expand 的不同，配置详情端点会将变体列表放在不同的键下；当响应结构是裸数组时，.variations.items[] 之类的筛选器会报错 Cannot index array with string "items"。如果必须调用 REST API，请先使用 jq -e . 检查实际结构，再深入筛选。

报告结果：

• 配置已创建，结构正确
• 变体已分配模型
• 标明缺少的模型或参数
• 提供配置 URL：https://app.launchdarkly.com/projects/{projectKey}/ai-configs/{configKey}

第 5 步：使变体可供服务

setup-ai-config 和 create-ai-config-variation 会创建变体，但不会将其提升为回退变体。在更新定向规则之前，新配置对所有使用方都会返回 enabled=False。这是“我创建了配置，但我的 SDK 仍然获取回退配置”这一问题最常见的原因。完成此步骤后，工作流才算结束。

要告知用户的内容

第 4 步后，将此清单原样打印给用户，然后等待确认。在用户确认已切换回退设置前，不要声称技能已成功。

✅ 配置和变体已创建。

🔴 在你切换定向设置之前，SDK 会返回 enabled=False。 当前回退设置指向的是自动生成的禁用变体，而不是你刚刚创建的 {variationKey}。

下一步 — 使用以下输入运行 /configs-targeting：

• 项目键：{projectKey}
• 配置键：{configKey}
• 环境键：.env 中 SDK 键所属的环境（通常是 test 或 production）
• 回退变体：{variationKey}（此技能刚刚创建的变体）

切换定向设置后，请通过以下方式验证：

1. 在 LD UI 中打开配置，切换到正确的环境，并确认显示“默认规则提供：{variationName}”，且定向设置为 开启。
2. 运行快速测试：ai_config = ai_client.{completion|agent}_config(...)，并断言 ai_config.enabled is True。

如果用户想在不调用同级技能的情况下切换定向设置，可直接使用此快捷方式

configs-targeting 是标准做法 — 它会处理百分比发布、定向规则和变体 ID 查询。但对于最简单的情况（“在一个环境中将新变体提升为回退变体”），只要知道新变体的 _id，你就可以自行运行底层语义 PATCH。

获取变体 ID（使用 get-ai-config MCP，或）：

curl -s "https://app.launchdarkly.com/api/v2/projects/$PROJECT/ai-configs/$CONFIG_KEY/targeting?env=$ENV" \
  -H "Authorization: {api_token}" -H "LD-API-Version: beta" \
  | jq '.variations[] | {key, _id}'

将回退设置切换为指向该变体：

curl -X PATCH "https://app.launchdarkly.com/api/v2/projects/$PROJECT/ai-configs/$CONFIG_KEY/targeting?env=$ENV" \
  -H "Authorization: {api_token}" \
  -H "Content-Type: application/json; domain-model=launchdarkly.semanticpatch" \
  -H "LD-API-Version: beta" \
  -d '{"instructions":[{"kind":"updateFallthroughVariationOrRollout","variationId":"<id-from-step-above>"}]}'

如果本地已安装 LD CLI，也可以执行相同操作：

ldcli resources ai-configs update-ai-config-targeting \
  --projectKey $PROJECT --configKey $CONFIG_KEY --envKey $ENV \
  --data '{"instructions":[{"kind":"updateFallthroughVariationOrRollout","variationId":"<id>"}]}'

不要使用 turnTargetingOn — 这条语义补丁指令不适用于配置。updateFallthroughVariationOrRollout 是唯一能实际切换回退设置的指令。

modelConfigKey 格式

模型要在 UI 中显示，此项为必填。格式：{Provider}.{model-id}

• OpenAI.gpt-4o
• OpenAI.gpt-4o-mini
• Anthropic.claude-sonnet-4-5
• Anthropic.claude-3-5-sonnet

create-ai-config-variation 工具会验证此格式，并拒绝无效值。

边缘情况

情况	操作
配置已存在	询问用户是否想改为更新配置
变体显示“NO MODEL”	使用 update-ai-config-variation 设置 modelConfigKey
需要附加工具	先创建工具（tools 技能），然后更新变体

不要执行的操作

• 不要在不了解使用场景的情况下创建配置
• 不要跳过两步流程（先创建配置，再创建变体）
• 不要在初始创建时尝试附加工具 — 应在之后更新变体
• 不要忘记 modelConfigKey（模型不会显示在 UI 中）
• 初始变体调用时不要省略 modelName。创建时必须提供此项；后续通过 PATCH 设置是针对 Bug 的变通方法，并非预期流程。PATCH 字段也应为 modelName，而不是 name。
• 验证时不要退回到原始 curl + jq。请使用 get-ai-config（MCP）— 它会返回类型化对象，并避免使用会因响应结构变化而失效的脆弱 jq 过滤器。
• 在告知用户运行 configs-targeting 之前，不要认为工作流已完成。未提升为回退变体的已创建变体，对所有使用者都会返回 enabled=False。

更多资源

要了解如何在 LaunchDarkly UI 中创建配置，请阅读 创建配置

要了解如何配置 SDK，请阅读：

• .NET AI SDK 参考
• Go AI SDK 参考
• Node.js（服务端）SDK AI 参考
• Python AI SDK 参考
• Ruby AI SDK 参考

相关技能

• tools -- 先创建工具，再进行关联
• configs-variations -- 添加更多变体以进行实验
• configs-update -- 根据经验修改配置