Index of every page on this site: llms.txt
All skills
launchdarkly avatar

/legacy-sdk-migrate

@f0ee110 official
Run it yourself

Migrate an app from the legacy LaunchDarkly AI SDKs (Python `launchdarkly-server-sdk-ai` / `ldai`, Node.js `@launchdarkly/server-sdk-ai`, Go `go-server-sdk-ai/ldai` or `go-server-sdk/ldai`) to the current handler-based AI SDKs (`launchdarkly-ai-server`, `@launchdarkly/ai-node` / `@launchdarkly/ai-server`, `github.com/launchdarkly/go-ai-sdk` plus handlers). Use when code calls `LDAIClient`, `initAi`, `ldai.NewClient`, `CompletionConfig`, `AgentConfig`, `AgentGraph`, `CreateTracker`, `completion_config` / `completionConfig`, `agent_config` / `agentConfig`, `agent_configs`, `create_tracker` / `trackMetricsOf`, `create_judge`, `create_model`, or `agent_graph`, or when the user asks to upgrade between LaunchDarkly AI SDKs. For apps with hardcoded LLM prompts that aren't on LaunchDarkly yet, use `migrate` instead.

Use this Skill: https://skilld.dev/gh/launchdarkly/ai-tooling/legacy-sdk-migrate

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesapi-mapping.md

≈6.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Legacy to current AI SDK: before and after

For Go, use go-api-mapping.md instead; Go's signatures, errors, registry, and lifecycle differ from the examples here.

Each section shows the legacy pattern and its replacement in Python and Node.js. All current examples assume LD_SDK_KEY and the provider API keys are set in the environment.

Handler factory names follow create_<provider>_<mode>_handler (Python) and create<Provider><Mode>Handler (Node.js), for example create_openai_messages_handler, create_openai_agents_handler, createOpenAIMessagesHandler, createOpenAIAgentsHandler, createClaudeMessagesHandler, createClaudeAgentsHandler. Some published examples use other names, such as createOpenAIHandler or create_openai_agent_handler; these are not exported by the current packages.

Contents

  1. API mapping
  2. Packages
  3. Initialization
  4. Completion call: convenience function
  5. Completion call: multi-provider handlers
  6. Fallbacks and inspection
  7. Agent mode and tools
  8. Registries
  9. Streaming and history
  10. User feedback
  11. Judges
  12. Agent graphs

API mapping

Concern Legacy Current
Init LDAIClient(ld_client) / initAi(ldClient) Lazy init from LD_SDK_KEY, or init_client() / initClient()
Completion completion_config() / completionConfig() config().invoke() or a convenience function
Agent agent_config() / agentConfig() config().invoke(); mode comes from the variation
Multi-agent agent_configs() / agentConfigs() graph() or a native framework runner
Managed objects create_model(), create_agent() / createModel().run(), createAgent() Convenience function or config().invoke()
Metrics create_tracker(), track_metrics_of, track_* / createTracker(), trackMetricsOf, track* Generation metrics are automatic on invoke() / stream(); a background run_judge() / runJudge() returns judge metrics that the worker must track
Feedback tracker.track_feedback() / tracker.trackFeedback() get_client().track() / getClient().track() with result.track_data / result.trackData (in Python, convert the context dict with ldclient.Context.from_dict(context))
Model parameters Passed manually to provider client (model=config.model.name, **config.model.parameters) Handler packages forward a per-handler allowlist of model.parameters (mapping max_tokens → max_output_tokens on OpenAI) and drop unknown keys; move app-scoped knobs to model.custom, and use an explicit allowlist in custom handlers
Content capture N/A (app owned any tracing) Prompts, outputs, tool payloads, and judge reasoning are captured on OpenTelemetry spans by default in 1.0+ (capture_content=True); opt out with configure(options=SDKOptions(capture_content=False)) / configure({ options: { captureContent: false } })
Fallback Default config object with enabled=False try/except around invoke() (checking inspect_config() / inspectConfig() before falling back); inspect_config() / inspectConfig() to read state
Template variables Fourth argument to completion_config / completionConfig variables= (convenience, Python), { variables } (convenience, Node), or third argument to invoke() ({{name}} without spaces; {{ldContext.*}} replaces {{ldctx.*}})
Judges create_judge(), judge_config() / createJudge(), judgeConfig() Judges attached to the variation; skip_judges / skipJudges plus a durable worker that runs and tracks run_judge() / runJudge() results
Graphs agent_graph(), create_agent_graph(), traversal helpers graph(), resolve_graph() / resolveGraph()
Shutdown ld_client.close() / ldClient.close() shutdown()

Packages

Language Remove Add
Python launchdarkly-server-sdk-ai, launchdarkly-server-sdk-ai-openai, launchdarkly-server-sdk-ai-langchain (imports ldai, ldai_openai, ldai_langchain) "launchdarkly-ai-server[ld]" (or launchdarkly-server-sdk + launchdarkly-ai-server, or "launchdarkly-ai-python[ld]"); plus one launchdarkly-ai-<provider>-<mode> per handler
Node.js @launchdarkly/server-sdk-ai, @launchdarkly/server-sdk-ai-openai, @launchdarkly/server-sdk-ai-langchain, @launchdarkly/server-sdk-ai-vercel @launchdarkly/ai-node (bundles @launchdarkly/node-server-sdk), or @launchdarkly/ai-server for edge runtimes; plus one @launchdarkly/ai-<provider>-<mode> per handler
# Python (3.12+)
pip uninstall launchdarkly-server-sdk-ai launchdarkly-server-sdk-ai-openai
pip install "launchdarkly-ai-server[ld]" launchdarkly-ai-openai-messages

# Node.js
npm uninstall @launchdarkly/server-sdk-ai @launchdarkly/server-sdk-ai-openai
npm install @launchdarkly/ai-node @launchdarkly/ai-openai-messages

Python modules are the package name with underscores (launchdarkly_ai_server, launchdarkly_ai_openai_messages). If you install launchdarkly-ai-python, import the core API from launchdarkly_ai_python instead.

Initialization

Legacy:

from ldclient import set_config, get
from ldclient.config import Config
from ldai import LDAIClient

set_config(Config("YOUR_SDK_KEY"))
aiclient = LDAIClient(get())
import { init } from '@launchdarkly/node-server-sdk';
import { initAi } from '@launchdarkly/server-sdk-ai';

const ldClient = init('YOUR_SDK_KEY');
await ldClient.waitForInitialization({ timeout: 10 });
const aiClient = initAi(ldClient);

Current: delete both. The first AI call initializes the client from LD_SDK_KEY. Pre-warm or pass options only if needed, and always flush on exit:

from launchdarkly_ai_server import init_client, shutdown

await init_client()   # optional
...
await shutdown()
import { initClient, shutdown } from '@launchdarkly/ai-node';

await initClient();   // optional
// Edge or custom runtime: await initClient(preInitializedClient);
...
await shutdown();

If the app also evaluates ordinary feature flags, keep its existing server SDK client for those. To share one client, pass it to init_client(client=ld_client) / initClient(ldClient).

In 1.0+, OpenTelemetry spans capture prompts, model output, tool arguments/results, and judge reasoning by default (capture_content=True). To opt out process-wide, call configure() before the first AI call:

from launchdarkly_ai_server import SDKOptions, configure

configure(options=SDKOptions(capture_content=False))
import { configure } from '@launchdarkly/ai-node';

configure({ options: { captureContent: false } });

Completion call: convenience function

Use when the config serves one provider in one mode.

Legacy:

from ldai import AICompletionConfigDefault
from ldai_openai import get_ai_metrics_from_response

config = aiclient.completion_config(
    "example-config-key",
    context,
    AICompletionConfigDefault(enabled=False),
    {"example_custom_variable": "example_custom_value"},
)
tracker = config.create_tracker()

if config.enabled:
    messages = [] if config.messages is None else config.messages
    completion = tracker.track_metrics_of(
        get_ai_metrics_from_response,
        lambda: openai_client.chat.completions.create(
            model=config.model.name,
            messages=[m.to_dict() for m in messages] + [{"role": "user", "content": user_input}],
        ),
    )
    text = completion.choices[0].message.content
import { getAIMetricsFromResponse } from '@launchdarkly/server-sdk-ai-openai';

const aiConfig = await aiClient.completionConfig(
  'example-config-key',
  context,
  { enabled: false },
  { exampleCustomVariable: 'exampleCustomValue' },
);
const tracker = aiConfig.createTracker();
const response = await tracker.trackMetricsOf(getAIMetricsFromResponse, () =>
  openai.chat.completions.create({
    model: aiConfig.model?.name || 'gpt-4',
    messages: [...(aiConfig.messages || []), { role: 'user', content: userInput }],
  }),
);
const text = response.choices[0].message.content;

Current:

from launchdarkly_ai_openai_messages import openai_messages

result = await openai_messages(
    "example-config-key",
    user_input,
    {"kind": "user", "key": "user-123"},
    variables={"example_custom_variable": "example_custom_value"},
)
text = result.response
import { openaiMessages } from '@launchdarkly/ai-openai-messages';

const result = await openaiMessages(
  'example-config-key',
  userInput,
  { kind: 'user', key: 'user-123' },
  { variables: { exampleCustomVariable: 'exampleCustomValue' } },
);
const text = result.response;

Other convenience functions follow the same shape: openai_agents / openaiAgents, claude_messages / claudeMessages, claude_agents / claudeAgents, and so on. Check the handler package's exports.

Completion call: multi-provider handlers

Use when variations of one config can target different providers or modes. The SDK routes to the handler that matches the variation's provider and mode.

from launchdarkly_ai_server import config
from launchdarkly_ai_openai_messages import create_openai_messages_handler
from launchdarkly_ai_claude_messages import create_claude_messages_handler

result = await config(
    key="example-config-key",
    handler=[create_openai_messages_handler(), create_claude_messages_handler()],
).invoke(
    user_input,
    {"kind": "user", "key": "user-123"},
    {"example_custom_variable": "example_custom_value"},
)
print(result.response, result.usage)
import { config } from '@launchdarkly/ai-node';
import { createOpenAIMessagesHandler } from '@launchdarkly/ai-openai-messages';
import { createClaudeMessagesHandler } from '@launchdarkly/ai-claude-messages';

const result = await config({
  key: 'example-config-key',
  handler: [createOpenAIMessagesHandler(), createClaudeMessagesHandler()],
}).invoke(
  userInput,
  { kind: 'user', key: 'user-123' },
  { exampleCustomVariable: 'exampleCustomValue' },
);
console.log(result.response, result.usage);

Fallbacks and inspection

There is no fallback argument. invoke() raises when the variation is disabled (RuntimeError: Variation '<key>' is disabled. in Python, Error: Variation <key> is not enabled in Node.js) or when LaunchDarkly cannot be reached. Because handler packages also raise RuntimeError / Error when a run fails after starting (for example, hitting the tool-loop step limit), check inspect_config() / inspectConfig() in the error handler and re-raise when enabled is true so real run failures are not swallowed by the disabled-config fallback:

from launchdarkly_ai_server import inspect_config
from launchdarkly_ai_openai_messages import openai_messages

FALLBACK = "Sorry, the assistant is unavailable right now."

try:
    result = await openai_messages("example-config-key", user_input, context)
    text = result.response
except Exception:
    if (await inspect_config("example-config-key", context))["enabled"]:
        raise
    logger.warning("AI config disabled or unreachable; using fallback")
    text = FALLBACK
import { inspectConfig } from '@launchdarkly/ai-node';
import { openaiMessages } from '@launchdarkly/ai-openai-messages';

let text: string;
try {
  text = (await openaiMessages('example-config-key', userInput, context)).response;
} catch (err) {
  if ((await inspectConfig('example-config-key', context)).enabled) throw err;
  logger.warn('AI config disabled or unreachable; using fallback', err);
  text = FALLBACK;
}

To read state up front without raising and without calling a provider or emitting metrics, use inspect_config() / inspectConfig(). It returns enabled, config (the evaluated variation, or None / null), and meta:

state = await inspect_config("example-config-key", context)
if not state["enabled"]:
    return FALLBACK
const state = await inspectConfig('example-config-key', context);
if (!state.enabled) return FALLBACK;

Inspecting first and then invoking evaluates the flag twice; keep the try/except either way, because LaunchDarkly can become unreachable between the two calls.

Agent mode and tools

Legacy agent mode used a separate evaluation call, and the app ran its own tool loop and tracked metrics:

from ldai import AIAgentConfigDefault

agent = aiclient.agent_config(
    "example-config-key", context, AIAgentConfigDefault(enabled=False),
    {"example_custom_variable": "example_custom_value"},
)
if agent.enabled:
    tracker = agent.create_tracker()
    result = run_my_tool_loop(agent.instructions, tools={"get-prefs": get_preferences_fn})
    tracker.track_success()
const agent = await aiClient.agentConfig(
  'example-config-key', context, { enabled: false },
  { exampleCustomVariable: 'exampleCustomValue' },
);
if (agent.enabled) {
  // agent.instructions + hand-written tool loop + agent.tracker.track*()
}

Current: completion and agent mode share config(). Register tool implementations by name; the handler runs the tool loop. Keys must match the tool names in the variation exactly, including case. Each tool function receives a single args dict (Python) or object (Node.js), not unpacked keyword arguments—wrap multi-argument functions (lambda args: get_preferences_fn(**args)) or LangChain @tool objects (lambda args: get_preferences_tool.invoke(args)).

from launchdarkly_ai_server import config
from launchdarkly_ai_openai_agents import create_openai_agents_handler

result = await config(
    key="example-config-key",
    handler=[create_openai_agents_handler()],
    tool_handlers={"get-prefs": get_preferences_fn},
).invoke(
    "What are my preferences?",
    {"kind": "user", "key": "user-123"},
    {"example_custom_variable": "example_custom_value"},
)
import { config } from '@launchdarkly/ai-node';
import { createOpenAIAgentsHandler } from '@launchdarkly/ai-openai-agents';

const result = await config({
  key: 'example-config-key',
  handler: [createOpenAIAgentsHandler()],
  toolHandlers: { 'get-prefs': getPreferencesFn },
}).invoke(
  'What are my preferences?',
  { kind: 'user', key: 'user-123' },
  { exampleCustomVariable: 'exampleCustomValue' },
);

Before deleting the loop, confirm that every tool it defined in code exists on each variation in LaunchDarkly. A tool missing from the variation is silently unavailable to the migrated agent; nothing fails. Do the same for a step cap or default model the old loop set: move it to the variation (or a custom handler) or tell the user. Then delete the hand-written loop, the provider tool-schema construction, and the manual track_tool_call / trackToolCall calls.

Registries

Register handlers and tools once, then pass the registry to every call site. Use a scoped Registry when parts of the app need different handlers or tools, and global_registry / globalRegistry when one set fits the whole app.

from launchdarkly_ai_server import Registry, config
from launchdarkly_ai_openai_messages import create_openai_messages_handler
from launchdarkly_ai_openai_agents import create_openai_agents_handler

openai_registry = Registry(
    handlers=[create_openai_messages_handler(), create_openai_agents_handler()],
    tools={"get-prefs": get_preferences_fn},
)

result = await config(key="example-config-key", registry=openai_registry).invoke(user_input, context)
import { Registry, config } from '@launchdarkly/ai-node';
import { createOpenAIMessagesHandler } from '@launchdarkly/ai-openai-messages';
import { createOpenAIAgentsHandler } from '@launchdarkly/ai-openai-agents';

const openaiRegistry = new Registry({
  handlers: [createOpenAIMessagesHandler(), createOpenAIAgentsHandler()],
  tools: { 'get-prefs': getPreferencesFn },
});

const result = await config({ key: 'example-config-key', registry: openaiRegistry }).invoke(userInput, context);

Some providers expose built-in tools (for example Claude web search) that you assign as tool implementations instead of writing a function.

Streaming and history

Replace trackStreamMetricsOf / manual time-to-first-token tracking with stream(). It takes the same arguments as invoke().

async for event in config(key="example-config-key", registry=openai_registry).stream(user_input, context):
    if event["type"] == "chunk":
        print(event["text"], end="")
    elif event["type"] == "done":
        final_text, usage = event["response"], event["usage"]
for await (const event of config({ key: 'example-config-key', registry: openaiRegistry }).stream(userInput, context)) {
  if (event.type === 'chunk') process.stdout.write(event.text);
  if (event.type === 'done') console.log(event.usage);
}

For multi-turn chat, stop appending to a message array you merge with config.messages. Pass earlier turns as the fourth argument, history:

history = [
    {"role": "user", "content": "Hi"},
    {"role": "assistant", "content": "Hello! How can I help?"},
]
result = await config(key="example-config-key", registry=openai_registry).invoke(
    user_input, context, None, history
)

User feedback

The current SDKs do not have a track_feedback / trackFeedback helper on a tracker, because there is no tracker. Instead, invoke() returns result.track_data (Python) / result.trackData (Node.js) identifying the config, variation, version, and model. Pass it to get_client().track() / getClient().track() when the user gives thumbs up or down:

Legacy:

from ldai.tracker import FeedbackKind

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

tracker.trackFeedback({ kind: LDFeedbackKind.Positive });

Current:

from ldclient import Context
from launchdarkly_ai_server import config, get_client

result = await config(key="example-config-key", registry=openai_registry).invoke(user_input, context)

# When the user responds with thumbs up / down:
event = "$ld:ai:feedback:user:positive" if thumbs_up else "$ld:ai:feedback:user:negative"
get_client().track(event, Context.from_dict(context), result.track_data, 1)
import { config, getClient } from '@launchdarkly/ai-node';

const result = await config({ key: 'example-config-key', registry: openaiRegistry }).invoke(userInput, context);

// When the user responds with thumbs up / down:
const event = thumbsUp ? '$ld:ai:feedback:user:positive' : '$ld:ai:feedback:user:negative';
getClient().track(event, context, result.trackData, 1);

stream() does not currently return track_data, so feedback on streamed responses cannot yet be attributed to a variation.

Judges

Legacy apps created a judge and called it after each response. Now judges are attached to the config variation in LaunchDarkly and run inline by default on every invoke(). If the legacy app judged only some calls on a config, it will now judge all of them; pass skip_judges=True / skipJudges: true on the calls that shouldn't be judged. Delete create_judge / createJudge call sites once the judges are attached to the variation (ask the user to attach them if they aren't).

To keep latency low, skip inline judges and put the returned tasks on a durable worker or queue. run_judge() / runJudge() executes the judge call but does not emit the judge's evaluation metric. The worker must track the returned score and supplied track data. Do not use a request-scoped create_task() or an unobserved promise: the request can end before either the judge or its metric finishes.

Python example for a long-lived process (use a durable queue instead when the process can be suspended or terminated after the request):

import asyncio
import threading
from ldclient import Context
from launchdarkly_ai_server import (
    config,
    get_client,
    global_registry,
    resolve_handlers,
    run_judge,
)

result = await config(
    key="example-config-key", registry=global_registry, skip_judges=True
).invoke(user_input, context)

handlers = resolve_handlers(global_registry, None) or []

def run_and_track_judge(task):
    judge_result = asyncio.run(run_judge(task, handlers))
    if judge_result and task.evaluation_metric_key:
        get_client().track(
            task.evaluation_metric_key,
            Context.from_dict(task.user_context),
            judge_result.track_data,
            judge_result.score,
        )

for task in result.judge_tasks or []:
    threading.Thread(
        target=run_and_track_judge,
        args=(task,),
        daemon=False,
    ).start()

Node.js worker example. Enqueue each judgeTask from the request handler, then run this function in the queue consumer:

import {
  config,
  getClient,
  globalRegistry,
  runJudge,
} from '@launchdarkly/ai-node';
import { createOpenAIMessagesHandler } from '@launchdarkly/ai-openai-messages';

// The handlers your judge configs' providers need.
const handlers = [createOpenAIMessagesHandler()];

const { response, judgeTasks } = await config({
  key: 'example-config-key',
  registry: globalRegistry,
  skipJudges: true,
}).invoke(userInput, context);

// Request path: enqueue the serializable task; do not run it as an unobserved promise.
for (const task of judgeTasks ?? []) {
  await judgeQueue.enqueue(task);
}

// Durable worker / queue consumer:
async function processJudgeTask(task) {
  const judgeResult = await runJudge(task, handlers);
  if (judgeResult && task.evaluationMetricKey) {
    getClient().track(
      task.evaluationMetricKey,
      task.userContext,
      judgeResult.trackData,
      judgeResult.score,
    );
  }
}

handlers is the list of provider handlers the judge configs can use. Remove the legacy track_judge_result / trackJudgeResult calls, but preserve their behavior with the current client's track() call shown above.

Agent graphs

Replace agent_configs / agentConfigs, agent_graph, create_agent_graph, and hand-written traversal with graph().invoke():

from launchdarkly_ai_server import graph
from launchdarkly_ai_claude_agents import create_claude_agents_handler
from launchdarkly_ai_openai_agents import create_openai_agents_handler

result = await graph(
    "support-graph",
    handlers=[create_claude_agents_handler(), create_openai_agents_handler()],
    tool_handlers={"lookup-invoice": lookup_invoice},
).invoke("I was double charged", {"kind": "user", "key": "user-123"}, {"account_tier": "pro"})
print(result.response)
import { graph } from '@launchdarkly/ai-node';
import { createClaudeAgentsHandler } from '@launchdarkly/ai-claude-agents';

const result = await graph('support-graph', {
  handlers: [createClaudeAgentsHandler()],
  toolHandlers: { 'lookup-invoice': lookupInvoice },
}).invoke('I was double charged', { kind: 'user', key: 'user-123' }, { account_tier: 'pro' });
console.log(result.response);

To keep running on a framework the app already uses, call resolve_graph() / resolveGraph() and pass the result to that framework's runner: to_lang_graph / toLangGraph, to_openai_agents / toOpenAIAgents, or to_claude_agents / toClaudeAgents. Check the handler package's exports and README for the exact call.

If the app walks the resolved topology by hand instead of using graph().invoke() or a native runner:

  • Node and edge accessors are attributes now: graph.enabled, graph.root, node.key, node.config (a plain dict), node.edges, and edge.target_key / edge.targetKey (replacing is_enabled(), root(), get_key(), get_config(), get_edges(), and edge.target_config).
  • resolve_graph() / resolveGraph() returns topology only and emits no telemetry on its own. Pass handlers= to resolve_graph() and execute nodes with await graph.run_node(node, input, opts) / await graph.runNode(node, input, opts) or graph.route(node, input, opts), or emit the $ld:ai:graph:* events yourself ($ld:ai:graph:node, $ld:ai:graph:handoff_success, $ld:ai:graph:handoff_failure, $ld:ai:graph:invocation_success, $ld:ai:graph:invocation_failure, $ld:ai:graph:duration:total, $ld:ai:graph:total_tokens, plus $ld:ai:tool_call). These match the legacy SDKs except that $ld:ai:graph:path became $ld:ai:graph:node and $ld:ai:graph:redirect is gone, so only LaunchDarkly metrics built on those two keys need updating.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2d3 checks · Risk SAFE
  • Gen Agent Trust Hub2d

    This skill guides the migration of applications from legacy LaunchDarkly AI SDKs to the current handler-based versions across Python, Node.js, and Go. It is verified as safe, as all recommended packages and documentation links originate from official and trusted LaunchDarkly infrastructure.

  • Socket3d

    No alerts

  • Snyk2d

    Risk: LOW · No issues

Signed by skilld at f0ee110. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 days ago
metadata
{
  "author": "launchdarkly",
  "version": "0.2.0"
}
Other metadata
compatibility
Python 3.12+ (`launchdarkly-ai-server` 1.0.0+ with `launchdarkly-server-sdk`), Node.js (`@launchdarkly/ai-node` 1.0.0+), or Go 1.26+ (`github.com/launchdarkly/go-ai-sdk` v1.0.0). No LaunchDarkly MCP tools needed; the AgentControl configs already exist.

README badge

README badge for launchdarkly/ai-tooling/legacy-sdk-migrate