Java AI SDK reference

​

Get started

​

Version compatibility

​

Install the SDK

<dependency>
  <groupId>com.launchdarkly</groupId>
  <artifactId>launchdarkly-java-server-sdk</artifactId>
</dependency>
<dependency>
  <groupId>com.launchdarkly</groupId>
  <artifactId>launchdarkly-java-server-sdk-ai</artifactId>
</dependency>

​

Initialize the client

LDClient ldClient = new LDClient(sdkKey);
LDAIClient aiClient = new LDAIClientImpl(ldClient);

​

Configure the context

LDContext context = LDContext.builder("example-context-key")
  .set("firstName", "Sandy")
  .set("lastName", "Smith")
  .set("email", "sandy@example.com")
  .build();

​

Customize a config

​

Customize configs in completion mode

• AgentControl config key
• Context
• Fallback value
• Optional variables

Map<String, Object> variables = new HashMap<>();
variables.put("username", "Sandy");

AICompletionConfig config = aiClient.completionConfig(
  "example-config-key",
  context,
  AICompletionConfigDefault.disabled(),
  variables
);

LDAIConfigTracker tracker = config.createTracker();

​

Customize configs in agent mode

Map<String, Object> variables = new HashMap<>();
variables.put("topic", "climate change");

AIAgentConfig agent = aiClient.agentConfig(
  "example-config-key",
  context,
  AIAgentConfigDefault.disabled(),
  variables
);

​

Retrieve a judge config

​

Retrieve a config without interpolating placeholders

​

Evaluate output manually with a judge

1. Retrieve the judge config with judgeConfig.
2. Implement Runner, a single-method interface that wraps whatever model provider SDK you use, so the SDK can invoke your model when it runs a judge prompt. The SDK does not ship provider-specific Runner implementations, so you write your own for whatever provider you use.
3. Construct a Judge by passing the judge config, your Runner implementation, and a logger to the Judge constructor.
4. Call evaluate on the Judge to score an input and output pair. The evaluate method takes the input, the output, and an optional sampling rate, and returns a JudgeResult with the score and reasoning.
5. Record the result with the tracker’s trackJudgeResult method.

AIJudgeConfig judgeConfig = aiClient.judgeConfig(
  "example-judge-key",
  context,
  AIJudgeConfigDefault.disabled(),
  variables
);

if (judgeConfig.isEnabled()) {
  Judge judge = new Judge(judgeConfig, runner, logger);
  JudgeResult result = judge.evaluate(inputText, outputText);

  // Record the result against the tracker for the completion or agent config
  // whose output you are evaluating, so the score is associated with that run.
  tracker.trackJudgeResult(result);
}

​

Call the provider and record metrics from AI model generation

1. Check config.isEnabled() before generating, and skip generation for the disabled case.
2. Create a tracker with config.createTracker().
3. Wrap your provider call in trackDurationOf to record its duration. Alternatively, call the individual track* methods directly, such as trackTimeToFirstToken, trackToolCall, or trackFeedback.
4. Record token usage with trackTokens.
5. Record the outcome with trackSuccess or trackError.

if (config.isEnabled()) {
  LDAIConfigTracker tracker = config.createTracker();

  Response response = tracker.trackDurationOf(() -> {
    // Make a request to your generative AI provider, using details from
    // the config. For example, pass config.getModel() and config.getMessages().
    return callProvider();
  });

  tracker.trackTokens(new TokenUsage(response.getTotalTokens(), response.getInputTokens(), response.getOutputTokens()));
  tracker.trackSuccess();
}

​

Agent graphs

1. Call agentGraph with the graph key, a context, and any variables. The method returns an AgentGraphDefinition that exposes the graph’s topology and a tracker for recording invocation metrics.
2. Check graph.isEnabled() before walking the graph.
3. Create a tracker with graph.createTracker() to record invocation metrics.

Map<String, Object> variables = new HashMap<>();
variables.put("topic", "climate change");

AgentGraphDefinition graph = aiClient.agentGraph("example-graph-key", context, variables);

if (graph.isEnabled()) {
  AIGraphTracker tracker = graph.createTracker();
  // Walk the graph and invoke each agent's config.
}

• getKey(): The agent config key for this node.
• getConfig(): The AIAgentConfig for the node, with its instructions, model, tools, and other agent config properties.
• getEdges(): The outgoing GraphEdge list from this node. Each edge includes the target node key and a handoff map describing how to pass state to the next node.
• isTerminal(): Whether this node has no outgoing edges.

graph.traverse((node, ctx) -> {
  // Use node.getConfig() to call your AI provider, passing instructions and tools.
  // Read upstream results from ctx as needed.
  Object output = callModelForNode(node.getConfig(), ctx);

  // The return value is stored under node.getKey() for downstream nodes.
  return output;
}, new HashMap<>());

• 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.

​

Resume tracking across processes

1. In the original process, create the config and tracker as usual.
2. Call getResumptionToken on the tracker to get a token.
3. Persist or pass the token to the next process, through a job queue, database row, or message envelope.
4. In the receiving process, call aiClient.createTracker for a completion or agent tracker, or aiClient.createGraphTracker for an agent graph tracker, passing the token and a context. Both methods return a tracker that records to the same invocation as the original.

AICompletionConfig config = aiClient.completionConfig("example-config-key", context, fallbackConfig, variables);
LDAIConfigTracker tracker = config.createTracker();

// Hand off work to another process. Persist the resumption token so the
// receiving process can reconstruct the tracker.
String token = tracker.getResumptionToken();
enqueueBackgroundJob(token, context);

LDAIConfigTracker tracker = aiClient.createTracker(token, context);

​

Supported features

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