Back to Details

configs-create

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create Config

创建配置项

You're using a skill that will guide you through creating a config in LaunchDarkly. Your job is to understand the use case, choose the right mode, create the config and its variations, and verify everything is set up correctly.
⚠️ This skill creates a config — it does not make it servable. A freshly-created config has its fallthrough pointing at an auto-generated disabled variation, not at the variation you just created. The SDK will return 
ai_config.enabled=False
on every evaluation until you flip targeting on and point the fallthrough at your new variation. This is not a bug — it's the default state. You must run 
/configs-targeting
(or the equivalent REST / CLI call shown in Step 5) before verifying against the SDK, or verification will look like the LD-served path is broken when it isn't. The single most common failure mode users hit with this skill is skipping the targeting step and spending time debugging 
enabled=False
in their application code.
您正在使用一项技能，它将引导您在LaunchDarkly中创建配置项。您的任务是理解使用场景，选择合适的模式，创建配置项及其变体，并验证所有设置是否正确。
⚠️ 本技能仅创建配置项——不会使其可被调用。 新创建的配置项的默认回退指向自动生成的禁用变体，而非您刚创建的变体。在您开启目标定位并将回退指向新变体之前，SDK每次评估都会返回 
ai_config.enabled=False
。这不是 bug——这是默认状态。在通过SDK验证之前，您必须运行 
/configs-targeting
（或步骤5中所示的等效REST/CLI调用），否则验证时会误以为LD提供的路径已损坏，但实际并非如此。用户使用本技能时最常见的失败情况就是跳过目标定位步骤，花费时间调试应用代码中的 
enabled=False
问题。

Prerequisites

前提条件

This skill requires the remotely hosted LaunchDarkly MCP server to be configured in your environment.
Primary MCP tool:
  • setup-ai-config
    -- create a config with its first variation in one step (recommended)
Alternative MCP tools (for more control):
  • create-ai-config
    -- create just the config shell (key, name, mode)
  • create-ai-config-variation
    -- add a variation with model, prompts, and parameters
  • get-ai-config
    -- verify the config was created correctly
Optional MCP tools (enhance workflow):
  • list-ai-configs
    -- browse existing configs to understand naming conventions
  • create-project
    -- create a project if one doesn't exist yet
使用本技能需要在您的环境中配置远程托管的LaunchDarkly MCP服务器。
主要MCP工具：
  • setup-ai-config
    —— 一步创建配置项及其首个变体（推荐）
备选MCP工具（用于更多控制）：
  • create-ai-config
    —— 仅创建配置项外壳（键、名称、模式）
  • create-ai-config-variation
    —— 添加包含模型、提示词和参数的变体
  • get-ai-config
    —— 验证配置项是否创建成功
可选MCP工具（优化工作流）：
  • list-ai-configs
    —— 浏览现有配置项以了解命名规范
  • create-project
    —— 若项目不存在则创建项目

Important: Bias Towards Action

重要：优先行动原则

When the user provides enough context (use case, model, mode), proceed through the entire workflow without stopping to ask for details you can infer. Use reasonable defaults for unspecified fields: 
default
for variation key, the use case as the basis for instructions/messages, kebab-case for config keys. Complete all steps (create + verify) in one pass.
当用户提供足够上下文（使用场景、模型、模式）时，直接完成整个工作流，无需停下来询问可推断的细节。对未指定的字段使用合理默认值：变体键使用 
default
，以使用场景作为指令/消息的基础，配置项键使用短横线分隔式（kebab-case）。一次性完成所有步骤（创建+验证）。

Workflow

工作流程

Step 1: Understand the Use Case

步骤1：理解使用场景

Before creating, identify what you're building:
  • What framework? LangGraph, LangChain, CrewAI, Strands, OpenAI SDK, Anthropic SDK, custom
  • What does the agent need? Just text generation, or tools/function calling?
  • Agent or completion? See the decision matrix below
创建之前，先明确您要构建的内容：
  • 使用什么框架？ LangGraph、LangChain、CrewAI、Strands、OpenAI SDK、Anthropic SDK、自定义框架
  • Agent需要什么？ 仅文本生成，还是需要工具/函数调用？
  • Agent模式还是Completion模式？ 参见下方决策矩阵

Step 2: Choose Agent vs Completion Mode

步骤2：选择Agent模式与Completion模式

This choice is about input schema and framework compatibility, not execution behavior. Agent mode returns an 
instructions
string; completion mode returns a 
messages
array. Both provide provider abstraction, A/B testing, and metrics tracking.
Your NeedModeWhy
LangGraph, CrewAI, Strands, AutoGen frameworksAgentFrameworks expect goal/instruction input
Persistent instructions across interactionsAgentSingle instructions string, SDK method: 
agent_config()
(Python) / 
agentConfig()
(Node)
Direct OpenAI/Anthropic API callsCompletionMessages array maps directly to provider APIs
Full control of message structureCompletionSystem/user/assistant role-based messages
One-off text generationCompletionStandard chat format
Need online evaluations (LLM-as-judge)CompletionOnline evals are only available in completion mode
Both modes support tools. Not all models support agent mode -- check model compatibility if using agent mode. If unsure, start with completion mode (it's the API default and more flexible).
此选择关乎输入模式与框架兼容性，而非执行行为。Agent模式返回 
instructions
字符串；Completion模式返回 
messages
数组。两种模式均支持供应商抽象、A/B测试和指标追踪。
您的需求模式原因
LangGraph、CrewAI、Strands、AutoGen框架Agent这些框架期望目标/指令输入
交互过程中保持指令持久化Agent单一指令字符串，SDK方法：
agent_config()
（Python）/ 
agentConfig()
（Node）
直接调用OpenAI/Anthropic APICompletion消息数组直接映射到供应商API
完全控制消息结构Completion基于角色（系统/用户/助手）的消息
一次性文本生成Completion标准聊天格式
需要在线评估（LLM-as-judge）Completion在线评估仅在Completion模式下可用
两种模式均支持工具。 并非所有模型都支持Agent模式——若使用Agent模式，请检查模型兼容性。若不确定，从Completion模式开始（这是API默认模式，且更灵活）。

Step 3: Create the Config (Recommended: One Step)

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

Use 
setup-ai-config
to create the config and its first variation in one call. This is the recommended approach: it handles creation, variation setup, and verification automatically.
Config fields:
  • key
    -- unique identifier (lowercase, hyphens)
  • name
    -- human-readable name
  • mode
    -- 
    "agent"
    or 
    "completion"
  • Optional: 
    description
    , 
    tags
Variation fields:
  • variationKey
    , 
    variationName
    -- identifiers for the first variation
  • modelConfigKey
    -- must be 
    Provider.model-id
    format (e.g., 
    OpenAI.gpt-4o
    , 
    Anthropic.claude-sonnet-4-5
    )
  • modelName
    -- the model identifier (e.g., 
    gpt-4o
    ). Always pass this in the initial call — leaving it off produces a variation that displays "NO MODEL" and forces a second PATCH to set it. The field is 
    modelName
    ; it is not 
    name
    or 
    model.name
    on this endpoint.
For agent mode, provide:
  • instructions
    -- a string with the agent's system instructions
Example agent-mode call:
json
{
  "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."
}
For completion mode, provide:
  • messages
    -- an array of 
    {role, content}
    objects (system, user, assistant)
Example completion-mode call:
json
{
  "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}}"}
  ]
}
Optional:
  • parameters
    -- model parameters like 
    {temperature: 0.7, max_tokens: 2000}
    (match the UI's snake_case keys)
The tool returns the full verified config detail with the variation attached.
使用 
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模式调用示例：
json
{
  "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}
    对象数组（系统、用户、助手）
Completion模式调用示例：
json
{
  "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的蛇形命名键）
该工具会返回附带变体的完整已验证配置项详情。

Step 3 (Alternative): Two-Step Creation

步骤3（备选）：两步创建

If the user asks for more control or a step-by-step approach, use the individual tools:
  1. create-ai-config
    -- create the config shell
  2. create-ai-config-variation
    -- add the variation with model, prompts, and parameters
  3. get-ai-config
    -- verify the result
Execute all three steps without stopping to ask for details. Infer the variation key (
default
), name (
Default
), instructions/messages, and model from the user's request context. If the user asked for GPT-4o agent mode, you have enough to complete the entire flow. Only ask clarifying questions if the mode or model is truly ambiguous.
如果用户要求更多控制或分步操作，请使用单独的工具：
  1. create-ai-config
    —— 创建配置项外壳
  2. create-ai-config-variation
    —— 添加包含模型、提示词和参数的变体
  3. get-ai-config
    —— 验证结果
无需停顿询问细节，直接执行所有三步。 从用户的请求上下文推断变体键（
default
）、名称（
Default
）、指令/消息和模型。如果用户要求GPT-4o Agent模式，您已有足够信息完成整个流程。仅当模式或模型确实不明确时才询问澄清问题。

Step 4: Verify

步骤4：验证

If you used 
setup-ai-config
, verification is automatic: the response includes the full config with variations. Check:
  1. Config exists with the correct mode
  2. Variation has a model assigned (not "NO MODEL")
  3. Instructions or messages are present
  4. Parameters are set
Use 
get-ai-config
for the verification call — do not drop to raw 
curl
+ 
jq
. The MCP tool returns a typed object you can inspect directly. Hand-rolled 
jq
filters against the REST response routinely break: the configs detail endpoint returns the variation list under different keys depending on 
expand
, and a filter like 
.variations.items[]
will fail with 
Cannot index array with string "items"
when the response shape is a bare array. If you must call the REST API, use 
jq -e .
first to inspect the actual shape before drilling in.
Report results:
  • Config created with correct structure
  • Variation has model assigned
  • Flag any missing model or parameters
  • Provide config URL: 
    https://app.launchdarkly.com/projects/{projectKey}/ai-configs/{configKey}
如果您使用了 
setup-ai-config
，验证是自动完成的：响应包含带变体的完整配置项。检查：
  1. 配置项已存在且模式正确
  2. 变体已分配模型（不是“NO MODEL”）
  3. 存在指令或消息
  4. 参数已设置
使用 
get-ai-config
进行验证调用——不要使用原始的 
curl
+ 
jq
。 MCP工具会返回您可以直接检查的类型化对象。针对REST响应手动编写的 
jq
筛选器经常出错：配置项详情端点根据 
expand
参数在不同键下返回变体列表，像 
.variations.items[]
这样的筛选器在响应形状为裸数组时会报错 
Cannot index array with string "items"
。如果必须调用REST API，请先使用 
jq -e .
检查实际形状，再深入筛选。
报告结果：
  • 配置项已按正确结构创建
  • 变体已分配模型
  • 标记任何缺失的模型或参数
  • 提供配置项URL：
    https://app.launchdarkly.com/projects/{projectKey}/ai-configs/{configKey}

Step 5: Make the variation servable

步骤5：使变体可被调用

setup-ai-config
and 
create-ai-config-variation
create the variation but do not promote it to fallthrough. The new config will return 
enabled=False
to every consumer until targeting is updated. This is the single most common "I created a config but my SDK still gets the fallback" failure. The workflow is not complete until this step is done.
setup-ai-config
和 
create-ai-config-variation
会创建变体，但不会将其提升为默认回退。在更新目标定位之前，新配置项会向所有消费者返回 
enabled=False
。这是最常见的“我创建了配置项但SDK仍获取回退值”问题。直到完成此步骤，工作流才算结束。

What to tell the user

告知用户的内容

Print this checklist verbatim to the user after Step 4, then wait for confirmation. Do not claim the skill succeeded until the user confirms the fallthrough was flipped.
✅ Config and variation are created.
🔴 The SDK will return 
enabled=False
until you flip targeting on. The fallthrough is currently pointing at an auto-generated disabled variation, not at the 
{variationKey}
you just created.
Next step — run 
/configs-targeting
 with these inputs:
  • Project key: 
    {projectKey}
  • Config key: 
    {configKey}
  • Environment key: the env whose SDK key is in your 
    .env
    (usually 
    test
    or 
    production
    )
  • Fallthrough variation: 
    {variationKey}
    (the one this skill just created)
Verify after targeting is flipped by:
  1. Opening the config in the LD UI, switching to the correct environment, and confirming "Default rule serves: 
    {variationName}
    " is shown with targeting On.
  2. Running a quick test: 
    ai_config = ai_client.{completion|agent}_config(...)
    and asserting 
    ai_config.enabled is True
    .
在步骤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
    。

Direct shortcut if the user wants to flip targeting without invoking the sibling skill

如果用户想不调用关联技能直接切换目标定位的快捷方式

configs-targeting
is the canonical path — it handles percentage rollouts, targeted rules, and variation-ID lookups. But for the simplest case ("promote the new variation to fallthrough in one environment"), you can run the underlying semantic PATCH yourself once you know the new variation's 
_id
.
Get the variation ID (use 
get-ai-config
MCP, or):
bash
curl -s "https://app.launchdarkly.com/api/v2/projects/$PROJECT/ai-configs/$CONFIG_KEY/targeting?env=$ENV" \
  -H "Authorization: $LD_API_KEY" -H "LD-API-Version: beta" \
  | jq '.variations[] | {key, _id}'
Flip the fallthrough to point at it:
bash
curl -X PATCH "https://app.launchdarkly.com/api/v2/projects/$PROJECT/ai-configs/$CONFIG_KEY/targeting?env=$ENV" \
  -H "Authorization: $LD_API_KEY" \
  -H "Content-Type: application/json; domain-model=launchdarkly.semanticpatch" \
  -H "LD-API-Version: beta" \
  -d '{"instructions":[{"kind":"updateFallthroughVariationOrRollout","variationId":"<id-from-step-above>"}]}'
Or the same thing via the LD CLI if it's installed locally:
bash
ldcli resources ai-configs update-ai-config-targeting \
  --projectKey $PROJECT --configKey $CONFIG_KEY --envKey $ENV \
  --data '{"instructions":[{"kind":"updateFallthroughVariationOrRollout","variationId":"<id>"}]}'
Do not use 
turnTargetingOn
— that semantic-patch instruction does not work for configs. 
updateFallthroughVariationOrRollout
is the only instruction that actually flips the fallthrough.
configs-targeting
是标准路径——它处理百分比发布、目标规则和变体ID查找。但对于最简单的情况（“在一个环境中将新变体提升为默认回退”），一旦您知道新变体的 
_id
，就可以自行运行底层语义PATCH。
获取变体ID（使用 
get-ai-config
MCP工具，或）：
bash
curl -s "https://app.launchdarkly.com/api/v2/projects/$PROJECT/ai-configs/$CONFIG_KEY/targeting?env=$ENV" \
  -H "Authorization: $LD_API_KEY" -H "LD-API-Version: beta" \
  | jq '.variations[] | {key, _id}'
将默认回退指向该变体：
bash
curl -X PATCH "https://app.launchdarkly.com/api/v2/projects/$PROJECT/ai-configs/$CONFIG_KEY/targeting?env=$ENV" \
  -H "Authorization: $LD_API_KEY" \
  -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，使用以下命令：
bash
ldcli resources ai-configs update-ai-config-targeting \
  --projectKey $PROJECT --configKey $CONFIG_KEY --envKey $ENV \
  --data '{"instructions":[{"kind":"updateFallthroughVariationOrRollout","variationId":"<id>"}]}'
不要使用 
turnTargetingOn
——该语义PATCH指令不适用于配置项。
updateFallthroughVariationOrRollout
是唯一能真正切换默认回退的指令。

modelConfigKey Format

modelConfigKey格式

Required for models to display in the UI. Format: 
{Provider}.{model-id}
  • OpenAI.gpt-4o
  • OpenAI.gpt-4o-mini
  • Anthropic.claude-sonnet-4-5
  • Anthropic.claude-3-5-sonnet
The 
create-ai-config-variation
tool validates this format and rejects invalid values.
要在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
工具会验证此格式并拒绝无效值。

Edge Cases

边缘情况

SituationAction
Config already existsAsk if user wants to update instead
Variation shows "NO MODEL"Use 
update-ai-config-variation
to set modelConfigKey
Need to attach toolsCreate tools first (
tools
skill), then update the variation
场景操作
配置项已存在询问用户是否要更新
变体显示“NO MODEL”使用 
update-ai-config-variation
设置modelConfigKey
需要附加工具先创建工具（
tools
技能），然后更新变体

What NOT to Do

禁止操作

  • Don't create configs without understanding the use case
  • Don't skip the two-step process (config then variation)
  • Don't try to attach tools during initial creation -- update the variation afterward
  • Don't forget modelConfigKey (models won't show in the UI)
  • Don't omit 
    modelName
    from the initial variation call. It is required at create time; setting it via a follow-up PATCH is a workaround for a bug, not the intended flow. The PATCH field is also 
    modelName
    , not 
    name
    .
  • Don't drop to raw 
    curl
    + 
    jq
    for verification. Use 
    get-ai-config
    (MCP) — it returns a typed object and avoids brittle 
    jq
    filters that break on response-shape variation.
  • Don't consider the workflow complete until the user has been told to run 
    configs-targeting
    . A created variation that isn't promoted to fallthrough returns 
    enabled=False
    to every consumer.
  • 不要在不理解使用场景的情况下创建配置项
  • 不要跳过两步流程（先配置项后变体）
  • 不要在初始创建时附加工具——之后再更新变体
  • 不要忘记modelConfigKey（模型不会在UI中显示）
  • 不要在初始变体调用中省略 
    modelName
    。创建时此字段是必需的；通过后续PATCH设置是针对bug的临时解决方法，而非预期流程。PATCH字段同样是 
    modelName
    ，而非 
    name
    。
  • 不要使用原始的 
    curl
    + 
    jq
    进行验证。使用 
    get-ai-config
    （MCP）——它返回类型化对象，避免因响应形状变化而失效的脆弱 
    jq
    筛选器。
  • 在告知用户运行 
    configs-targeting
    之前，不要认为工作流已完成。未被提升为默认回退的已创建变体将向所有消费者返回 
    enabled=False
    。

Related Skills

相关技能

  • tools
    -- Create tools before attaching
  • configs-variations
    -- Add more variations for experimentation
  • configs-update
    -- Modify configs based on learnings
  • tools
    —— 附加工具前先创建工具
  • configs-variations
    —— 添加更多变体用于实验
  • configs-update
    —— 根据学习成果修改配置项