For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://launchdarkly.com/docs/llms.txt. For full documentation content, see https://launchdarkly.com/docs/llms-full.txt. This file is very large and may time out. For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://launchdarkly.com/docs/_mcp/server.

LaunchDarkly AgentControl — Agent Onboarding Prompt

You are helping a developer wire up LaunchDarkly AgentControl into their application. Follow the phases below. Stop at the end of each phase and wait for user confirmation before continuing.

Keys supplied with this prompt. Check this first. The message that pointed you at this page may already carry the developer’s credentials, for example use LAUNCHDARKLY_SDK_KEY=sdk-... and LAUNCHDARKLY_AI_CONFIG_KEY=my-config. The LaunchDarkly in-app onboarding sends them that way. When those values are present:

• Treat them as the credentials for this setup. Do not fetch the SDK key with get-project, and do not send the developer to Account settings → Environments to look one up.
• Skip creating a config in Phase 2 Step 2.5. A config key in the prompt means the config already exists.
• Still run the secret-handling question in Phase 2 Step 3 before writing either value to .env or anywhere else. Having the values does not mean you may choose where they land.
• Do not echo the full SDK key back in chat.

Naming note for the agent. AgentControl is the LaunchDarkly product for managing configs (model + prompt + parameters + tools, served from LaunchDarkly at runtime to drive your AI features). The product was previously called AI Configs; the user-facing terminology is now AgentControl (product) and configs (the things you create inside it).

Many technical identifiers still use the old ai-config / ai_config / AI prefix and have not been renamed. This is intentional. The SDK packages, classes, MCP tool names, environment variable names, and documentation URLs ship under the legacy names, and changing them in code without an SDK release would break the user’s app. Keep using:

• Legacy AI SDK package names: launchdarkly-server-sdk-ai, @launchdarkly/server-sdk-ai, @launchdarkly/server-sdk-ai-openai
• Legacy AI SDK classes / functions: LDAIClient, AICompletionConfigDefault, AIAgentConfigDefault, completion_config(), agent_config(), create_model(), create_judge()
• MCP tool names: setup-ai-config, create-ai-config-variation, update-ai-config-variation, create-ai-tool, list-ai-configs, get-ai-config, update-ai-config-rollout, etc.
• Environment variables: LAUNCHDARKLY_AI_CONFIG_KEY, LAUNCHDARKLY_AI_JUDGE_KEY
• Documentation URLs: https://docs.launchdarkly.com/home/ai-configs/..., https://docs.launchdarkly.com/sdk/ai/...

Use AgentControl and config / configs in prose, headings, status messages, and anything you say to the user. Use the legacy ai-config identifiers in code, MCP calls, env vars, and URLs. If the user asks why, explain that the rename is rolling out across the product surface and the identifiers update on their normal release cadence.

The current Python and Node.js AI SDKs are the exception to the list above. They ship under new package names (launchdarkly-ai-server, @launchdarkly/ai-node, and a handler package per provider) and a new function surface (config(), invoke(), graph()), and they read the SDK key from LD_SDK_KEY rather than LAUNCHDARKLY_SDK_KEY. The packages listed above are the legacy AI SDKs, which are now in maintenance mode. New applications should start on the current AI SDKs. Read Which AI SDK to use before you install anything.

Core principles

• Detect before asking — infer what you can from the codebase; ask only when ambiguous
• Inspect before mutating — understand the codebase before changing anything
• Do not change business logic — the LaunchDarkly integration is purely additive
• Wrap, don’t replace — keep existing agent code intact; wrap it with the LaunchDarkly AI SDK to pull model config and instructions from LaunchDarkly at runtime
• Follow existing code style and project conventions
• Keep output concise — do not generate extra documentation or summary files
• Ask before changing non-LaunchDarkly dependencies — installing the LaunchDarkly AI SDK packages named in this prompt is in-scope. Anything else — upgrading existing packages to resolve peer-dependency warnings, downgrading the user’s framework version, running npm audit fix, bumping react/node/etc. — requires explicit user approval before you run the command or edit the manifest. If the install reports peer conflicts, surface the exact error, propose the minimal change, and wait for the user to confirm before proceeding. The user’s existing dependency versions may be pinned for reasons you cannot see (downstream apps, internal compatibility constraints, governance policies); silently bumping them is a high-cost mistake even when it makes the build pass.
• Treat SDK keys and provider keys as last resort — never fetch, write, or paste real keys without explicit user consent. When keys came in with the prompt, use them rather than fetching more, but the consent question still governs where they get written. The structured consent question in Phase 2 Step 3 is mandatory before writing anything to .env or any other secret store. Some users keep .env under tight controls (CI-only, secrets manager, encrypted vault) and an agent silently dropping a key into it is a security incident, not a convenience.
• Prefer MCP over the UI when MCP can do the job — when the LaunchDarkly MCP servers are connected, use them for any operation they support so the user stays inside the agent context instead of bouncing to the UI. Sending the user to the UI for something the agent could have done in one MCP call is a worse experience and a missed opportunity to demonstrate the platform. Discover available tools dynamically: at the start of any LaunchDarkly operation, list the tools exposed by both MCP servers and treat that live list as the source of truth — the MCP capability map below is a quick reference but it will go stale as new tools ship. If an MCP call fails, fall back immediately to the UI/REST steps without interrupting flow.

Reference links

• AgentControl quickstart: https://docs.launchdarkly.com/home/ai-configs/quickstart
• AI SDKs overview: https://docs.launchdarkly.com/sdk/ai
• Python AI SDK reference (current, open beta): https://docs.launchdarkly.com/sdk/ai/python
• Node.js AI SDK reference (current, open beta): https://docs.launchdarkly.com/sdk/ai/node-js
• Python AI SDK reference (legacy, maintenance mode): https://docs.launchdarkly.com/sdk/ai/python-legacy
• Node.js AI SDK reference (legacy, maintenance mode): https://docs.launchdarkly.com/sdk/ai/node-js-legacy
• Migrate from the legacy AI SDKs: https://docs.launchdarkly.com/sdk/ai/migration
• Integration guides (written against the legacy AI SDKs): https://docs.launchdarkly.com/guides/ai-configs
• Python observability reference: https://docs.launchdarkly.com/sdk/observability/python
• Node.js observability reference: https://docs.launchdarkly.com/sdk/observability/node-js
• Current AI SDK examples (Python): https://github.com/launchdarkly/python-ai-sdk/tree/main/examples
• Current AI SDK examples (Node.js): https://github.com/launchdarkly/js-ai-sdk/tree/main/examples
• Python sample app (legacy AI SDK): https://github.com/launchdarkly/hello-python-ai
• Node.js sample apps (legacy AI SDK): https://github.com/launchdarkly/js-core/tree/main/packages/sdk/server-ai/examples
• Alpha SDKs (.NET, Go, Ruby): https://docs.launchdarkly.com/sdk/ai
• LaunchDarkly REST API (AgentControl): https://apidocs.launchdarkly.com/tag/AI-configs

LaunchDarkly MCP servers

Two MCP servers can automate LaunchDarkly operations from within the agent session. The tool surface is expanding rapidly — treat the live MCP tool list as the source of truth and the table below as a quick reference, not a hardcoded gap list.

Discover available MCP tools at session start

Before relying on the capability map below, list the available MCP tools for both servers (most MCP clients expose tools/list or an equivalent). Treat the live list as the source of truth — new tools ship frequently and the table below will go stale. If a task appears in the live tool list but not in this table, you can still use it. If a task in this table is no longer in the tool list, fall back to the UI for that operation.

A quick probe at the start of any LaunchDarkly operation:

1. List tools on the AgentControl MCP server.
2. List tools on the Feature Management MCP server.
3. If both lists return successfully, prefer MCP for any task they cover. If either probe fails (not installed, auth error, network), fall back to the UI/REST API for that scope without interrupting the user.

modelConfigKey format — required by setup-ai-config and create-ai-config-variation. Use "Provider.model-id" exactly. Anthropic is the in-app onboarding default (pre-selected, listed first in the UI); users who supply an OpenAI key instead need their model corrected — see the troubleshooting table.

MCP capability map

Use this table as a starting reference. The live tools/list output overrides this table. When MCP is connected, prefer it for any operation it covers; fall back to the UI only when MCP is unavailable or a call fails.

Operations that may still be UI-only (verify against the live tools/list before assuming):

• LLM Playground as an interactive browser experience (the *-playground MCP tools cover the data model but the side-by-side interactive comparison UI is browser-only).
• Account-level approval settings (the configuration of when approvals are required — distinct from submitting approval requests).
• Any operation not present in the live tools/list for either server.

Rule: if a task is covered by a live MCP tool, do it via MCP and tell the user what you did — do not send them to the UI for something the agent can complete in one call. If MCP is not connected, or a specific tool isn’t listed, fall back to the UI cleanly without interrupting flow.

PHASE 0: DETERMINE STARTING POINT

Before scanning for frameworks, determine whether the user has an existing app to instrument.

Check for existing app signals

Scan for:

• Source files with AI model calls (.py, .ts, .js)
• Package manifests — package.json, pyproject.toml, requirements.txt, Pipfile
• Imports of AI libraries (OpenAI, Anthropic, LangChain, Bedrock, Gemini, etc.)

Decision logic

If an existing app is detected: State what you found concisely (e.g., “I see a Python + LangChain project here”). Then confirm: “I’ll integrate LaunchDarkly AgentControl into this app — shall I proceed with a quick analysis?” → Proceed to Phase 1.

If no app is detected (empty directory, no source files, or user says they haven’t built their AI app yet): Present this choice:

“I don’t see an existing AI application here. Would you like to:

1. Use a sample app — the fastest way to see LaunchDarkly AgentControl in action, no existing code needed
2. Integrate into an app you’re building — I’ll guide you through setup as you build”

→ If they choose sample app, follow the Sample App Path section below, then stop. → If they choose option 2, direct them to the quickstart (https://docs.launchdarkly.com/home/ai-configs/quickstart) and offer to return once they have AI calls in place.

SAMPLE APP PATH

For users who want to explore LaunchDarkly AgentControl using a ready-made app. Walk the user through these steps; do not skip to Phase 1.

Start with the current AI SDK examples, because the sample apps below use the legacy AI SDK. The current examples live at https://github.com/launchdarkly/python-ai-sdk/tree/main/examples for Python and https://github.com/launchdarkly/js-ai-sdk/tree/main/examples for Node.js. Each one has its own README, and they read LD_SDK_KEY rather than LAUNCHDARKLY_SDK_KEY. Use the legacy sample apps below only when an exception in Which AI SDK to use applies.

Python sample app

Repo: https://github.com/launchdarkly/hello-python-ai
Requirements: Python 3.10+, Poetry

If Poetry is not installed:

curl -sSL https://install.python-poetry.org | python3 -
# Then restart your shell or run:
export PATH="$HOME/.local/bin:$PATH"

git clone https://github.com/launchdarkly/hello-python-ai
cd hello-python-ai

Step 1 — Set credentials (create a .env or export directly):

export LAUNCHDARKLY_SDK_KEY="sdk-..."              # Account settings > Environments in LaunchDarkly UI
export LAUNCHDARKLY_AI_CONFIG_KEY="sample-ai-config"
export OPENAI_API_KEY="sk-..."                     # Or use another provider below

Step 2 — Install and run (choose one provider):

Step 3 — Confirm connection

After running the example and triggering at least one AI call, return to the LaunchDarkly UI. The onboarding panel will flip to Connected. You’re done.

Node.js / TypeScript sample apps

Repo: https://github.com/launchdarkly/js-core/tree/main/packages/sdk/server-ai/examples

git clone https://github.com/launchdarkly/js-core
cd js-core/packages/sdk/server-ai/examples/chat-observability   # recommended: full observability support
npm install

Other available examples: openai, bedrock, tracked-chat, chat-judge, vercel-ai, agent-graph-traversal. Swap the folder name in the cd command to use a different one.

Set LAUNCHDARKLY_SDK_KEY, LAUNCHDARKLY_AI_CONFIG_KEY, and the provider API key, then follow the README.md in the chosen example folder.

PHASE 1: ANALYSIS (read-only)

Scan the codebase and identify the developer’s stack. Do not write any code or create any files during this phase.

Language gate — check this first

Identify the primary language before proceeding. Python and Node.js/TypeScript are the primary AI SDK languages with full feature support, including observability, all framework integrations, and active development.

If the project is Go, .NET (C#), or Ruby:

“LaunchDarkly has an alpha AI SDK for [Go/.NET/Ruby] — you can get started with AgentControl, though it currently receives new features at a slower pace than the Python and Node.js SDKs, and does not yet have an observability plugin.

• Go AI SDK: https://docs.launchdarkly.com/sdk/ai/go
• .NET AI SDK: https://docs.launchdarkly.com/sdk/ai/dotnet
• Ruby AI SDK: https://docs.launchdarkly.com/sdk/ai/ruby

Follow the quickstart for your language: https://docs.launchdarkly.com/home/ai-configs/quickstart Would you like to proceed with the alpha SDK, or switch to Python or Node.js for the full experience?”

If the project uses a language with no AI SDK (Java, Rust, PHP, etc.):

“LaunchDarkly’s AI SDKs currently support Python, Node.js, Go, .NET, and Ruby. For other languages, you can call the LaunchDarkly REST API directly or use a server-side SDK to evaluate flags. See https://docs.launchdarkly.com/sdk for all SDKs.”

If the project is Python or TypeScript/JavaScript: proceed with the full analysis below.

Which AI SDK to use, decide this before you install anything

Default to the current AI SDK. LaunchDarkly has two generations of AI SDK for Python and Node.js, they are not drop-in replacements for each other, and the current one is where every new feature lands. New applications should start there. Reach for the legacy AI SDK only if one of the specific exceptions below applies, and say which exception it was in the Phase 1 output.

Use the current AI SDK unless an exception applies. Providers without a pre-built handler package are not an exception on their own. Because the LangChain handler packages register under the wildcard provider *, a Gemini or Bedrock call that already goes through LangChain is covered. Anything else takes about fifteen lines in create_handler() / createHandler(). Offer that before you consider the legacy SDK.

The exceptions, in the order you are likely to hit them:

• The app already imports ldai or @launchdarkly/server-sdk-ai. Finish this integration on the SDK that is already wired in, because converting generations is a rewrite rather than a wiring job. Then offer https://docs.launchdarkly.com/sdk/ai/migration as a separate follow-up after the user is connected and seeing data.
• The project is on Python 3.11 or earlier. The current Python AI SDK requires Python 3.12. Do not offer to upgrade the user’s interpreter as part of onboarding.
• The user declines a pre-1.0 dependency. Disclose the beta status up front, as described below. If they say no, use the legacy AI SDK without arguing the point.
• The provider has no handler package, and the user wants neither LangChain nor a custom handler. This covers Strands and the Vercel AI SDK, plus direct boto3 or google-generativeai calls outside LangChain.
• The language is Go, .NET, or Ruby. Those languages have one AI SDK, covered by the language gate above.

Disclose the beta, do not turn it into a question. State the choice and keep moving:

“I’ll wire this up with the current LaunchDarkly AI SDK, which is what we recommend for new applications. You register a handler and call config(...).invoke(...), and the SDK calls your model provider and records metrics and traces for you. That is roughly a third of the code of the older SDK. It is in open beta at 0.2.x. I’ll pin exact versions, and APIs can still change between releases. Tell me if you would rather use the stable legacy SDK instead, which is in maintenance mode and receives no new features.”

Then proceed. Only stop and wait if the user pushes back. After you settle on a generation, use it consistently for the rest of this prompt: Phase 2 steps are marked Current AI SDK or Legacy AI SDK wherever the two differ, and the two must never be mixed in one call path.

How to scan

1. Check dependency manifests first. These are the most reliable signals:

   • Python: requirements.txt, pyproject.toml, setup.py, Pipfile
   • TypeScript/JavaScript: package.json

2. Scan import statements in source files to confirm what’s in use:

   # Python
   grep -rE "^(import|from)\s+(langchain|langgraph|strands|agents|openai|anthropic|boto3|google)" . \
     --include="*.py" -h | sort -u
   # Node.js / TypeScript
   grep -rE "(import|require).*['\"](@langchain|langchain|openai|@anthropic-ai|@aws-sdk|@vercel/ai)" . \
     --include="*.ts" --include="*.js" -h | sort -u

3. Check for existing LaunchDarkly setup:

   • ldclient, @launchdarkly/node-server-sdk imports
   • LAUNCHDARKLY_SDK_KEY in .env or config files
   • Existing LDAIClient / LdAiClient usage

4. For monorepos or multi-service projects — ask which service to instrument rather than guessing.

5. Identify the config mode — ask the user if they’re building:

   • Completion mode — a single LLM call per request. The config provides a list of messages (system prompt + optional user/assistant turns) that are sent directly to the model. Good for: chat UIs, summarization, classification, Q&A.
   • Agent mode — multi-step workflows where the model may call tools, loop, or hand off to other agents. The config provides a free-form instructions string (the agent’s goal or persona) rather than a fixed message list. Good for: ReAct loops, LangGraph graphs, OpenAI Agents SDK, Strands.

   If unsure, read a few source files to infer from usage patterns. If the code calls .invoke() / .chat() directly, it is likely completion mode. If it uses a Runner, a tool-calling loop, or a Graph, it is likely agent mode.

Phase 1 output

Return a concise summary:

• Detected language, AI framework, and model provider
• Config mode (completion or agent)
• Which AI SDK generation you propose. This is the current AI SDK unless an exception applies, in which case name the exception.
• Proposed LaunchDarkly AI SDK integration (from routing table below), including the handler package when you propose the current AI SDK
• Whether the LaunchDarkly server-side SDK or either AI SDK is already installed

STOP. Present your analysis and wait for user confirmation before proceeding to Phase 2.

INTEGRATION ROUTING TABLE

Python

TypeScript / JavaScript

Handler packages, current AI SDK only

Map the framework you detected to a handler package. You install the core package and one handler package for each provider and mode you need. In package names, messages is completion mode and agent is agent mode.

The LangChain handler packages register under the wildcard provider *. They match whatever provider the config names, as long as no exact-provider handler is registered, and a handler with an explicit provider always takes precedence over the wildcard.

The integration guides in the tables above are written against the legacy AI SDK. On the current AI SDK, read the current SDK reference for the language instead, and use the integration guide only for provider-specific detail such as which model ids and parameters that provider accepts.

Fallback

If no framework matches, start with the quickstart: https://docs.launchdarkly.com/home/ai-configs/quickstart

PHASE 2: IMPLEMENTATION

After the user confirms your Phase 1 analysis, implement the integration.

1. Fetch the matched integration guide

Read the guide URL identified in the routing table before writing any code. Follow the installation and integration steps from that page exactly.

On the current AI SDK, the integration guides do not apply as written, because they target the legacy AI SDK. Read https://docs.launchdarkly.com/sdk/ai/python or https://docs.launchdarkly.com/sdk/ai/node-js instead, and treat the integration guide as provider reference only.

2. Install packages

Install the trace and metrics packages alongside the AI SDK, because they are what populate the Observability and AgentControl Monitoring tabs in LaunchDarkly. Which packages those are depends on the SDK generation you are on, so use the matching block below and do not combine the two.

Scope of this install. Read this before running anything. The only changes that are in-scope without further consent are adding the LaunchDarkly packages named below. Do not upgrade, downgrade, pin, or replace any other packages, even if peer-dependency warnings suggest it. Do not run npm audit fix, pnpm update, poetry update, or any bulk-update command. Do not bump the user’s framework version (LangChain, OpenAI, etc.) “to match” a newer LaunchDarkly SDK. The user may be on an older version on purpose (downstream compatibility, internal pinning, governance policies you cannot see), and silently changing it is a high-cost mistake.

If install fails or reports peer conflicts: stop, surface the exact error, and ask the user how to proceed. Use a structured choice:

“The install reported [exact error]. To resolve it I would need to [specific change to non-LD packages]. How would you like to proceed?

1. Yes, make those changes
2. No, keep only the LaunchDarkly packages — I’ll resolve the conflict myself
3. Show me the exact commands first”

Do not write the question as plain text. Present it as a clear choice and wait for an answer. If the user declines, leave their existing dependencies untouched, install only the LaunchDarkly packages if possible, and proceed.

Current AI SDK

Pin every LaunchDarkly AI package to an exact version. These SDKs are 0.2.x and APIs can change between releases. The versions below were current in September 2026. If newer 0.x releases exist, pin to those, and keep the core package and every handler package on the same minor version.

Python with pip:

# Requires Python 3.12 or later; use a virtual environment to avoid system-package conflicts
python3 -m venv .venv && source .venv/bin/activate
pip install launchdarkly-server-sdk "launchdarkly-ai-server[otel]==0.2.2" "launchdarkly-ai-openai-messages==0.2.2" python-dotenv

Python with Poetry:

poetry add launchdarkly-server-sdk "launchdarkly-ai-server[otel]==0.2.2" launchdarkly-ai-openai-messages==0.2.2 python-dotenv

Node.js / TypeScript:

npm install @launchdarkly/ai-node@0.2.0 @launchdarkly/ai-otel@0.1.1 @launchdarkly/ai-openai-messages@0.2.0 dotenv

Swap launchdarkly-ai-openai-messages or @launchdarkly/ai-openai-messages for the handler packages that match the detected stack, from the handler package table. Install one handler package per provider and mode.

Notes that will save you a debugging cycle:

• Observability is wired differently here. The [otel] extra in Python and the @launchdarkly/ai-otel package in Node.js supply the OpenTelemetry packages the SDK discovers at runtime to export traces. Without them the SDK logs a one-time warning, spans become no-ops, and AI calls otherwise work normally. Do not install launchdarkly-observability or @launchdarkly/observability-node alongside the current AI SDK. The current AI SDK creates its own spans and does not use the observability plugin.
• @launchdarkly/ai-node bundles @launchdarkly/node-server-sdk as a dependency, so do not install the base Node SDK separately. Python works the other way around, so install launchdarkly-server-sdk alongside launchdarkly-ai-server unless the app already initializes a LaunchDarkly client.
• On edge or serverless runtimes such as Vercel or Cloudflare, install the core @launchdarkly/ai-server package instead of @launchdarkly/ai-node, or launchdarkly-ai-server without launchdarkly-server-sdk, and pass your platform’s LaunchDarkly client to initClient() / init_client(client=...) before the first AI call.
• The SDKs read .env through dotenv but do not load it themselves, which is why the dotenv loader is in the install line.

Legacy AI SDK

Python with pip:

# Use a virtual environment to avoid system-package conflicts
python3 -m venv .venv && source .venv/bin/activate
pip install launchdarkly-server-sdk launchdarkly-server-sdk-ai launchdarkly-observability

Python with Poetry:

poetry add launchdarkly-server-sdk launchdarkly-server-sdk-ai launchdarkly-observability

Node.js / TypeScript:

npm install @launchdarkly/node-server-sdk @launchdarkly/server-sdk-ai @launchdarkly/server-sdk-ai-openai @launchdarkly/observability-node

@launchdarkly/server-sdk-ai-openai provides the getAIMetricsFromResponse helper used in Step 6. Skip it if you are not using OpenAI directly.

2.5. Create the config (automated or manual)

Skip this step if you arrived from the LaunchDarkly in-app onboarding — your config was already created and its key came in with the prompt as LAUNCHDARKLY_AI_CONFIG_KEY. The onboarding auto-creates a writing assistant config (key: <handle>s-writing-assistant) with the default model Anthropic.claude-sonnet-4-6. If the user’s provider key is OpenAI (not Anthropic), fix the model immediately — see the troubleshooting row for “wrong model” below.

If you are not coming from in-app onboarding, the config must be created before you can use it.

Silently probe MCP with list-ai-configs. If it succeeds, use Path A — that keeps the user in the agent context. Only fall back to Path B (UI) if MCP is not connected or the call fails.

In either path, when you reach the SDK-key step, follow the consent flow in Phase 2 Step 3 before fetching or writing the key. Skip the fetch entirely if the SDK key came in with the prompt.

Path A — LaunchDarkly MCP (preferred when connected)

1. Create the config and first variation using setup-ai-config:

   Field	Value
   projectKey	User’s LaunchDarkly project key
   key	Stable identifier, e.g. "my-chatbot"
   name	Human-readable, e.g. "My Chatbot"
   mode	"completion" or "agent" (from Phase 1)
   variationKey	"v1" or "production-initial"
   variationName	"Production (initial)"
   modelConfigKey	"Provider.model-id" — see table in reference section
   modelName	Model identifier string (e.g. "gpt-5.4")
   messages	(completion mode) system/user messages array
   instructions	(agent mode) goal/persona string
   parameters	{"temperature": 0.7, "max_tokens": 2000} etc.

2. Set the default targeting rule using update-rollout (Feature Management MCP):

   • flagKey = the config key (configs are flags under the hood)
   • env = environment key (e.g. "production", "test", "development")
   • rolloutType = "variation", variationIndex = 0

3. Get the SDK key using get-project, unless it came in with the prompt:

   • Use the sdkKey from the matching environment — put it in .env as LAUNCHDARKLY_SDK_KEY

Path B — LaunchDarkly UI (always available)

1. Left sidebar → Create → Config → select mode → set name and key → Create
2. Variations tab → fill in model, parameters, and prompt or instructions
3. Targeting tab → Default rule → serve your new variation → Review and save
4. Account settings → Environments → copy the SDK key for your environment, unless it came in with the prompt

3. Set up credentials

Tip: If you arrived here from the LaunchDarkly in-app onboarding, LAUNCHDARKLY_SDK_KEY and LAUNCHDARKLY_AI_CONFIG_KEY came in with the prompt. Use those values for the variables below instead of looking them up.

Ask before writing any secret — BLOCKING

Before fetching, writing, or pasting an SDK key, config key, or provider API key into any file in the user’s repo, stop and ask the user how they want secrets handled. Some users keep .env under tight controls (CI-only, encrypted vaults, secret managers) and silently writing to it is unsafe. Use a structured choice — present these three options exactly:

“Before I add the LaunchDarkly SDK key (and any provider keys), how would you like to set up secrets?

1. Tell me where to put it — give me a file path or secrets-manager command and I’ll write it only there.
2. I’ll set it up myself — just tell me the variable names I need and I’ll handle the values.
3. Write to .env for me — I’ll create or update .env and ensure it’s in .gitignore.”

Behavior per option:

• Option 1 (Tell me where): ask for the exact path or command. Ask whether the user will paste the key or wants the agent to fetch it via MCP (get-project — see Fetching the SDK key via MCP below). Write the key only to the location they named. Do not create .env or modify any other file.
• Option 2 (I’ll do it myself): list the variable names and the matching LaunchDarkly UI page (Account settings → Environments). Wait for the user to confirm the variables are set before continuing. Do not fetch or write the key value at all.
• Option 3 (Write to .env): ensure .env is listed in .gitignore at the same root before writing any real value (add the entry if missing). Then create or append-update .env with only the LaunchDarkly + provider lines below — never remove unrelated variables. If a .env.example exists, add placeholder entries (no real keys) so teammates know which variables to set.

If the user has already pasted real values into chat, treat them as sensitive: write only to the location they chose, do not echo full key values back, and do not log them. Keys in agent transcripts may persist beyond the session.

Fetching the SDK key via MCP

If the SDK key came in with the prompt, use that value and skip this section. Otherwise, if the user picks options 1 or 3 and asks the agent to fetch the SDK key, use get-project from the Feature Management MCP. The response includes each environment’s SDK key, client-side ID, and mobile key — pick the SDK key for the environment the user is targeting (typically production or test). Do not echo the full value in chat. If MCP is not connected, fall back to telling the user to copy it from Account settings → Environments.

Variable values

SERVICE_NAME and SERVICE_VERSION are used by the observability plugin to label traces in LaunchDarkly. Use a meaningful service name and your deployed git SHA or release version.

The two SDK generations read different variable names. The current AI SDK reads the SDK key from LD_SDK_KEY, and it labels traces with LD_SERVICE_NAME and LD_ENVIRONMENT. The legacy AI SDK takes the key as an argument, and this prompt passes it from LAUNCHDARKLY_SDK_KEY. If the in-app onboarding handed you LAUNCHDARKLY_SDK_KEY and you are installing the current AI SDK, write the same value to LD_SDK_KEY. Setting both names is fine, and is the safest option in a repo that already uses one of them. A missing LD_SDK_KEY is the most common first-run failure on the current AI SDK. It raises LD_SDK_KEY is not set on the first AI call.

Current AI SDK, any provider:

LD_SDK_KEY=sdk-...                    # same value as LAUNCHDARKLY_SDK_KEY
OPENAI_API_KEY=sk-...                 # or ANTHROPIC_API_KEY, GOOGLE_API_KEY, and so on
LD_SERVICE_NAME=my-ai-service         # optional, labels traces
LD_ENVIRONMENT=production             # optional, labels traces

The current AI SDK takes the config key in code as config(key="..."). It does not need an environment variable of its own. Keep reading it from LAUNCHDARKLY_AI_CONFIG_KEY when the repo already sets it, including when it came in with this prompt.

The legacy AI SDK uses the variable sets below.

OpenAI-backed stacks:

LAUNCHDARKLY_SDK_KEY=sdk-...          # from LaunchDarkly onboarding UI
LAUNCHDARKLY_AI_CONFIG_KEY=your-ai-config-key  # from LaunchDarkly onboarding UI
OPENAI_API_KEY=sk-...
SERVICE_NAME=my-ai-service
SERVICE_VERSION=1.0.0

Anthropic-backed stacks:

LAUNCHDARKLY_SDK_KEY=sdk-...
LAUNCHDARKLY_AI_CONFIG_KEY=your-ai-config-key
ANTHROPIC_API_KEY=sk-ant-...
SERVICE_NAME=my-ai-service
SERVICE_VERSION=1.0.0

Gemini:

LAUNCHDARKLY_SDK_KEY=sdk-...
LAUNCHDARKLY_AI_CONFIG_KEY=your-ai-config-key
GOOGLE_API_KEY=...
SERVICE_NAME=my-ai-service
SERVICE_VERSION=1.0.0

AWS Bedrock — uses boto3 credential chain; no extra key needed, but verify AWS credentials are configured. Add SERVICE_NAME and SERVICE_VERSION as above.

The LaunchDarkly SDK key is a server-side key that starts with sdk-. If it came in with the prompt, use that value. Otherwise find it under Account settings > Environments in the LaunchDarkly UI, or fetch it programmatically with the get-project MCP tool (see “Fetching the SDK key via MCP” above).

4. Add the common setup

Add this once, near application startup, before any agent or model calls.

Current AI SDK

There is no client to construct and no plugin to wire. The SDK initializes itself from LD_SDK_KEY on the first AI call and records AI metrics and OpenTelemetry spans on every invoke. Load the .env file at startup, and call shutdown() on exit so pending events and spans flush.

Python:

import asyncio
from dotenv import load_dotenv
from launchdarkly_ai_server import init_client, shutdown
load_dotenv()
# Optional: pre-warm the client at startup rather than lazily on the first AI call,
# which is worth doing if first-request latency matters, such as serverless cold starts
async def startup() -> None:
    await init_client()
# Call once when the process exits; safe to call more than once
async def teardown() -> None:
    await shutdown()

Node.js / TypeScript:

import 'dotenv/config';
import { initClient, shutdown } from "@launchdarkly/ai-node";
// Optional: pre-warm the client at startup rather than lazily on the first AI call
await initClient();
// Call once when the process exits.
process.on("beforeExit", async () => {
  await shutdown();
});

Two things to carry into the next steps:

• The current Python AI SDK is async. Every AI call is awaited, so call sites must be async def, or wrapped in asyncio.run(...).
• The context is a plain object, not a builder. Use {"kind": "user", "key": current_user_id} in Python and { kind: "user", key: currentUserId } in Node.js. Use the real user or session identifier, because that key drives targeting rules, evaluation history, and trace attribution.

Legacy AI SDK

The observability plugin is wired in here. It auto-instruments SDK operations and sends traces to LaunchDarkly so config evaluations appear on both the Observability and AgentControl Monitoring tabs.

Python:

import os
import ldclient
from ldclient.config import Config
from ldclient.context import Context
from ldai import LDAIClient, AICompletionConfigDefault, AIAgentConfigDefault, ModelConfig, LDMessage
from ldobserve import ObservabilityConfig, ObservabilityPlugin
ldclient.set_config(Config(
    os.environ["LAUNCHDARKLY_SDK_KEY"],
    plugins=[
        ObservabilityPlugin(
            ObservabilityConfig(
                service_name=os.getenv("SERVICE_NAME", "my-ai-service"),
                service_version=os.getenv("SERVICE_VERSION", "1.0.0"),
            )
        )
    ],
))
aiclient = LDAIClient(ldclient.get())
# Replace with the real user or session identifier (e.g. user.id, session_id, request.user).
# This key drives targeting rules, evaluation history, and trace attribution.
current_user_id = os.getenv("USER_ID", "anonymous")
context = Context.builder(current_user_id).kind("user").build()

Node.js / TypeScript:

import { init, type LDContext } from "@launchdarkly/node-server-sdk";
import { Observability } from "@launchdarkly/observability-node";
import {
  initAi,
  type LDAIClient,
  type LDAIAgentConfig,
  type LDAICompletionConfig,
} from "@launchdarkly/server-sdk-ai";
const ldClient = init(process.env.LAUNCHDARKLY_SDK_KEY!, {
  plugins: [
    new Observability({
      serviceName: process.env.SERVICE_NAME ?? "my-ai-service",
      serviceVersion: process.env.SERVICE_VERSION ?? "1.0.0",
    }),
  ],
});
await ldClient.waitForInitialization({ timeout: 10 });
const aiClient: LDAIClient = initAi(ldClient);
// Replace with the real user or session identifier (e.g. req.user.id, session.id).
// This key drives targeting rules, evaluation history, and trace attribution.
const currentUserId = process.env.USER_ID ?? "anonymous";
const context: LDContext = { kind: "user", key: currentUserId };

5. Evaluate the config

Current AI SDK

There is no separate evaluate step. config() takes the config key and your handlers, and invoke() evaluates the config, selects the provider, calls the model, and records metrics and spans in one call.

Python:

import os
from launchdarkly_ai_server import config
from launchdarkly_ai_openai_messages import create_openai_messages_handler
async def handle_call(user_input: str, current_user_id: str) -> str:
    try:
        result = await config(
            key=os.environ["LAUNCHDARKLY_AI_CONFIG_KEY"],
            handler=[create_openai_messages_handler()],
            # tool_handlers={"get-user-preferences": get_user_preferences},  # only if the variation defines tools
        ).invoke(
            user_input,
            {"kind": "user", "key": current_user_id},
            {"example_variable": "value"},                     # optional template variables, omit if unused
        )
    except Exception:
        # invoke() raises when the config is disabled, the key is wrong, or LaunchDarkly is
        # unreachable. Return the same hardcoded response the app used before LaunchDarkly.
        return "I'm sorry, this feature is temporarily unavailable."
    return result.response        # model output
    # result.usage               → normalized token counts
    # result.judge_results       → judge scores, when judges are attached to the variation

Node.js / TypeScript:

import { config } from "@launchdarkly/ai-node";
import { createOpenAIHandler } from "@launchdarkly/ai-openai-messages";
async function handleCall(userInput: string, currentUserId: string): Promise<string> {
  try {
    const result = await config({
      key: process.env.LAUNCHDARKLY_AI_CONFIG_KEY!,
      handler: [createOpenAIHandler()],
      // toolHandlers: { "get-user-preferences": getUserPreferences },  // only if the variation defines tools
    }).invoke(
      userInput,
      { kind: "user", key: currentUserId },
      { example_variable: "value" },                     // optional template variables, omit if unused
    );
    return result.response;
  } catch {
    // invoke() throws when the config is disabled, the key is wrong, or LaunchDarkly is unreachable.
    return "I'm sorry, this feature is temporarily unavailable.";
  }
}

The current AI SDK raises instead of returning enabled=False, and it has no default= argument. invoke() throws when the variation has targeting off, when the config key does not exist, or when it cannot reach LaunchDarkly, including during first-time setup before the SDK connects. Two rules follow from that. First, wrap every call path in try/except (or try/catch) that falls back to the exact response the app produced before LaunchDarkly was involved, so an outage cannot take the feature down. Second, if you need to branch on config state without raising, call inspect_config(key, context) in Python or inspectConfig(key, context) in Node.js, which returns {enabled, config, meta} and never raises.

Pass one handler per provider and mode the config might serve. When you pass a list, the SDK routes each call to the handler whose provider and mode match the resolved variation. A single handler that does not match the variation raises.

Tool keys in tool_handlers / toolHandlers must match the tool names on the config variation exactly, including case. A mismatch fails at runtime the moment the model requests the tool. If several call sites need the same handlers and tools, register them once in a Registry and pass registry= instead of repeating them. To learn more, read the registry section of the SDK reference for the language.

Each handler package also exports a single convenience function, for example openai_messages(config_key, user_input, context) in Python and openaiMessages(configKey, userInput, context) in Node.js, which wraps config(...).invoke(...) with that one handler pre-bound. Use it for the simplest single-provider case.

Legacy AI SDK

Each call returns a single config object. Get a tracker by calling tracker = config.create_tracker() (Python) or const tracker = config.createTracker() (Node.js). Call this once per request, after the enabled check, and use that same tracker for all metric calls in the request.

Always provide a default= value. Without one, the SDK returns enabled=False whenever LaunchDarkly is unreachable, including during first-time setup before the SDK connects. The default must duplicate the exact hardcoded values from the original code so behavior is identical during outages. ModelConfig, LDMessage, AICompletionConfigDefault, and AIAgentConfigDefault are imported in Step 4.

Agent mode (Python):

config = aiclient.agent_config(
    os.environ["LAUNCHDARKLY_AI_CONFIG_KEY"],
    context,
    default=AIAgentConfigDefault(
        enabled=True,
        model=ModelConfig(name="gpt-5.4"),          # ← your hardcoded model
        instructions="You are a helpful assistant.", # ← your hardcoded prompt
    ),
)
if not config.enabled:
    # config is explicitly disabled in the LaunchDarkly UI.
    return "I'm sorry, this feature is temporarily unavailable."
tracker = config.create_tracker()   # call once per request, after enabled check
# config.instructions    → system prompt / agent goal (str)
# config.model.name      → model identifier (str)
# tracker                → LDAIConfigTracker for metrics (see step 7)

Agent mode (Node.js):

const agentConfig = await aiClient.agentConfig(
  process.env.LAUNCHDARKLY_AI_CONFIG_KEY!,
  context,
  {                                    // default — mirrors your hardcoded values
    enabled: true,
    model: { name: "gpt-5.4" },
    instructions: "You are a helpful assistant.",
  },
);
if (!agentConfig.enabled) {
  // config is explicitly disabled in the LaunchDarkly UI.
  return "I'm sorry, this feature is temporarily unavailable.";
}
const tracker = agentConfig.createTracker();

Completion mode (Python):

config = aiclient.completion_config(
    os.environ["LAUNCHDARKLY_AI_CONFIG_KEY"],
    context,
    default=AICompletionConfigDefault(
        enabled=True,
        model=ModelConfig(name="gpt-5.4"),          # ← your hardcoded model
        messages=[
            LDMessage(role="system", content="You are a helpful assistant."),  # ← your hardcoded prompt
        ],
    ),
    variables={"example_variable": "value"},        # optional — omit if not using template variables
)
if not config.enabled:
    # config is explicitly disabled in the LaunchDarkly UI.
    return "I'm sorry, this feature is temporarily unavailable."
tracker = config.create_tracker()   # call once per request, after enabled check
# config.messages            → list[LDMessage] to pass to the model
# config.model.name          → model identifier
# tracker                    → LDAIConfigTracker for metrics

Completion mode (Node.js):

const aiConfig = await aiClient.completionConfig(
  process.env.LAUNCHDARKLY_AI_CONFIG_KEY!,
  context,
  {                                    // default — mirrors your hardcoded values
    enabled: true,
    model: { name: "gpt-5.4" },
    messages: [{ role: "system", content: "You are a helpful assistant." }],
  },
  { example_variable: "value" },       // optional template variables — omit if unused
);
if (!aiConfig.enabled) {
  // config is explicitly disabled in the LaunchDarkly UI.
  return "I'm sorry, this feature is temporarily unavailable.";
}
const tracker = aiConfig.createTracker();

6. Add the framework-specific handler

Current AI SDK: skip this step. The handler package is the framework integration. invoke() merges the config’s messages or instructions with the user input, calls the provider through its own SDK, and records metrics and spans. You only write code here if the provider has no handler package, in which case build one with create_handler(provides_for, fn) in Python or createHandler(providesFor, fn) in Node.js, as shown in the SDK reference. Everything below this line is legacy AI SDK code.

Read the integration guide fetched in step 1 for the exact handler. The snippets below are starting points only. Prefer the guide’s code.

Observability is automatic. The ObservabilityPlugin wired in during Step 4 auto-instruments OpenAI, LangChain, and other supported frameworks via OpenTelemetry. You do not need to add decorators or manual span code to get traces. For custom providers or unsupported frameworks, see NEXT STEP 4 for manual span creation.

Model name pattern: config.model can be None if the config variation has no model configured. Always provide a hard-coded fallback: model_name = config.model.name if config.model else "gpt-5.4". Choose the fallback that matches your stack (e.g. "claude-sonnet-4-6" for Anthropic, "o4-mini" for a cost-optimized OpenAI option).

OpenAI SDK, direct calls (Python):

from openai import OpenAI
from ldai_openai import get_ai_metrics_from_response
openai_client = OpenAI()
def handle_call(config, user_input: str):
    tracker = config.create_tracker()
    model_name = config.model.name if config.model else "gpt-5.4"
    # OpenAI spans are emitted automatically by the observability plugin — no decorator needed.
    return tracker.track_metrics_of(
        get_ai_metrics_from_response,
        lambda: openai_client.chat.completions.create(
            model=model_name,
            messages=[m.to_dict() for m in (config.messages or [])] + [{"role": "user", "content": user_input}],
        ),
    )

OpenAI SDK, direct calls (Node.js):

import { OpenAI } from "openai";
import { getAIMetricsFromResponse } from "@launchdarkly/server-sdk-ai-openai";
const openaiClient = new OpenAI();
async function handleCall(aiConfig: LDAICompletionConfig, userInput: string) {
  const tracker = aiConfig.createTracker();
  return tracker.trackMetricsOf(
    getAIMetricsFromResponse,
    async () => openaiClient.chat.completions.create({
      model: aiConfig.model?.name ?? "gpt-5.4",
      messages: [...(aiConfig.messages ?? []), { role: "user", content: userInput }],
    }),
  );
}

LangChain — agent mode (Python): (uses config.instructions — free-form agent goal)

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_community.callbacks import get_openai_callback
from ldai.tracker import TokenUsage
def handle_call(config, user_input: str) -> str:
    tracker = config.create_tracker()
    model_name = config.model.name if config.model else "gpt-5.4"
    llm = ChatOpenAI(model=model_name)
    messages = []
    if config.instructions:
        messages.append(SystemMessage(content=config.instructions))
    messages.append(HumanMessage(content=user_input))
    with get_openai_callback() as cb:
        response = llm.invoke(messages)
    tracker.track_tokens(TokenUsage(
        input=cb.prompt_tokens,
        output=cb.completion_tokens,
        total=cb.total_tokens,
    ))
    tracker.track_success()
    return response.content

LangChain — completion mode (Python): (uses config.messages — structured message list)

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
from langchain_community.callbacks import get_openai_callback
from ldai.tracker import TokenUsage
def handle_call(config, user_input: str) -> str:
    tracker = config.create_tracker()
    model_name = config.model.name if config.model else "gpt-5.4"
    llm = ChatOpenAI(model=model_name)
    # config.messages is a list[LDMessage] from the config variation
    lc_messages = []
    for m in (config.messages or []):
        if m.role == "system":
            lc_messages.append(SystemMessage(content=m.content))
        elif m.role == "assistant":
            lc_messages.append(AIMessage(content=m.content))
        else:
            lc_messages.append(HumanMessage(content=m.content))
    lc_messages.append(HumanMessage(content=user_input))
    with get_openai_callback() as cb:
        response = llm.invoke(lc_messages)
    tracker.track_tokens(TokenUsage(
        input=cb.prompt_tokens,
        output=cb.completion_tokens,
        total=cb.total_tokens,
    ))
    tracker.track_success()
    return response.content

OpenAI Agents SDK (Python):

from agents import Agent
from agents.run import Runner
async def handle_call(config, user_input: str) -> str:
    tracker = config.create_tracker()
    model_name = config.model.name if config.model else "gpt-5.4"
    agent = Agent(name="assistant", instructions=config.instructions or "", model=model_name)
    result = await Runner.run(agent, user_input)
    tracker.track_success()
    return result.final_output

Strands (Python):

from strands import Agent
from strands.models.openai import OpenAIModel
async def handle_call(config, user_input: str) -> str:
    tracker = config.create_tracker()
    model_name = config.model.name if config.model else "gpt-5.4"
    openai_model = OpenAIModel(model_id=model_name)
    agent = Agent(system_prompt=config.instructions or "", model=openai_model, callback_handler=None)
    result = str(agent(user_input))
    tracker.track_success()
    return result

Claude Agent SDK (Python):

from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import ResultMessage
async def handle_call(config, user_input: str) -> str:
    tracker = config.create_tracker()
    model_name = config.model.name if config.model else "claude-sonnet-4-6"
    final_message = None
    async for message in query(
        prompt=user_input,
        options=ClaudeAgentOptions(system_prompt=config.instructions or "", model=model_name),
    ):
        final_message = message
    if not isinstance(final_message, ResultMessage):
        raise ValueError(f"Unexpected message type: {type(final_message)}")
    tracker.track_success()
    return final_message.result or ""

For Node.js non-OpenAI frameworks, refer to: https://launchdarkly.com/docs/sdk/observability/node-js

7. Track metrics and token usage

Current AI SDK: skip this step. There is no tracker. invoke() and stream() record duration, token counts, success and error, and the OpenTelemetry span for every call. Do not write create_tracker(), track_success(), track_tokens(), or track_metrics_of() against the current AI SDK; those functions do not exist there. The rest of this step is legacy AI SDK code.

tracker = config.create_tracker() (Python) / const tracker = config.createTracker() (Node.js) must record every call outcome. This is what populates the AgentControl Monitoring tab. Create the tracker once per request, after the enabled check.

Python, modern API for OpenAI (preferred):

from ldai_openai import get_ai_metrics_from_response
tracker = config.create_tracker()
response = tracker.track_metrics_of(
    get_ai_metrics_from_response,
    lambda: openai_client.chat.completions.create(model=..., messages=...),
)

Note: tracker.track_metrics_of(extractor, fn) runs the call, applies the extractor to its response, and records duration, tokens, and success/error in one shot. Every provider goes through track_metrics_of with the appropriate extractor — get_ai_metrics_from_response from ldai_openai for OpenAI, or a small custom extractor for Anthropic, Bedrock, Gemini, and others. See NEXT STEP 11 for extractor examples covering Anthropic, Bedrock, and Gemini.

Python, manual tracking for other frameworks:

from ldai.tracker import TokenUsage
tracker = config.create_tracker()
try:
    result = handle_call(config, user_input)        # handler must call tracker.track_success() internally
    # Optionally add token tracking if the framework exposes usage:
    # tracker.track_tokens(TokenUsage(
    #     input=usage.prompt_tokens,
    #     output=usage.completion_tokens,
    #     total=usage.total_tokens,
    # ))
except Exception:
    tracker.track_error()
    raise

Note: track_tokens takes a TokenUsage dataclass (from ldai.tracker import TokenUsage), not a plain dict.

Node.js, recommended shortcut for OpenAI (auto-tracks everything):

import { getAIMetricsFromResponse } from "@launchdarkly/server-sdk-ai-openai";
const tracker = aiConfig.createTracker();
const response = await tracker.trackMetricsOf(
  getAIMetricsFromResponse,
  async () => openaiClient.chat.completions.create({ model: ..., messages: ... }),
);

Node.js, manual tracking for other frameworks:

const tracker = aiConfig.createTracker();
try {
  const result = await runAgent(agentConfig, userInput);
  tracker.trackTokens({ input: 0, output: 0, total: 0 });  // fill in from your framework
  tracker.trackSuccess();
} catch (e) {
  tracker.trackError();
  throw e;
}

LangChain always exposes token counts via get_openai_callback() — always wrap LangChain calls in that context manager and call tracker.track_tokens() (see the LangChain snippets above). tracker.track_success() alone does not send token data; cost and token metrics in the Monitoring dashboard derive entirely from track_tokens(). For frameworks that genuinely do not expose token counts, omit track_tokens / trackTokens — success/error tracking alone is sufficient to populate request count and error rate.

8. Implementation rules

Both generations:

• Read credentials from environment variables. Never hardcode SDK keys or API keys.
• Never cache a resolved config across requests. Evaluate or invoke once per request so targeting and variation changes take effect immediately
• Keep a hardcoded fallback response on every AI call path, so the feature degrades rather than fails when LaunchDarkly is unreachable
• Do not mix the two AI SDK generations in one call path

Current AI SDK:

• Set LD_SDK_KEY; the SDK reads the key from the environment and nowhere else unless you pass sdkKey in options
• Pin the core package and every handler package to exact 0.x versions, all on the same minor version
• Wrap every invoke() in try/except or try/catch; it raises on disabled configs, unknown keys, and connection failures, and there is no default=
• Register one handler per provider and mode the config can serve, or register a wildcard LangChain handler as the fallback
• Do not add a tracker, an observability plugin, or manual spans; metrics and traces are automatic
• Call shutdown() on process exit so events and spans flush
• Python only. Every call is awaited, and call sites must be async.

Legacy AI SDK:

• Initialize the LaunchDarkly client once at startup, before any agent or model calls
• Always include the observability plugin in the Config/init call, because traces do not appear without it
• Call agent_config() / completion_config() (Python) or agentConfig() / completionConfig() (Node.js) once per request, and never cache the returned config across requests
• Python: Call tracker = config.create_tracker() once per request, after the enabled check, to get the tracker.
• Node.js: Call const tracker = config.createTracker() once per request to get a fresh tracker.
• The observability plugin emits traces automatically, and standard frameworks such as OpenAI and LangChain need no @observe decorator or manual span code
• Always provide a default= argument to completion_config() / agent_config(). Without one, the SDK returns enabled=False when LaunchDarkly is unreachable, including during first-time setup
• Always provide a fallback model name in case config.model is None
• Always call tracker.track_success() or tracker.track_error() after every AI call (or use tracker.track_metrics_of(extractor, fn) / tracker.trackMetricsOf(extractor, fn) which handle this automatically)

VERIFICATION

After implementation:

1. Run the application and trigger at least one AI call through the integrated path
2. Check the LaunchDarkly UI. The in-app onboarding shows Connected after the SDK evaluates the config
3. Check the Observability tab. Traces should appear within 1 to 2 minutes of the first call, from the observability plugin on the legacy AI SDK or from the SDK’s own spans on the current AI SDK
4. Check the AgentControl Monitoring tab. Token usage, latency, and success and error rates appear within 1 to 2 minutes of the first tracked call

Set the user’s expectations on data delay. Tell the user up front: “After your first AI call, the Connected state usually flips within seconds, but monitoring data, traces, and judge scores typically take 1–2 minutes to appear in their respective tabs, and sometimes a bit longer. If a tab looks empty right after a call, refresh after a minute or two before troubleshooting.” Saying this once at verification time prevents the very common “I made a call but the page is empty, what’s wrong?” cycle.

Troubleshooting checklist:

WHAT’S NEXT

Once the user confirms “Connected” appears in the LaunchDarkly UI:

Step 1 — Acknowledge and direct them to the Monitoring tab:

“Your SDK is connected — nice work. Before we go further, head over to your config → Monitoring tab. After a minute or two of AI calls flowing through, you’ll start seeing token usage, latency, and request counts broken down by variation. Make a few AI calls if you haven’t already, give it a moment, and refresh the page. This is where you’ll track the real cost and performance impact of every prompt and model change you make.”

Step 2 — Present the next-steps menu:

If the user came from Phase 1 (existing app integration), lead with option 11 — completing the full migration is the highest-value next step for them. If they used the sample app path, option 11 is not yet relevant; start from option 1.

Say:

“You just experienced the core value of AgentControl: you changed a prompt or model in the LaunchDarkly UI and your running app picked it up immediately — no redeploy needed. That’s the foundation. Here’s what to explore next:”

Then present the following menu with each section clearly separated — never run items together into a single paragraph:

If you have more hardcoded prompts or models to extract:

11. Complete the migration — extract every remaining hardcoded prompt, model, parameter, and tool into configs in five structured stages

Core next steps

1. Invite your team — give teammates access to edit prompts and models in the LaunchDarkly UI, no code needed
2. Add a judge — automatically score every AI response for accuracy, relevance, and toxicity
3. Run your first eval. Test prompt variations against each other before going to production
4. Review your monitoring data. Token costs, latency, and error rates on the Monitoring tab
5. Log traces. Full request traces linked to config evaluations in the Observability tab
6. Explore more SDK features. Streaming, structured output, registries, and, for legacy AI SDK users, moving to the current AI SDK

Advanced topics

7. Agent graphs — orchestrate multi-agent workflows, defined via the AgentControl MCP or the LaunchDarkly UI
8. Run an experiment — A/B test prompt or model variations against real user behavior metrics
9. Guarded rollouts — automatically pause or roll back a model change if quality scores drop
10. Governance and approvals — require review before any config change reaches production

Ask: “Which would you like to explore?”

Wait for the user to choose. Then follow the guidance for that topic below. Read the referenced docs URL before writing any code or describing UI steps.

After completing any topic, re-offer the menu. Acknowledge what they just accomplished, note which steps they’ve done, and suggest the most logical next step — guide them progressively toward the full product rather than just dumping the entire list again.

NEXT STEP 1: Invite your team

What this unlocks: Once your config is running, anyone on your team — product managers, ML engineers, or other developers — can edit prompts, swap models, and update parameters directly in the LaunchDarkly UI. No code changes or redeployment required. This is one of the core value propositions of AgentControl: separating model configuration from application code so the people closest to the product can iterate on their own.

Docs: https://docs.launchdarkly.com/home/account/members

Prefer MCP when connected. The Feature Management MCP exposes invite-members — invite teammates from the agent in one call instead of asking the user to switch to the UI. Confirm the role with the user first if it’s not obvious from context.

invite-members:
  emails: ["alice@example.com", "bob@example.com"]
  role: "writer"      # or "reader" / "admin"

UI fallback (use only if MCP is not connected):

1. Go to Account settings → Members.
2. Click Invite members.
3. Enter one or more email addresses.
4. Assign a role:
   • Writer — can create and edit configs, variations, targeting rules, and tools. Recommended for anyone who will manage prompts or models.
   • Reader — view-only access. Good for stakeholders who want to review monitoring data without making changes.
   • Admin — full account access, including environment and project settings.
5. Click Send invite. Recipients get an email link to join the LaunchDarkly account.

What to tell teammates once they’re in:

• Open the config → Variations tab → edit the system prompt or swap the model → Review and save. The change goes live immediately — no deployment needed.
• Use the LLM Playground (top right of the Variations tab) to compare prompt or model options side-by-side before committing.
• Check the Monitoring tab for real-time token costs, latency, and error rates broken down by variation.

Custom roles (Enterprise): custom roles let you grant fine-grained permissions — for example, write access to configs only, scoped to specific projects or environments, without touching feature flags. Contact your LaunchDarkly admin to configure this. See: https://docs.launchdarkly.com/home/account/role-create

NEXT STEP 2: Add a judge

What this unlocks: Every AI response is automatically scored (0.0–1.0) for Accuracy, Relevance, and Toxicity. Scores appear on the Monitoring tab and can trigger guarded rollout pauses.

Docs: https://docs.launchdarkly.com/home/ai-configs/online-evaluations

On the current AI SDK, attaching a judge to the variation is the whole job. Judges attached to a variation in LaunchDarkly run inline on every invoke() and come back on result.judge_results. No judge code is needed at the call site. If the added latency matters, pass skip_judges=True / skipJudges: true, then hand each task from result.judge_tasks to a background worker that calls run_judge(task, handlers) / runJudge(task, handlers). The code below is for the legacy AI SDK.

Tailor by mode detected in Phase 1:

If completion mode, attach a judge to a variation

Prefer MCP when connected. Pass judgeConfiguration to update-ai-config-variation (or create-ai-config-variation for a new variation) to attach judges programmatically — keep the user in the agent context. Confirm the sampling rate with the user first; 10–20% is a reasonable starting default to control cost.

update-ai-config-variation:
  projectKey: "my-project"
  configKey: "chat-assistant"
  variationKey: "production-initial"
  judgeConfiguration:
    judges:
      - key: "accuracy"
        sampling: 0.20
      - key: "relevance"
        sampling: 0.20
      - key: "toxicity"
        sampling: 0.20

UI fallback (use only if MCP is not connected or judgeConfiguration isn’t in the live tool schema):

1. Open your config → Variations tab → click into a variation.
2. In the Judges section, click + Attach judges.
3. Select Accuracy, Relevance, and/or Toxicity. Start at 10–20% sampling to control cost.
4. Click Review and save.

Then update the call site to await evaluation results:

Python, create_model pattern (recommended for completion mode):

import asyncio
model = await aiclient.create_model(
    os.environ["LAUNCHDARKLY_AI_CONFIG_KEY"],
    context,
)
if not model:
    print("config disabled or unreachable — using fallback")
    # return fallback here
else:
    response = await model.run(user_input)
    print("Response:", response.content)
    # Await judge evaluations before the request ends
    if response.evaluations:
        results = await asyncio.gather(*response.evaluations)
        for r in results:
            print("Judge result:", r.to_dict())

Node.js sample: js-core/packages/sdk/server-ai/examples/chat-judge

If agent mode, invoke a judge directly in code

Agent-mode variations cannot have judges attached in the UI. Use programmatic evaluation:

1. Create a judge config in LaunchDarkly. If MCP is connected, use setup-ai-config with a judge mode and a built-in or custom judge — do this from the agent rather than sending the user to the UI. If MCP is not available, walk the user through AgentControl → Create → choose a built-in judge or custom in the UI.
2. Add its key to your environment: LAUNCHDARKLY_AI_JUDGE_KEY=your-judge-key (use the SDK key consent flow from Phase 2 Step 3 before writing it).

Python:

from ldai import AICompletionConfigDefault
judge = await aiclient.create_judge(
    os.environ["LAUNCHDARKLY_AI_JUDGE_KEY"],
    context,
    AICompletionConfigDefault(enabled=False),
)
if judge and judge.enabled:
    result = await judge.evaluate(user_input, agent_response)
    print("Judge score:", result.to_dict())
    # Optionally link the score to your agent's config tracker:
    # tracker.track_judge_result(result)  # tracker = config.create_tracker()

Check the Monitoring tab for judge results

Once the judge is wired up and a few requests have been scored, direct the user here. Set the delay expectation explicitly — this is the most common point of confusion in onboarding:

“Now head over to your config → Monitoring tab. Scroll down to the User satisfaction section — that’s where judge scores (accuracy, relevance, toxicity) appear as they accumulate. Heads up: judge scores are not instant. Expect a 1–2 minute delay (sometimes a bit more for the very first scores) between making the AI call and seeing the score on this tab. If you don’t see anything yet, that’s almost always the answer — wait a minute or two, refresh the page, and the scores will appear. Once you have data, you can see how scores differ across variations — that’s what makes guarded rollouts and experiments meaningful.”

NEXT STEP 3: Run your first eval

What this unlocks: Compare prompt or model variations against known inputs before they go live. The LLM Playground lets you test side-by-side in the browser; offline evals let you run repeatable tests against a dataset.

Docs: https://docs.launchdarkly.com/home/ai-configs/offline-evaluations
Playground: https://docs.launchdarkly.com/home/ai-configs/playground
Datasets: https://docs.launchdarkly.com/home/ai-configs/datasets

Prefer MCP for setup. Datasets, evaluations, and playgrounds all have MCP tool coverage. The agent can create the dataset, set up the evaluation, run it, and report the summary back without ever leaving the chat:

# 1. Create a dataset of inputs (and optional expected outputs)
create-dataset:
  projectKey: "my-project"
  key: "qa-baseline"
  rows:
    - input: "What is feature flagging?"
      expected: "..."
    - input: "How does a canary deployment work?"
      expected: "..."
# 2. Create an evaluation that ties the dataset to one or more config variations
create-evaluation:
  projectKey: "my-project"
  key: "v1-vs-v2"
  datasetKey: "qa-baseline"
  configKey: "chat-assistant"
  variationKeys: ["production-initial", "shorter-prompt"]
  judges: ["accuracy", "relevance"]
# 3. Run it and fetch the summary when it's done
run-evaluation:
  projectKey: "my-project"
  evaluationKey: "v1-vs-v2"
get-evaluation-run-summary:
  projectKey: "my-project"
  evaluationKey: "v1-vs-v2"
  runId: "...returned by run-evaluation..."

For interactive side-by-side comparison (the LLM Playground UI experience), still use the browser — but the underlying playground objects can be created and updated via create-playground / update-playground so the agent can pre-populate them.

UI fallback (use only if the corresponding MCP tools aren’t listed):

1. Open your config → click LLM Playground (top right of the Variations tab).
2. Add a second variation (different model or prompt wording).
3. Enter a test input and compare responses side-by-side.
4. For repeatable batch testing: go to Configs → Datasets → New dataset, upload input/output pairs, then run an offline evaluation from the Playground.

For programmatic evaluation in CI (when you want the eval to run as part of your build):

judge = await aiclient.create_judge(
    os.environ["LAUNCHDARKLY_AI_JUDGE_KEY"],
    context,
    AICompletionConfigDefault(enabled=False),
)
test_cases = [
    ("What is feature flagging?", expected_answer_1),
    ("How does a canary deployment work?", expected_answer_2),
]
for input_text, expected in test_cases:
    actual = your_model_call(input_text)
    if judge and judge.enabled:
        result = await judge.evaluate(input_text, actual)
        print(f"Score: {result.to_dict()}")

Python sample: poetry run direct-judge-example in hello-python-ai

NEXT STEP 4: Review your monitoring data

What this unlocks: The Monitoring tab shows tokens consumed, cost, latency (P50/P95/P99), error rate, and user satisfaction — per variation — so you can compare the real cost and performance of different prompts and models.

Docs: https://docs.launchdarkly.com/home/ai-configs/monitor

In the LaunchDarkly UI:

1. Open your config → click the Monitoring tab.
2. Explore the variation-level breakdown if charts already appear, because that means data is flowing.
3. Expect an empty state, or “Waiting for data”, immediately after the first call. Monitoring data, traces, and judge scores typically take 1 to 2 minutes to appear, and sometimes a bit longer for the very first batch. Wait a couple of minutes, then refresh. The data should populate. Tell the user this delay is normal before they start troubleshooting.
4. Check the tracking calls if nothing appears after a few minutes. On the legacy AI SDK, confirm track_success() / track_error() runs after each AI call, as described in Phase 2, Step 7. On the current AI SDK, confirm at least one invoke() returned without raising, because the SDK records metrics per invoke.

On the current AI SDK, token counts, latency, and success and error rates are recorded on every call with no tracker involved. Feedback is the one signal that is still explicit, and the tracker-based API below belongs to the legacy AI SDK.

On the legacy AI SDK, if track_metrics_of (Python) or trackMetricsOf (Node.js) is used (from Step 6/7 of Phase 2), token data flows automatically. To add user satisfaction signals:

Python, same-request feedback (thumbs up/down in the response):

from ldai.tracker import FeedbackKind
# tracker was obtained via tracker = config.create_tracker() earlier in the request
tracker.track_feedback({"kind": FeedbackKind.Positive})   # thumbs up
tracker.track_feedback({"kind": FeedbackKind.Negative})   # thumbs down

Python, async feedback that arrives in a later request:

At generation time, save the resumption token alongside the response:

# At generation time — serialize and return alongside the response
token = tracker.resumption_token
response_payload = {"text": response_text, "ld_token": token}

When feedback arrives later (separate request, separate process):

result = aiclient.create_tracker(token, context)
if result.is_success():
    late_tracker = result.value
    late_tracker.track_feedback({"kind": FeedbackKind.Positive})

Node.js:

tracker.trackFeedback({ kind: LDFeedbackKind.Positive });
// For async feedback: use tracker.resumptionToken and aiClient.createTracker(token, context)

NEXT STEP 5: Log traces

What this unlocks: Full distributed traces visible in the Observability tab, showing every span in the request with timing, model inputs/outputs, and tool calls — automatically linked to which config variation was served.

Docs: https://docs.launchdarkly.com/home/ai-configs/manual-llm-span-tracing
Python reference: https://docs.launchdarkly.com/sdk/observability/python

On the current AI SDK, spans follow the OpenTelemetry Gen AI semantic conventions and are emitted on every call, as long as the trace dependencies are installed: the otel extra on launchdarkly-ai-server, or @launchdarkly/ai-otel. There is no plugin to wire and no span to open by hand. LD_SERVICE_NAME and LD_ENVIRONMENT label the traces.

On the legacy AI SDK, if the observability plugin is already wired into the SDK init (Phase 2, Step 4), traces are emitting automatically for standard frameworks (OpenAI, LangChain, etc.). To verify:

1. Run the app and trigger an AI call.
2. Open Observability in the LaunchDarkly left sidebar, then open the Traces tab.
3. Traces appear within 1–2 minutes. If nothing appears after several calls, confirm the ObservabilityPlugin is in the plugins array at init.

If you need to create a manual span (custom provider, unsupported framework, or to group multiple calls under one named trace):

from ldobserve import observe  # observe is a module singleton, not a decorator
with observe.start_span("my-agent-call") as span:
    # all AI SDK calls inside this block are linked to this span
    tracker = config.create_tracker()
    result = my_model_call(config, user_input)
    tracker.track_success()

If you need to annotate a span with custom LLM attributes (for custom providers):

from ldobserve import observe
from opentelemetry import trace
with observe.start_span("custom-llm-call") as span:
    span.set_attribute("gen_ai.request.model", "my-model")
    span.set_attribute("gen_ai.system", "my-provider")
    result = my_custom_llm(prompt)
    span.set_attribute("gen_ai.response.finish_reasons", ["stop"])

NEXT STEP 6: Explore more SDK features

What this unlocks: Less boilerplate on every AI call, plus streaming, structured output, and shared registries.

Current AI SDK: https://docs.launchdarkly.com/sdk/ai/python and https://docs.launchdarkly.com/sdk/ai/node-js
Legacy AI SDK: https://docs.launchdarkly.com/sdk/ai/python-legacy and https://docs.launchdarkly.com/sdk/ai/node-js-legacy
Migration guide: https://docs.launchdarkly.com/sdk/ai/migration

Tailor by which SDK they ended up on:

If they are on the current AI SDK, point them at the features they have not used yet, all documented in the reference above:

• stream() for token-by-token responses, which returns chunk events followed by a done event carrying the full response, usage, and judge results. Streaming and structured output are mutually exclusive.
• Structured output, which you set on the config in the LaunchDarkly UI. When an output format is set, invoke() returns a parsed object as response rather than a string.
• A Registry for handlers and tools, so call sites stop repeating them. Scoped registries are preferred over global_registry because each call site then exposes only the handlers and tools it needs.
• Provider built-in tools, such as Claude’s web search, assigned to a LaunchDarkly tool key so provider-native capabilities still show up in tool-call tracking.
• graph() for multi-agent workflows, covered in NEXT STEP 7.

If they are on the legacy AI SDK, the highest-value next step is moving to the current AI SDK, which is where new features now land. It is not a drop-in replacement: packages, initialization, model calls, tool wiring, and metrics all change, and the current SDKs are in open beta at 0.2.x. Walk them through https://docs.launchdarkly.com/sdk/ai/migration, and start with one call site rather than the whole app. The legacy SDK is in maintenance mode, so there is no deadline; frame it as a choice, not a forced move.

Legacy AI SDK features they may not be using yet, if they want to stay put for now:

If they are using low-level completion_config + manual model calls → show create_model:

Python, create_model (auto-tracks tokens, duration, success):

model = await aiclient.create_model(
    os.environ["LAUNCHDARKLY_AI_CONFIG_KEY"],
    context,
    variables={"username": "Sandy"},
)
if not model:
    # disabled or LD unreachable — return a hard-coded fallback
    return "I'm sorry, this feature is temporarily unavailable."
response = await model.run("Hello, how can you help me?")
print(response.content)
# Token usage, latency, and success tracked automatically — no tracker calls needed

Python, retrieve multiple agent configs at once:

from ldai import AIAgentConfigRequest, AIAgentConfigDefault
agents = aiclient.agent_configs([
    AIAgentConfigRequest(key="summarizer-agent", default=AIAgentConfigDefault(enabled=False)),
    AIAgentConfigRequest(key="validator-agent",  default=AIAgentConfigDefault(enabled=False)),
], context)
summarizer = agents["summarizer-agent"]
validator  = agents["validator-agent"]

Reuse common prompt fragments with prompt snippets

If the user has the same persona, guardrails, or formatting instructions repeated across multiple configs, prompt snippets let them define the shared text once and reference it from any variation. When the snippet is updated, every variation that references it picks up the change.

Manage snippets via MCP when connected:

create-prompt-snippet:
  projectKey: "my-project"
  key: "company-tone"
  name: "Company tone"
  content: "Respond in a friendly, professional voice. Avoid jargon. Use plural 'we' when describing the company."
list-prompt-snippets / get-prompt-snippet / update-prompt-snippet / delete-prompt-snippet
  # for the rest of the lifecycle

Then reference the snippet inside a variation’s messages or instructions so every config that needs that tone shares a single source. This pairs well with the migration stages below: when the audit reveals duplicate prompt fragments across call sites, extract them into snippets instead of copying the same string into each variation.

NEXT STEP 7: Agent graphs (advanced)

What this unlocks: Define the topology of a multi-agent system — which agents hand off to which, and what data is passed. Change agent routing without touching code.

Docs: https://docs.launchdarkly.com/home/ai-configs/agent-graphs
Node.js example: js-core/packages/sdk/server-ai/examples/agent-graph-traversal

Prerequisites: Two or more agent-mode configs already created in LaunchDarkly.

On the current AI SDK, graphs have first-class functions. Call graph(key, handlers=[...]).invoke(input, context, variables) in Python, or graph(key, { handlers: [...] }).invoke(...) in Node.js, to run a graph on the SDK’s model-driven router, which presents each node’s outgoing edges to the model as handoff choices and stops on a final answer, a leaf node, a cycle, or the step cap. Every node emits its own telemetry and runs its own judges. Pass a judge config key as graph_judge / graphJudge to score the graph’s final answer. To hand the topology to a provider’s own runner instead, resolve it with resolve_graph() / resolveGraph() and pass the result to to_openai_agents, to_lang_graph, or to_claude_agents from the matching handler package. The traversal helpers further down this section are for the legacy AI SDK.

Prefer MCP when connected. Agent graphs have full create, read, update, and delete coverage in the AgentControl MCP. The agent can construct the graph, set the root node, draw the edges, and return the graph key without sending the user to the UI:

create-agent-graph:
  projectKey: "my-project"
  key: "support-triage"
  name: "Support triage"
  rootNodeKey: "router-agent"
  nodes:
    - key: "router-agent"
      configKey: "router-agent-config"
    - key: "billing-agent"
      configKey: "billing-agent-config"
    - key: "tech-agent"
      configKey: "tech-agent-config"
  edges:
    - from: "router-agent"
      to: "billing-agent"
    - from: "router-agent"
      to: "tech-agent"

Use list-agent-graphs, get-agent-graph, update-agent-graph, and delete-agent-graph for the rest of the lifecycle.

UI fallback (use only if MCP isn’t available):

1. Left sidebar → Configs → Agent graphs → Create agent graph.
2. Add your agent configs as nodes. Assign one as the root.
3. Draw directed edges between nodes to define handoff order and optional handoff data.
4. Save and note the graph key.

Python, retrieve and traverse the graph:

graph = aiclient.agent_graph(
    os.environ["LAUNCHDARKLY_GRAPH_KEY"],
    context,
)
def build_agent(node, execution_context):
    cfg = node.get_config()
    model_name = cfg.model.name if cfg.model else "gpt-5.4"
    return your_framework.Agent(
        name=node.get_key(),
        instructions=cfg.instructions or "",
        model=model_name,
    )
# Forward: root → leaf (use when framework builds parents before children)
graph.traverse(build_agent)
# Reverse: leaf → root (use when framework builds children before parents, e.g. LangGraph)
graph.reverse_traverse(build_agent)

NEXT STEP 8: Run an experiment (advanced)

What this unlocks: Statistically validate that one prompt or model variation actually improves user behavior (clicks, conversions, task completions) compared to another — not just internal quality scores.

Docs: https://docs.launchdarkly.com/home/ai-configs/experimentation
Experimentation reference: https://docs.launchdarkly.com/home/experimentation

Step 1 — Add a second variation (use create-ai-config-variation MCP, or Variations tab → + Add variation in the UI). Try a different model (e.g. o4-mini vs gpt-5.4 for a cost/quality tradeoff) or a shorter/longer prompt.

Step 2 — Instrument a user-behavior metric in code:

# Track a signal that shows the AI response was useful
ldclient.get().track("task-completed", context, metric_value=1)

Step 3 — Configure and start the experiment. Prefer MCP when connected:

create-experiment:
  projectKey: "my-project"
  key: "shorter-prompt-test"
  configKey: "chat-assistant"
  variationKeys: ["production-initial", "shorter-prompt"]
  metricKeys: ["task-completed"]
  primaryMetricKey: "task-completed"
start-experiment-iteration:
  projectKey: "my-project"
  experimentKey: "shorter-prompt-test"

Use list-experiments, get-experiment, and update-experiment to inspect or adjust an experiment. Results appear on the Experimentation tab as traffic accumulates.

UI fallback (use only if the experiment MCP tools aren’t listed):

1. Go to your config → Targeting tab.
2. Set up a 50/50 percentage rollout between your two variations.
3. Click Review and save → select Start experiment.
4. Choose your metric(s) and set the primary goal.

Note: Guarded rollouts and experiments cannot run simultaneously on the same config. Use a guarded rollout to protect against quality regressions; use an experiment to measure user-facing impact.

NEXT STEP 9: Guarded rollouts (advanced)

What this unlocks: When rolling out a new prompt or model, LaunchDarkly monitors your quality metrics in real time. If accuracy or relevance drops, the rollout pauses automatically before all users are affected.

Docs: https://docs.launchdarkly.com/home/releases/guarded-rollouts
Targeting reference: https://docs.launchdarkly.com/home/ai-configs/target

Prerequisites: A judge attached to your config (NEXT STEP 2) so there are quality metrics to monitor.

Prefer MCP when connected. start-guarded-rollout configures the V2 measured rollout on the fallthrough rule in one call — pick the new variation, the metrics to monitor, the rollback thresholds, and start. stop-guarded-rollout ends it.

start-guarded-rollout:
  projectKey: "my-project"
  flagKey: "chat-assistant"
  env: "production"
  newVariationKey: "shorter-prompt"
  monitorMetrics: ["accuracy", "relevance"]
  rollbackOnRegression: true

UI fallback (use only if MCP isn’t available):

1. Go to your config → Targeting tab.
2. Update the default rule to serve your new variation to an initial percentage of users (e.g., 10%).
3. Click Review and save → in the confirmation modal, select Guarded rollout.
4. Choose the metrics to monitor (judge scores work well here).
5. Set rollback thresholds and enable automatic rollback.
6. Start the rollout.

LaunchDarkly progressively increases traffic and monitors. If a regression is detected it pauses and sends a notification. No code changes are required.

NEXT STEP 10: Governance and approvals (advanced)

What this unlocks: No prompt or model change can reach production without explicit approval from a designated reviewer — preventing unauthorized or accidental changes to AI behavior in production.

Docs: https://docs.launchdarkly.com/home/releases/approval-config
Configs management: https://docs.launchdarkly.com/home/ai-configs/manage

In the LaunchDarkly UI:

1. Go to Account settings → Projects → select your project → select your production environment.
2. Under Approval settings, enable approvals for config changes.
3. Set the minimum number of approvals required and (optionally) restrict who can approve.

Once configured, any variation or targeting change in that environment shows Request approval instead of Review and save. The change is queued until approved.

No code changes are needed. The SDK always evaluates whatever variation is in the current approved state.

NEXT STEP 11: Complete the migration (existing-app users)

What this unlocks: Every hardcoded model name, prompt, parameter, and tool in the existing codebase becomes live config — editable in the LaunchDarkly UI, A/B testable, and guarded by rollout policies — without changing runtime behavior.

Migration guide: https://docs.launchdarkly.com/guides/ai-configs/migrate-prompts

This is a different migration from the SDK one. These five stages move hardcoded prompts and models out of the user’s code and into AgentControl configs. Moving from the legacy AI SDK to the current AI SDK is a separate piece of work, covered at https://docs.launchdarkly.com/sdk/ai/migration. Do not run both at once. The stage code below is written for the legacy AI SDK; on the current AI SDK the audit and inventory stages are identical, while the wiring stages collapse into config(...).invoke(...) calls with no tracker.

The migration runs in five ordered stages. Each stage is independently deployable. Read the full guide before starting.

Stage 1: Audit — find everything hardcoded

Scan the codebase and build an inventory. Do not write code in this stage. For every hit, record file, line range, and current value:

• Model name literals: model="gpt-5.4", model="claude-sonnet-4-6", modelId="anthropic.claude-sonnet-4-6", etc.
• Model parameters: temperature, max_tokens, top_p, max_completion_tokens
• System prompts / instructions: full text of strings passed to system=, systemPrompt:, instructions=, or the first {"role": "system", ...} in a messages array
• Tool definitions: arguments to tools=[...], bind_tools(...), ToolNode(...) — flag each one
• Template placeholders: .format(), f-strings, JS template literals, %(var)s, str.replace("__VAR__", ...) — note each placeholder name, they become {{ variable }} in the config
• Repeated prompt fragments: identical chunks of system prompt or instructions that appear in 2+ call sites — note these for extraction into prompt snippets (one shared fragment, referenced from many variations) in Stage 2.

Also confirm:

• Does the app already initialize an LDClient for feature flags? If yes, reuse it — pass it to LDAIClient() / initAi() instead of creating a second one.
• Which config mode (completion or agent) matches how each call site works?

Output of this stage: a short audit manifest listing every hardcoded value and its location, plus a list of duplicate fragments to lift into snippets.

Stage 2: Wrap with identical fallback

For each call site in the manifest, create the config in LaunchDarkly (automated or manual), then update the code.

Prefer Option A (MCP) when MCP is connected — it keeps the user in the agent context and scales to dozens of call sites without manual UI work, which is the common case during a migration. Fall back to Option B (UI) only when MCP is unavailable or fails.

Option A — LaunchDarkly MCP (preferred when connected)

Use setup-ai-config with the exact values from your audit manifest. The messages/instructions/parameters fields are all optional — include only what you found hardcoded:

setup-ai-config:
  projectKey: "my-project"
  key: "chat-assistant"                      ← from audit manifest
  name: "Chat Assistant"
  mode: "completion"                         ← or "agent"
  variationKey: "production-initial"
  variationName: "Production (initial)"
  modelConfigKey: "OpenAI.gpt-5.4"           ← Provider.model-id format
  modelName: "gpt-5.4"
  messages:
    - role: "system"
      content: "You are a helpful assistant."  ← exact hardcoded value
  parameters:
    temperature: 0.7
    max_tokens: 2000

Then set the default targeting rule with update-rollout: