Migrate from the legacy AI SDKs

This topic explains how to migrate from the legacy Python and Node.js AI SDKs to the current AI SDKs. The current SDKs are not drop-in replacements. You must change some workflows when you migrate. You stop evaluating a config and calling the provider yourself, and instead register handlers and invoke the model through the SDK. The current Python and Node.js AI SDKs are in open beta. Their APIs are subject to change. To learn more about each SDK, read the Python AI SDK reference and Node.js (server-side) AI SDK reference.

How SDK versions differ

We recommend migrating from the legacy AI SDK version to the current version when possible. Recent SDK versions facilitate more efficient implementations by removing the requirement for custom coding in many parts of your application. The current SDKs remove the provider setup, message merging, and metrics wrapping you had to write by hand in the legacy SDKs. For the full before-and-after examples, read Migrate a manual completion call.

Language	Legacy AI SDK	Current AI SDK
Python	28 lines	9 lines
Node.js	25 lines	9 lines

To compare the code itself, switch between these tabs:

from ldclient import set_config, get
from ldclient.config import Config
from ldai import LDAIClient, AICompletionConfigDefault
from ldai_openai import get_ai_metrics_from_response
from openai import OpenAI

set_config(Config("YOUR_SDK_KEY"))
ai_client = LDAIClient(get())
openai_client = OpenAI()

config = ai_client.completion_config(
  "example-config-key",
  context,
  AICompletionConfigDefault(enabled=False),
)
tracker = config.create_tracker()

if config.enabled:
  messages = [m.to_dict() for m in config.messages or []]
  messages.append({"role": "user", "content": user_input})
  completion = tracker.track_metrics_of(
      get_ai_metrics_from_response,
      lambda: openai_client.chat.completions.create(
          model=config.model.name,
          messages=messages,
      ),
  )
  print(completion.choices[0].message.content)

from launchdarkly_ai_openai_messages import openai_messages

result = await openai_messages(
  "example-config-key",
  user_input,
  {"kind": "user", "key": "user-123"},
)

print(result.response)

import { init } from '@launchdarkly/node-server-sdk';
import { initAi } from '@launchdarkly/server-sdk-ai';
import { getAIMetricsFromResponse } from '@launchdarkly/server-sdk-ai-openai';
import OpenAI from 'openai';

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

const aiConfig = await aiClient.completionConfig('example-config-key', context, {
enabled: false,
});

if (aiConfig.enabled) {
const tracker = aiConfig.createTracker();
const messages = [...(aiConfig.messages ?? []), { role: 'user', content: userInput }];
const completion = await tracker.trackMetricsOf(getAIMetricsFromResponse, () =>
  openai.chat.completions.create({
    model: aiConfig.model?.name ?? 'gpt-4o',
    messages,
  }),
);
console.log(completion.choices[0].message.content);
}

import { openaiMessages } from '@launchdarkly/ai-openai-messages';

const result = await openaiMessages(
'example-config-key',
userInput,
{ kind: 'user', key: 'user-123' },
);

console.log(result.response);

Most of these responsibilities leave your application when you migrate. Fallback handling is the exception because the current SDKs raise an error rather than return a disabled config:

Responsibility	What happens in the current AI SDK
Initialize the LaunchDarkly and AI clients	The SDK initializes from the environment, or you call `init_client()` / `initClient()`
Construct a provider client and choose a model	A handler package resolves the provider and model from the AgentControl config
Supply fallback values and check `enabled`	There is no fallback argument. `invoke()` raises an error if the variation has targeting off or if LaunchDarkly is unreachable. Keep your own fallback response and check state with `inspect_config()` / `inspectConfig()`
Merge config messages with user input	The SDK merges messages before it calls the provider
Create a tracker and wrap the provider call	The SDK records metrics and OpenTelemetry spans on every invoke

In the legacy SDKs, you evaluate an AgentControl config, call your model provider with the returned messages or instructions, and record metrics with a tracker. In the current SDKs, you register provider handlers and tools one time, then call config(), graph(), or a convenience function. The SDK evaluates the config, routes to the matching handler, calls the provider, and records metrics and OpenTelemetry spans for you.

Step	Legacy AI SDK	Current AI SDK
Evaluate the config	Call `completion_config()` / `completionConfig()`, `agent_config()` / `agentConfig()`, or related methods	Call `config()`, `graph()`, or a provider convenience function
Call the provider	Build a provider client, merge messages, and call the provider yourself	A handler package calls the provider
Record metrics	Create a tracker and wrap the provider call	Automatic on every invoke

What changes when you migrate from a legacy SDK

You must change some parts of your application code when you migrate. They are:

Packages: Replace the legacy AI SDK packages with the current core package, as well as provider and mode handler packages.
Initialization: Replace explicit LaunchDarkly and AI client construction with automatic initialization from the environment, or call init_client() / initClient() when you need control.
Model calls: Replace evaluate-then-call-provider-yourself with config().invoke(), graph(), or a provider convenience function.
Tools and handlers: Register tool implementations and handlers one time, typically in a Registry, instead of wiring them at every call site.
Metrics and traces: Remove tracker setup and manual span wrapping. The SDK records metrics and creates OpenTelemetry spans automatically.
Judges and graphs: Attach judges to config variations instead of calling a standalone judge, and replace legacy graph helpers with graph() or resolve_graph() / resolveGraph(), as well as a native runner.

The sections below contain examples for each of these changes.

Replace packages and install handlers

Uninstall the legacy AI SDK packages and install the current core package, as well as one handler package for each provider and mode you use.

Language	Legacy packages	Current packages
Python	`launchdarkly-server-sdk`, `launchdarkly-server-sdk-ai`, and optional provider helpers such as `ldai_openai`	`launchdarkly-ai-server` and handler packages such as `launchdarkly-ai-openai-messages`
Node.js	`@launchdarkly/node-server-sdk`, `@launchdarkly/server-sdk-ai`, and optional provider packages such as `@launchdarkly/server-sdk-ai-openai`	`@launchdarkly/ai-node` and handler packages such as `@launchdarkly/ai-openai-messages`

Install the base LaunchDarkly server SDK alongside the AI SDK core and handler packages. Use launchdarkly-server-sdk for Python and @launchdarkly/node-server-sdk for Node.js. For edge or custom runtimes, install the core @launchdarkly/ai-server package instead and pass a pre-initialized client. For the full handler package matrix, read Install the SDK in the Python AI SDK reference or Install the SDK in the Node.js AI SDK reference. Here’s how to install the base LaunchDarkly server SDK, the AI SDK core package, and the OpenAI messages handler:

pip install launchdarkly-server-sdk launchdarkly-ai-server launchdarkly-ai-openai-messages

npm install @launchdarkly/ai-node @launchdarkly/ai-openai-messages

Update client initialization

The legacy SDKs require you to construct an explicit LaunchDarkly client and an AI client wrapper. Here’s how the legacy SDKs initialize:

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, LDClient } from '@launchdarkly/node-server-sdk';
import { initAi, LDAIClient } from '@launchdarkly/server-sdk-ai';

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

const aiClient: LDAIClient = initAi(ldClient);

In the current SDKs, initialization is often automatic. The SDK derives its settings from the environment, reading LD_SDK_KEY and your provider API keys, and initializes the client on your first AI call. You no longer construct a LaunchDarkly client or an AI client wrapper yourself. If you need to control initialization, such as to pass custom options or pre-warm the client, call init_client() / initClient() yourself. Call shutdown() when your application exits to flush events and spans. To learn more, read Manage the client lifecycle or Manage the client lifecycle.

Migrate a manual completion call

This is the most common migration. In the legacy SDKs, you evaluate a completion-mode config, merge messages, call the provider, and wrap the call with a tracker. Here’s the legacy pattern:

from ldai import AICompletionConfigDefault
from ldai_openai import get_ai_metrics_from_response

fallback_value = AICompletionConfigDefault(enabled=False)

config = aiclient.completion_config(
  'example-config-key',
  context,
  fallback_value,
  {'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=[message.to_dict() for message in messages],
      ),
  )

import { getAIMetricsFromResponse } from '@launchdarkly/server-sdk-ai-openai';

const fallbackConfig = { enabled: false };

const aiConfig = await aiClient.completionConfig(
'example-config-key',
context,
fallbackConfig,
{ exampleCustomVariable: 'exampleCustomValue' },
);

const tracker = aiConfig.createTracker();
const configMessages = aiConfig.messages || [];
const userMessage = { role: 'user', content: 'What is feature flagging?' };
const allMessages = [...configMessages, userMessage];

const response = await tracker.trackMetricsOf(
getAIMetricsFromResponse,
() => client.chat.completions.create({
  model: aiConfig.model?.name || 'gpt-4',
  messages: allMessages,
}),
);

Use a convenience function

If you call one provider in one mode, replace the evaluate-call-track sequence with that provider’s convenience function. Call it with the config key, the user input, and an LDContext, in that order. The SDK evaluates the config, calls the provider, and records metrics. Pass template variables as the variables keyword argument in Python or inside the options object in Node.js. Here’s the same call with a convenience function:

from dotenv import load_dotenv
from launchdarkly_ai_openai_messages import openai_messages

load_dotenv()

result = await openai_messages(
  "example-config-key",
  "What is feature flagging?",
  {"kind": "user", "key": "user-123"},
  variables={"example_custom_variable": "example_custom_value"},
)

print(result.response)

import 'dotenv/config';
import { openaiMessages } from '@launchdarkly/ai-openai-messages';

const result = await openaiMessages(
'example-config-key',
'What is feature flagging?',
{ kind: 'user', key: 'user-123' },
{ variables: { exampleCustomVariable: 'exampleCustomValue' } },
);

console.log(result.response);

Use handlers for multi-provider routing

If your config can serve more than one provider or mode, register handlers and call config().invoke(). Pass template variables as the third argument to invoke(). You no longer pass a fallback default object, merge UI messages with the user message, or create a tracker. Because there is no fallback argument, invoke() raises an error instead of returning a disabled config. Wrap invoke() to return a fallback response if the variation has targeting off or if LaunchDarkly is unreachable. To read the state without raising, call inspect_config() / inspectConfig(). This returns the enabled flag, the config, and the variation metadata. Here’s how:

from dotenv import load_dotenv
from launchdarkly_ai_server import config, shutdown
from launchdarkly_ai_openai_messages import create_openai_messages_handler
from launchdarkly_ai_claude_messages import create_claude_messages_handler

load_dotenv()

result = await config(
  key="example-config-key",
  handler=[
      create_openai_messages_handler(),
      create_claude_messages_handler(),
  ],
).invoke(
  "What is feature flagging?",
  {"kind": "user", "key": "user-123"},
  {"example_custom_variable": "example_custom_value"},
)

print(result.response)
await shutdown()

import 'dotenv/config';
import { config, shutdown } from '@launchdarkly/ai-server';
import { createOpenAIHandler } from '@launchdarkly/ai-openai-messages';
import { createClaudeMessagesHandler } from '@launchdarkly/ai-claude-messages';

const result = await config({
key: 'example-config-key',
handler: [
  createOpenAIHandler(),
  createClaudeMessagesHandler(),
],
}).invoke(
'What is feature flagging?',
{ kind: 'user', key: 'user-123' },
{ exampleCustomVariable: 'exampleCustomValue' },
);

console.log(result.response);
await shutdown();

If you used Node.js legacy managed objects such as createModel().run(), map those call sites to the same convenience function or config().invoke() path. Managed objects were the closest precursor to the current SDK, but the packages and APIs still change.

Migrate agent mode and tools

In the legacy SDKs, agent mode uses a separate evaluation method, then your application runs the tool loop and records metrics. In the current SDKs, completion and agent mode share config(). The config variation’s mode selects the handler. Register tool implementations by name, or pass them inline. Tool keys must match the tool names defined in the LaunchDarkly config variation exactly, including case. Here’s the legacy agent-mode pattern:

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 = example_model_api(agent.instructions)
  tracker.track_success()

const fallbackConfig = { enabled: false };

const agent = await aiClient.agentConfig(
'example-config-key',
context,
fallbackConfig,
{ exampleCustomVariable: 'exampleCustomValue' },
);

if (agent.enabled) {
const tracker = agent.tracker;
// Use agent.instructions with your provider and tool loop, then track metrics.
}

Here’s the same call with handlers and tools:

from launchdarkly_ai_server import config
from launchdarkly_ai_openai_agents import create_openai_agent_handler

config_instance = config(
  key="example-config-key",
  handler=[create_openai_agent_handler()],
  tool_handlers={
      "get-prefs": get_preferences_fn,
  },
)

result = await config_instance.invoke(
  "What are my preferences?",
  {"kind": "user", "key": "user-123"},
  {"example_custom_variable": "example_custom_value"},
)

print(result.response)

import { config } from '@launchdarkly/ai-server';
import { createOpenAIAgentHandler } from '@launchdarkly/ai-openai-agents';

const configInstance = config({
key: 'example-config-key',
handler: [createOpenAIAgentHandler()],
toolHandlers: {
  'get-prefs': getPreferencesFn,
},
});

const result = await configInstance.invoke(
'What are my preferences?',
{ kind: 'user', key: 'user-123' },
{ exampleCustomVariable: 'exampleCustomValue' },
);

console.log(result.response);

Centralize configuration management

Registries are one of the larger cleanup opportunities in this migration. In the legacy SDKs, sharing handler wiring and tool implementations across call sites meant writing your own higher-level wrapper functions or duplicating handling code at each site. In the current SDKs, you register handlers and tools one time in a Registry, then pass that registry to any call. Provider routing, tool dispatch, and metrics all live in one place. Use a scoped Registry when different parts of your application need different handlers or tools, or the global registry when a single set is appropriate for the whole application. Some providers also expose built-in tools, such as Claude web search, that you assign as tool implementations instead of writing a function. Here’s how to register handlers and tools one time, then reuse them:

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_agent_handler

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

# Reuse the same registry across call sites
result = await config(key="example-config-key", registry=openai_registry).invoke(user_input, context)

import { Registry, config } from '@launchdarkly/ai-server';
import { createOpenAIHandler } from '@launchdarkly/ai-openai-messages';
import { createOpenAIAgentHandler } from '@launchdarkly/ai-openai-agents';

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

// Reuse the same registry across call sites.
const result = await config({ key: 'example-config-key', registry: openaiRegistry }).invoke(userInput, context);

To learn more, read Manage handlers and tools with a registry or Create a registry.

Migrate judges

In the current SDKs, you attach judges to a config variation rather than calling a standalone judge in your application code. To keep response latency low, you can skip inline evaluation and run judges in the background instead. Run attached judges asynchronously. If you don’t include skip_judges=true, judges are run inline by default. Here’s how:

import asyncio
from launchdarkly_ai_server import config, global_registry

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

for task in result.judge_tasks or []:
  asyncio.create_task(run_judge_worker(task))

import { config, globalRegistry } from '@launchdarkly/ai-server';
import { Worker } from 'node:worker_threads';

const { invoke } = config({
key: 'example-config-key',
registry: globalRegistry,
skipJudges: true,
});

const { response, judgeTasks } = await invoke(userInput, context);

for (const task of judgeTasks ?? []) {
new Worker(new URL('./judge-worker.js', import.meta.url), { workerData: task });
}

Inside each worker, call run_judge(task, handlers) / runJudge(task, handlers) and track the evaluation metric when present. To learn more, read Run judges asynchronously or Run judges asynchronously.

Migrate agent graphs

Replace legacy graph creation and traversal helpers with graph().invoke(), or resolve the topology and hand it to a native framework runner. Here’s how to run a graph with the current SDK router:

from launchdarkly_ai_server import graph, shutdown
from launchdarkly_ai_claude_agents import create_claude_agents_handler
from launchdarkly_ai_openai_agents import create_openai_agent_handler

result = await graph(
  "support-graph",
  handlers=[create_claude_agents_handler(), create_openai_agent_handler()],
).invoke(
  "I was double charged",
  {"kind": "user", "key": "user-123"},
  {"account_tier": "pro"},
)

print(result["response"])
await shutdown()

import { graph, shutdown } from '@launchdarkly/ai-server';
import { createClaudeAgentsHandler } from '@launchdarkly/ai-claude-agents';

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

console.log(result.response);
await shutdown();

To run on a provider framework such as LangGraph or the OpenAI Agents SDK, call resolve_graph() / resolveGraph(), then pass the result to to_lang_graph / toLangGraph, to_openai_agents / toOpenAIAgents, or to_claude_agents / toClaudeAgents. To learn more, read Run an agent graph or Run an agent graph.

API mapping

Concern	Legacy	Current
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
Metrics	Tracker methods	Automatic on every call
Judges	`create_judge()` / `createJudge()`	Attached judges, plus `run_judge()` / `runJudge()` for async work
Graphs	`create_agent_graph()`, traverse helpers	`graph()`, `resolve_graph()` / `resolveGraph()`
Init	`LDAIClient` / `initAi()`	Lazy init, or `init_client()` / `initClient()`

​How SDK versions differ

​What changes when you migrate from a legacy SDK

​Replace packages and install handlers

​Update client initialization

​Migrate a manual completion call

​Use a convenience function

​Use handlers for multi-provider routing

​Migrate agent mode and tools

​Centralize configuration management

​Migrate judges

​Migrate agent graphs

​API mapping

​What’s next