.NET AI SDK reference

This topic documents how to get started with the .NET AI SDK, and links to reference information on all of the supported features.

The .NET AI SDK is designed for use with AgentControl. It is in a pre-1.0 release and the API may change based on feedback. Active feature development is ongoing in the Python and Node.js AI SDKs, so this SDK receives new features at a slower pace. You can follow development or contribute on GitHub.

Get started

LaunchDarkly AI SDKs interact with AgentControl configs. Configs are the LaunchDarkly resources that manage model configurations and messages for your generative AI applications.

You can use the .NET AI SDK to customize your config based on the context that you provide. This means both the messages and the model evaluation in your generative AI application are specific to each end user, at runtime. You can also use the AI SDKs to record metrics from your AI model generation, including duration and tokens.

Follow these instructions to start using the .NET AI SDK in your application.

Version compatibility

The .NET AI SDK is built for the following targets:

• .NET 8.0 and higher
• .NET Framework 4.6.2 and higher
• .NET Standard 2.0 and higher

The .NET build tools automatically load the most appropriate build for your application’s target platform.

Install the SDK

First, install the AI SDK as a dependency in your application using your application’s dependency manager. If you want to depend on a specific version, refer to the SDK releases page to identify the latest version.

The .NET AI SDK is built on the .NET (server-side) SDK, so install both packages.

Here’s how:

$
Install-Package LaunchDarkly.ServerSdk
$
Install-Package LaunchDarkly.ServerSdk.Ai

Next, import the namespaces in your application code. The namespace is not the same as the package name:

1
using LaunchDarkly.Sdk.Server.Ai;
2
using LaunchDarkly.Sdk.Server.Ai.Adapters;
3
using LaunchDarkly.Sdk.Server.Ai.Config;

Initialize the client

After you install and import the SDK, create a single, shared instance of LdClient. When the LdClient is initialized, use it to initialize the LdAiClient. The LdAiClient is how you interact with configs. Specify the SDK key to authorize your application to connect to a particular environment within LaunchDarkly.

Here’s how:

1
var baseClient = new LdClient(Configuration.Builder("sdk-key-123").StartWaitTime(TimeSpan.FromSeconds(5)).Build());
2
var aiClient = new LdAiClient(new LdClientAdapter(baseClient));

Configure the context

Next, configure the context that will use the config, that is, the context that will encounter generated AI content in your application. The context attributes determine which variation of the config LaunchDarkly serves to the end user, based on the targeting rules in your config. If you are using template variables in the messages in your config’s variations, the context attributes also fill in values for the template variables.

Here’s how:

1
LDContext context = Context.Builder("example-context-key")
2
    .Set("firstName", "Sandy")
3
    .Set("lastName", "Smith")
4
    .Set("email", "sandy@example.com")
5
    .Set("groups", LdValue.ArrayOf(LdValue.Of("Acme"), LdValue.Of("Global Health Services")))
6
    .Build();

Customize the config

Customize your config to set values for variables used in messages, or for instructions based on context attributes or other information you provide.

The details of customizing a config depend on whether you are using configs in completion mode or agent mode. You set the mode for a config when you create it in the LaunchDarkly UI.

Customize configs in completion mode

In completion mode, each variation in your config includes a single set of roles and messages used to prompt your AI model. Use CompletionConfig to customize the config.

The CompletionConfig method takes an AgentControl config key, a context, a fallback value, and optional variables. It performs the evaluation, then returns an LdAiCompletionConfig object that includes the customized messages and model configuration. Call CreateTracker on the returned object to get a tracker instance you can use to record metrics.

If it cannot perform the evaluation or LaunchDarkly is unreachable, the SDK returns the fallback configuration you provided. For example, you might use LdAiCompletionConfigDefault.Disabled as a fallback value, or a fully configured default. Either way, check for this case and handle it appropriately in your application.

Here’s how:

1
var fallbackConfig = LdAiCompletionConfigDefault.Disabled;
2
3
var config = aiClient.CompletionConfig(
4
  "example-config-key",
5
  context,
6
  fallbackConfig,
7
  new Dictionary<string, object> {
8
    { "exampleCustomVariable", "exampleCustomValue" }
9
  }
10
);
11
12
var tracker = config.CreateTracker();

Customize configs in agent mode

In agent mode, each variation in your config includes a set of instructions that enable multi-step workflows.

In agent mode, use AgentConfig or AgentConfigs to customize the config. The AgentConfig method customizes a single agent config. The AgentConfigs method customizes a list of them.

The instructions returned by the SDK come directly from the instructions you define for the variation in the LaunchDarkly UI. The goal or task shown in the UI is delivered unchanged as the Instructions property on the returned object.

AgentConfig takes an AgentControl config key, a context, a fallback value, and optional variables. It performs the evaluation, then returns an LdAiAgentConfig object that includes the customized instructions. Call CreateTracker on the returned object to get a tracker instance for recording metrics. AgentConfigs takes IEnumerable<AgentConfigRequest> and returns a dictionary.

If the method cannot perform the evaluation or LaunchDarkly is unreachable, it returns the fallback value. For example, you might use LdAiAgentConfigDefault.Disabled as a fallback value, or a fully configured default. Either way, check for this case and handle it appropriately in your application.

Here’s how:

1
var fallbackConfig = LdAiAgentConfigDefault.Disabled;
2
3
var agent = aiClient.AgentConfig(
4
  "example-config-key",
5
  context,
6
  fallbackConfig,
7
  new Dictionary<string, object> {
8
    { "exampleCustomVariable", "exampleCustomValue" }
9
  }
10
);

To learn more, read Customizing AgentControl configs.

Evaluate input and output pairs with a judge

The JudgeConfig method takes an AgentControl config key, a context, a fallback value, and optional variables. It returns an LdAiJudgeConfig object that includes the judge’s customized messages, model configuration, and the EvaluationMetricKey to associate scores with. Pass the input and output you want to evaluate as variables so the judge’s message template can reference them.

If the SDK cannot perform the evaluation or LaunchDarkly is unreachable, it returns the fallback value. You can use LdAiJudgeConfigDefault.Disabled as a fallback, or a fully configured default.

Unlike completion mode and agent mode, the .NET AI SDK does not invoke the model for you in judge mode. You are responsible for calling your AI provider with the judge’s messages, parsing the score from the response, and recording it to LaunchDarkly using the tracker’s TrackJudgeResult method.

Here’s how:

1
var fallback = LdAiJudgeConfigDefault.Disabled;
2
3
var judge = aiClient.JudgeConfig(
4
  "example-judge-key",
5
  context,
6
  fallback,
7
  new Dictionary<string, object> {
8
    { "input", inputText },
9
    { "output", outputText }
10
  }
11
);
12
13
if (judge.Enabled) {
14
  // Call your AI provider using judge.Model and judge.Messages,
15
  // then parse the score from the response.
16
  var score = CallModelAndParseScore(judge.Model, judge.Messages);
17
18
  // Record the score against the metric key the judge specifies.
19
  // Use the tracker from the completion or agent config whose output you
20
  // are evaluating, so the score is associated with that config's run.
21
  tracker.TrackJudgeResult(new JudgeResult(
22
    metricKey: judge.EvaluationMetricKey,
23
    score: score,
24
    judgeConfigKey: judge.Key
25
  ));
26
}

Programmatic judge evaluation does not automatically emit metrics for the config’s Monitoring tab. It also does not attach judges to variations in the LaunchDarkly UI.

To learn more, read Online evaluations in AgentControl and Judges.

Call the provider and record metrics from AI model generation

Finally, make a request to your generative AI provider and record metrics from your AI model generation. The steps to do this vary based on whether you use completion mode or agent mode.

In completion mode, use the tracker’s TrackMetricsOf method to call your generative AI provider and record metrics from model generation. Check whether the returned LdAiCompletionConfig is enabled and handle the disabled case appropriately in your application.

In agent mode, you can access the Instructions returned from the customized config to send to your AI model. Call CreateTracker on the returned LdAiAgentConfig object to get a tracker instance you can use to record metrics.

Here’s how:

1
if (config.Enabled) {
2
3
var response = tracker.TrackMetricsOf(
4
  result => new AiMetrics(success: true, tokens: new Usage(total, input, output)),
5
  () => CallProviderAsync()
6
);
7
    {
8
      // Make request to a provider, which automatically tracks metrics in LaunchDarkly.
9
      // When sending the request to a provider, use details from the config.
10
      // For example, you can pass config.Model and config.Messages.
11
      // Optionally, return response metadata, for example to do your own additional logging.
12
      //
13
      // CAUTION: If the call inside of the function throws an exception,
14
      // the SDK will re-throw that exception
15
16
      return new Response
17
      {
18
        Usage = new Usage { Total = 1, Input = 1, Output = 1 }, /* Token usage data */
19
        Metrics = new Metrics { LatencyMs = 100 } /* Metrics data */
20
      };
21
    }
22
  ));
23
24
} else {
25
26
  // Application path to take when the config is disabled
27
28
}

If you would like to do any tracking beyond what LaunchDarkly provides, you must fill in the AiMetrics object with the data you want to track.

Alternatively, you can use the tracker’s other Track* methods to record metrics manually. The tracker provides methods for tracking duration, tokens, time to first token, tool calls, judge results, success, error, and feedback.

Make sure to call CompletionConfig or AgentConfig each time you generate content from your AI model. Here’s how:

1
var config = aiClient.CompletionConfig(
2
  "example-config-key",
3
  context,
4
  fallbackConfig,
5
  new Dictionary<string, object> {
6
    { "exampleCustomVariable", "exampleCustomValue" }
7
  }
8
);
9
10
var tracker = config.CreateTracker();
11
var response = tracker.TrackMetricsOf(...);

To learn more, read Tracking AI metrics.

Agent graphs

Agent graphs let you define a directed graph of agent configs in the LaunchDarkly UI, then traverse the graph at runtime to orchestrate multi-step workflows. Each node in the graph is an agent config. Each edge defines a handoff from one agent to the next.

Use AgentGraph to retrieve a graph by its key. The graph key populates automatically when you create a graph in the LaunchDarkly UI. After the graph exists, the key is in the agent graph details panel. To learn more, read Initialize an agent graph.

The method takes a graph key, a context, and optional variables. It returns an AgentGraphDefinition that exposes the graph’s topology and a tracker for recording invocation metrics.

Here’s how:

1
var graph = aiClient.AgentGraph(
2
  "example-graph-key",
3
  context,
4
  new Dictionary<string, object> {
5
    { "exampleCustomVariable", "exampleCustomValue" }
6
  }
7
);
8
9
if (graph.Enabled) {
10
  var tracker = graph.CreateTracker();
11
  // Walk the graph and invoke each agent's config
12
}

You can navigate the graph manually using RootNode, GetNode, GetChildNodes, GetParentNodes, and TerminalNodes. Each AgentGraphNode exposes:

• Key: the agent config key for this node.
• Config: the LdAiAgentConfig for the node, with Instructions, Model, Tools, and other agent config properties.
• Edges: the outgoing edges from this node. Each GraphEdge includes the target node Key and a Handoff dictionary describing how to pass state to the next node.
• IsTerminal: whether this node has no outgoing edges.

Alternatively, use Traverse or ReverseTraverse to walk the graph with a callback that the SDK invokes for each node. Traverse walks breadth-first from the root. ReverseTraverse walks breadth-first from the terminal nodes back toward the root.

Both methods take a callback with the signature Func<AgentGraphNode, Dictionary<string, object>, object> and an optional initial context dictionary. The SDK calls the callback one time for each node, passing the node and a shared context dictionary. The callback’s return value is stored in the context dictionary under the node’s key. This allows downstream nodes to read upstream results.

Here’s how:

1
graph.Traverse((node, context) =>
2
{
3
  // Use node.Config to call your AI provider, passing instructions and tools.
4
  // Read upstream results from context as needed.
5
  var output = CallModelForNode(node.Config, context);
6
7
  // The return value is stored in context[node.Key] for downstream nodes.
8
  return output;
9
});

The SDK does not automatically record handoff or invocation metrics during traversal. Call the appropriate AiGraphTracker methods from your callback to record what happens at each node and edge.

Use the AiGraphTracker returned by CreateTracker to record metrics for the full graph invocation as well as per-edge handoffs:

• TrackInvocationSuccess and TrackInvocationFailure record whether the graph completed successfully
• TrackDuration records total invocation duration
• TrackTotalTokens records aggregate token usage across all nodes
• TrackPath records the sequence of nodes visited
• TrackHandoffSuccess and TrackHandoffFailure record per-edge handoff outcomes
• TrackRedirect records when a node redirects to a different target than its declared edges

You can call the provider for each node the same way you do in agent mode. To learn more, read Customize configs in agent mode.

To learn more about defining agent graphs in the LaunchDarkly UI, read Agent graphs.

Resume tracking across processes

If a single AI workflow spans multiple processes, you can resume tracking on the same config or graph invocation in a different process. An example of this is if a request handler hands work off to a background job.

Each tracker exposes a ResumptionToken property. In the original process, read the token after you create the tracker, then pass it to the next process through a job queue, database row, or message envelope.

In the receiving process, call aiClient.CreateTracker for a completion or agent tracker, or aiClient.CreateGraphTracker for an agent graph tracker. Both methods take the resumption token and a context and return a tracker that records to the same invocation as the original.

Here’s how:

1
var config = aiClient.CompletionConfig("example-config-key", context, fallbackConfig);
2
var tracker = config.CreateTracker();
3
4
// Hand off work to another process. Persist the resumption token so the
5
// receiving process can reconstruct the tracker.
6
var token = tracker.ResumptionToken;
7
EnqueueBackgroundJob(token, context);

For agent graphs, use CreateGraphTracker in place of CreateTracker. The token comes from AiGraphTracker.ResumptionToken on the original graph tracker.

Supported features

This SDK supports the following features:

• Anonymous contexts
• Context configuration
• Customizing AgentControl configs
• Private attributes
• Tracking AI metrics