@launchdarkly/server-sdk-ai 0.20.0 → 1.0.1

package/dist/index.d.cts

@@ -21,6 +21,20 @@ interface LDJudgeResult {
     reasoning?: string;
 }
 
+/**
+ * Feedback about the generated content.
+ */
+declare enum LDFeedbackKind {
+    /**
+     * The sentiment was positive.
+     */
+    Positive = "positive",
+    /**
+     * The sentiment is negative.
+     */
+    Negative = "negative"
+}
+
 /**
  * Information about token usage.
  */
@@ -39,32 +53,6 @@ interface LDTokenUsage {
     output: number;
 }
 
-declare function createBedrockTokenUsage(data: {
-    totalTokens?: number;
-    inputTokens?: number;
-    outputTokens?: number;
-}): LDTokenUsage;
-
-declare function createOpenAiUsage(data: {
-    total_tokens?: number;
-    prompt_tokens?: number;
-    completion_tokens?: number;
-}): LDTokenUsage;
-
-/**
- * Feedback about the generated content.
- */
-declare enum LDFeedbackKind {
-    /**
-     * The sentiment was positive.
-     */
-    Positive = "positive",
-    /**
-     * The sentiment is negative.
-     */
-    Negative = "negative"
-}
-
 /**
  * Metrics information for AI operations that includes success status and token usage.
  * This class combines success/failure tracking with token usage metrics.
@@ -91,14 +79,6 @@ interface LDAIMetrics {
     durationMs?: number;
 }
 
-declare function createVercelAISDKTokenUsage(data: {
-    totalTokens?: number;
-    inputTokens?: number;
-    promptTokens?: number;
-    outputTokens?: number;
-    completionTokens?: number;
-}): LDTokenUsage;
-
 /**
  * Summary metrics returned in a ManagedResult or from LDAIConfigTracker.getSummary().
  * Provides a flat view of the key metrics for the completed operation.
@@ -189,7 +169,13 @@ interface ManagedResult {
 }
 
 /**
- * The LDAIConfigTracker is used to track various details about AI operations.
+ * The LDAIConfigTracker records metrics for a single AI run.
+ *
+ * All events a tracker emits share a runId (a UUIDv4) so LaunchDarkly can
+ * correlate them in metrics views. See individual track methods for their
+ * specific semantics. Call `createTracker` on the AI Config to start a new
+ * run. A resumption token preserves the runId, so events emitted by a
+ * tracker reconstructed in another process correlate with the original run.
  */
 interface LDAIConfigTracker {
     /**
@@ -208,51 +194,49 @@ interface LDAIConfigTracker {
      * A URL-safe Base64-encoded token that encodes the tracker's runId, configKey,
      * variationKey, and version. Pass this to AIClient.createTracker() to reconstruct
      * the tracker across process boundaries (e.g. for associating deferred feedback
-     * with the original invocation).
+     * with the original AI run).
      */
     readonly resumptionToken: string;
     /**
      * Track the duration of generation.
      *
-     * At-most-once per execution: subsequent calls on the same tracker are dropped
-     * with a warning. Use createTracker() on the config result to obtain a fresh
-     * tracker for a new execution.
-     *
      * Ideally this would not include overhead time such as network communication.
      *
      * @param durationMs The duration in milliseconds.
+     *
+     * @remarks Records at most once per Tracker; further calls are ignored.
      */
     trackDuration(durationMs: number): void;
     /**
      * Track information about token usage.
      *
-     * At-most-once per execution: subsequent calls on the same tracker are dropped
-     * with a warning.
-     *
      * @param tokens Token usage information.
+     *
+     * @remarks Records at most once per Tracker; further calls are ignored.
      */
     trackTokens(tokens: LDTokenUsage): void;
     /**
      * Generation was successful.
      *
-     * At-most-once per execution: subsequent calls (including trackError) on the
-     * same tracker are dropped with a warning.
+     * @remarks Records at most once per Tracker. trackSuccess and trackError share
+     * state; only one of the two can record per Tracker, and subsequent calls are
+     * ignored.
      */
     trackSuccess(): void;
     /**
      * An error was encountered during generation.
      *
-     * At-most-once per execution: subsequent calls (including trackSuccess) on the
-     * same tracker are dropped with a warning.
+     * @remarks Records at most once per Tracker. trackSuccess and trackError share
+     * state; only one of the two can record per Tracker, and subsequent calls are
+     * ignored.
      */
     trackError(): void;
     /**
      * Track sentiment about the generation.
      *
-     * At-most-once per execution: subsequent calls on the same tracker are dropped
-     * with a warning.
-     *
      * @param feedback Feedback about the generation.
+     *
+     * @remarks Records at most once per Tracker; further calls are ignored.
      */
     trackFeedback(feedback: {
         kind: LDFeedbackKind;
@@ -260,10 +244,9 @@ interface LDAIConfigTracker {
     /**
      * Track the time to first token for this generation.
      *
-     * At-most-once per execution: subsequent calls on the same tracker are dropped
-     * with a warning.
-     *
      * @param timeToFirstTokenMs The duration in milliseconds.
+     *
+     * @remarks Records at most once per Tracker; further calls are ignored.
      */
     trackTimeToFirstToken(timeToFirstTokenMs: number): void;
     /**
@@ -272,22 +255,31 @@ interface LDAIConfigTracker {
      * No event is emitted when the result was not sampled (result.sampled is false).
      *
      * @param result Judge result containing score, reasoning, and metadata
+     *
+     * @remarks May be called multiple times per Tracker; each call records the
+     * scores from the given response.
      */
     trackJudgeResult(result: LDJudgeResult): void;
     /**
      * Track a single tool invocation.
      *
      * @param toolKey The identifier of the tool that was invoked.
+     *
+     * @remarks May be called multiple times per Tracker; each call records the
+     * given tool call.
      */
     trackToolCall(toolKey: string): void;
     /**
      * Track multiple tool invocations.
      *
      * @param toolKeys The identifiers of the tools that were invoked.
+     *
+     * @remarks May be called multiple times per Tracker; each call records the
+     * given tool calls.
      */
     trackToolCalls(toolKeys: string[]): void;
     /**
-     * Track the duration of execution of the provided function.
+     * Track the duration of the provided function.
      *
      * If the provided function throws, then this method will also throw.
      * In the case the provided function throws, this function will still record the duration.
@@ -296,30 +288,38 @@ interface LDAIConfigTracker {
      *
      * @param func The function to track the duration of.
      * @returns The result of the function.
+     *
+     * @remarks Because each inner metric is at-most-once per Tracker, calling
+     * this twice on the same Tracker will run the inner function again but
+     * produce no additional metric events.
      */
     trackDurationOf(func: () => Promise<any>): Promise<any>;
     /**
      * Track metrics for a generic AI operation.
      *
-     * This function will track the duration of the operation, extract metrics using the provided
+     * This function will track the duration of the AI run, extract metrics using the provided
      * metrics extractor function, and track success or error status accordingly.
      *
      * If the provided function throws, then this method will also throw.
      * In the case the provided function throws, this function will record the duration and an error.
-     * A failed operation will not have any token usage data.
+     * A failed AI run will not have any token usage data.
+     *
+     * @param metricsExtractor Function that extracts LDAIMetrics from the AI run result
+     * @param func Function which executes the AI run
+     * @returns The result of the AI run
      *
-     * @param metricsExtractor Function that extracts LDAIMetrics from the operation result
-     * @param func Function which executes the operation
-     * @returns The result of the operation
+     * @remarks Subsequent calls re-run the inner function but emit only metrics
+     * not already recorded on this Tracker. Call createTracker on the AI Config
+     * to start a new run.
      */
     trackMetricsOf<TRes>(metricsExtractor: (result: TRes) => LDAIMetrics, func: () => Promise<TRes>): Promise<TRes>;
     /**
      * Track metrics for a streaming AI operation.
      *
-     * This function will track the duration of the operation, extract metrics using the provided
+     * This function will track the duration of the AI run, extract metrics using the provided
      * metrics extractor function, and track success or error status accordingly.
      *
-     * Unlike trackMetricsOf, this method is designed for streaming operations where:
+     * Unlike trackMetricsOf, this method is designed for streaming AI runs where:
      * - The stream is created and returned immediately (synchronously)
      * - Metrics are extracted asynchronously in the background once the stream completes
      * - Duration is tracked from stream creation to metrics extraction completion
@@ -333,69 +333,12 @@ interface LDAIConfigTracker {
      * @param streamCreator Function that creates and returns the stream (synchronous)
      * @param metricsExtractor Function that asynchronously extracts metrics from the stream
      * @returns The stream result (returned immediately, not a Promise)
-     */
-    trackStreamMetricsOf<TStream>(streamCreator: () => TStream, metricsExtractor: (stream: TStream) => Promise<LDAIMetrics>): TStream;
-    /**
-     * Track an OpenAI operation.
-     *
-     * This function will track the duration of the operation, the token usage, and the success or error status.
      *
-     * If the provided function throws, then this method will also throw.
-     * In the case the provided function throws, this function will record the duration and an error.
-     * A failed operation will not have any token usage data.
-     *
-     * @param func Function which executes the operation.
-     * @returns The result of the operation.
+     * @remarks Subsequent calls re-run the inner function but emit only metrics
+     * not already recorded on this Tracker. Call createTracker on the AI Config
+     * to start a new run.
      */
-    trackOpenAIMetrics<TRes extends {
-        usage?: {
-            total_tokens?: number;
-            prompt_tokens?: number;
-            completion_tokens?: number;
-        };
-    }>(func: () => Promise<TRes>): Promise<TRes>;
-    /**
-     * Track an operation which uses Bedrock.
-     *
-     * This function will track the duration of the operation, the token usage, and the success or error status.
-     *
-     * @param res The result of the Bedrock operation.
-     * @returns The input operation.
-     */
-    trackBedrockConverseMetrics<TRes extends {
-        $metadata: {
-            httpStatusCode?: number;
-        };
-        metrics?: {
-            latencyMs?: number;
-        };
-        usage?: {
-            inputTokens?: number;
-            outputTokens?: number;
-            totalTokens?: number;
-        };
-    }>(res: TRes): TRes;
-    /**
-     * Track a Vercel AI SDK generateText operation.
-     *
-     * This function will track the duration of the operation, the token usage, and the success or error status.
-     *
-     * If the provided function throws, then this method will also throw.
-     * In the case the provided function throws, this function will record the duration and an error.
-     * A failed operation will not have any token usage data.
-     *
-     * @param func Function which executes the operation.
-     * @returns The result of the operation.
-     */
-    trackVercelAISDKGenerateTextMetrics<TRes extends {
-        usage?: {
-            totalTokens?: number;
-            inputTokens?: number;
-            promptTokens?: number;
-            outputTokens?: number;
-            completionTokens?: number;
-        };
-    }>(func: () => Promise<TRes>): Promise<TRes>;
+    trackStreamMetricsOf<TStream>(streamCreator: () => TStream, metricsExtractor: (stream: TStream) => Promise<LDAIMetrics>): TStream;
     /**
      * Get a summary of the tracked metrics.
      */
@@ -503,9 +446,10 @@ interface LDAIConfig extends Omit<LDAIConfigDefault, 'enabled'> {
      */
     enabled: boolean;
     /**
-     * Creates a new tracker for this AI Config invocation. Each call returns a
-     * new tracker with a fresh runId. Use createTracker() at the start of each
-     * execution to obtain a tracker, then use it to record metrics for that run.
+     * Creates a new tracker for a fresh AI run. Each call mints a new runId (a
+     * UUIDv4) that LaunchDarkly uses to correlate the run's events in metrics
+     * views. Call this once per AI run; metrics from different runIds cannot be
+     * combined.
      */
     createTracker: () => LDAIConfigTracker;
 }
@@ -562,12 +506,6 @@ interface LDAIJudgeConfigDefault extends LDAIConfigDefault {
      * The key of the metric that this judge can evaluate.
      */
     evaluationMetricKey?: string;
-    /**
-     * Evaluation metric keys for judge configurations (legacy).
-     * The keys of the metrics that this judge can evaluate.
-     * @deprecated Use evaluationMetricKey instead. This field is kept for legacy support.
-     */
-    evaluationMetricKeys?: string[];
 }
 /**
  * Union type for all default AI Config variants.
@@ -626,12 +564,6 @@ interface LDAIJudgeConfig extends LDAIConfig {
      * The key of the metric that this judge can evaluate.
      */
     evaluationMetricKey?: string;
-    /**
-     * Evaluation metric keys for judge configurations (legacy).
-     * The keys of the metrics that this judge can evaluate.
-     * @deprecated Use evaluationMetricKey instead. This field is kept for legacy support.
-     */
-    evaluationMetricKeys?: string[];
 }
 /**
  * Union type for all AI Config variants.
@@ -912,7 +844,13 @@ declare class ManagedModel {
 }
 
 /**
- * Tracks graph-level and edge-level metrics for an agent graph invocation.
+ * The LDGraphTracker records metrics for a single AI run of an agent graph.
+ *
+ * All events a graph tracker emits share a runId (a UUIDv4) so LaunchDarkly
+ * can correlate them in metrics views. Call `createTracker` on the agent
+ * graph to start a new run. A resumption token preserves the runId, so events
+ * emitted by a tracker reconstructed in another process correlate with the
+ * original run.
  *
  * Graph-level methods enforce at-most-once semantics: calling the same method
  * twice on a tracker instance drops the second call and emits a warning.
@@ -944,7 +882,7 @@ interface LDGraphTracker {
     /**
      * Returns a snapshot of all graph-level metrics tracked so far. Fields
      * populate incrementally as `track*` methods are called, so the result is
-     * a `Partial<LDAIGraphMetricSummary>`. Once the graph invocation has
+     * a `Partial<LDAIGraphMetricSummary>`. Once the graph run has
      * completed via `ManagedAgentGraph.run()`, prefer `ManagedGraphResult.metrics`
      * which is fully populated.
      */
@@ -960,19 +898,19 @@ interface LDGraphTracker {
      */
     readonly resumptionToken: string;
     /**
-     * Tracks a successful graph invocation.
+     * Tracks a successful graph run.
      * Emits event `$ld:ai:graph:invocation_success` with metric value `1`.
      * At-most-once: subsequent calls are dropped with a warning.
      */
     trackInvocationSuccess(): void;
     /**
-     * Tracks an unsuccessful graph invocation.
+     * Tracks an unsuccessful graph run.
      * Emits event `$ld:ai:graph:invocation_failure` with metric value `1`.
      * At-most-once: subsequent calls are dropped with a warning.
      */
     trackInvocationFailure(): void;
     /**
-     * Tracks the total duration of the graph execution in milliseconds.
+     * Tracks the total duration of the graph run in milliseconds.
      * Emits event `$ld:ai:graph:duration:total` with the duration as the metric value.
      * At-most-once: subsequent calls are dropped with a warning.
      *
@@ -980,7 +918,7 @@ interface LDGraphTracker {
      */
     trackDuration(durationMs: number): void;
     /**
-     * Tracks aggregate token usage across the entire graph invocation.
+     * Tracks aggregate token usage across the entire graph run.
      * Emits event `$ld:ai:graph:total_tokens` with the total token count as the metric value.
      * At-most-once: subsequent calls are dropped with a warning.
      *
@@ -988,12 +926,12 @@ interface LDGraphTracker {
      */
     trackTotalTokens(tokens: LDTokenUsage): void;
     /**
-     * Tracks the execution path through the graph.
+     * Tracks the path taken through the graph during this run.
      * Emits event `$ld:ai:graph:path` with metric value `1`.
      * The data payload includes the path array in addition to standard track data.
      * At-most-once: subsequent calls are dropped with a warning.
      *
-     * @param path An ordered array of agent config keys representing the execution path.
+     * @param path An ordered array of agent config keys representing the path taken.
      */
     trackPath(path: string[]): void;
     /**
@@ -1112,10 +1050,10 @@ declare class AgentGraphDefinition {
      */
     getConfig(): LDAgentGraphFlagValue;
     /**
-     * Returns a new {@link LDGraphTracker} for this graph invocation.
+     * Returns a new {@link LDGraphTracker} for a fresh graph run.
      *
-     * Call this once per invocation. Each call produces a tracker with a fresh `runId`
-     * that groups all events for that invocation.
+     * Call this once per graph run. Each call produces a tracker with a fresh `runId`
+     * that groups all events for that run.
      */
     createTracker(): LDGraphTracker;
     /**
@@ -1161,61 +1099,6 @@ declare class AgentGraphDefinition {
     static collectAllKeys(graph: LDAgentGraphFlagValue): Set<string>;
 }
 
-/**
- * ManagedAgentGraph wraps an AgentGraphDefinition and provides a managed run()
- * method that returns ManagedGraphResult with async judge evaluations.
- *
- * The runner function is responsible for executing the graph and returning
- * an AgentGraphRunnerResult. ManagedAgentGraph builds the managed result from
- * the runner result, including LDAIGraphMetricSummary with the graphTracker's
- * resumptionToken.
- */
-declare class ManagedAgentGraph {
-    private readonly _graphDefinition;
-    private readonly _logger?;
-    constructor(_graphDefinition: AgentGraphDefinition, _logger?: LDLogger$1 | undefined);
-    /**
-     * Runs the agent graph using the provided runner function and returns a ManagedGraphResult.
-     *
-     * The runner function receives the graph tracker and AgentGraphDefinition,
-     * executes the graph, and returns an AgentGraphRunnerResult.
-     *
-     * run() returns before ManagedGraphResult.evaluations resolves.
-     *
-     * @param runner Async function that executes the graph and returns AgentGraphRunnerResult.
-     * @returns ManagedGraphResult with LDAIGraphMetricSummary and evaluations promise.
-     */
-    run(runner: (graphDefinition: AgentGraphDefinition, graphTracker: LDGraphTracker) => Promise<AgentGraphRunnerResult>): Promise<ManagedGraphResult>;
-    /**
-     * Converts per-node LDAIMetrics from the runner into LDAIMetricSummary by
-     * creating a per-node tracker, firing tracking events, and calling getSummary().
-     */
-    private _trackNodeMetrics;
-    /**
-     * Returns the underlying AgentGraphDefinition.
-     */
-    getGraphDefinition(): AgentGraphDefinition;
-}
-
-/**
- * Chat response structure.
- */
-interface ChatResponse {
-    /**
-     * The response message from the AI.
-     */
-    message: LDMessage;
-    /**
-     * Metrics information including success status and token usage.
-     */
-    metrics: LDAIMetrics;
-    /**
-     * Promise that resolves to judge evaluation results.
-     * Only present when judges are configured for evaluation.
-     */
-    evaluations?: Promise<LDJudgeResult[]>;
-}
-
 /**
  * Judge implementation that handles evaluation functionality and conversation management.
  *
@@ -1234,8 +1117,7 @@ declare class Judge {
      */
     get sampleRate(): number;
     /**
-     * Gets the evaluation metric key, prioritizing evaluationMetricKey over evaluationMetricKeys.
-     * Falls back to the first valid (non-empty, non-whitespace) value in evaluationMetricKeys if evaluationMetricKey is not provided.
+     * Gets the evaluation metric key from the judge AI config.
      * Treats empty strings and whitespace-only strings as invalid.
      * @returns The evaluation metric key, or undefined if not available
      */
@@ -1252,15 +1134,19 @@ declare class Judge {
      */
     evaluate(input: string, output: string, samplingRate?: number): Promise<LDJudgeResult>;
     /**
-     * Evaluates an AI response from chat messages and response.
+     * Evaluates an AI response from chat messages and a runner result.
+     *
+     * Each message is rendered as `<role>: <content>` so the judge model can
+     * distinguish speakers in the message history. Messages are joined with a
+     * single newline.
      *
      * @param messages Array of messages representing the conversation history
-     * @param response The AI response to be evaluated
+     * @param response The runner result containing the AI-generated content to evaluate
      * @param samplingRatio Sampling ratio (0-1). When omitted, the Judge's
      *   constructor-default rate is used.
      * @returns Promise that resolves to evaluation results
      */
-    evaluateMessages(messages: LDMessage[], response: ChatResponse, samplingRatio?: number): Promise<LDJudgeResult>;
+    evaluateMessages(messages: LDMessage[], response: RunnerResult, samplingRatio?: number): Promise<LDJudgeResult>;
     /**
      * Returns the AI Config used by this judge.
      */
@@ -1312,10 +1198,14 @@ declare abstract class AIProvider {
      * Default implementation returns `undefined`.
      *
      * @param config The completion or judge AI configuration.
+     * @param multiTurn Whether the runner should accumulate conversation history
+     *   across successive `run()` calls. Defaults to `true` (chat semantics).
+     *   Pass `false` for stateless runners such as judges where each call must
+     *   start from the initial config messages.
      * @returns Promise resolving to a {@link Runner}, or `undefined` if this
      *   provider does not support model creation.
      */
-    createModel(_config: LDAICompletionConfig | LDAIJudgeConfig): Promise<Runner | undefined>;
+    createModel(_config: LDAICompletionConfig | LDAIJudgeConfig, _multiTurn?: boolean): Promise<Runner | undefined>;
     /**
      * Create a Runner for an agent AI Config.
      *
@@ -1407,10 +1297,14 @@ declare class RunnerFactory {
      *   ('openai', 'langchain', 'vercel', …). When set, only that provider is
      *   tried. When omitted, providers are tried in priority order based on the
      *   provider name in the config.
+     * @param multiTurn Whether the runner should accumulate conversation history
+     *   across successive `run()` calls. Defaults to `true` (chat semantics).
+     *   Judges pass `false` so each evaluation starts from the initial config
+     *   messages.
      * @returns A configured {@link Runner} ready to invoke the model, or
      *   `undefined` if no suitable provider could be loaded.
      */
-    static createModel(config: LDAICompletionConfig | LDAIJudgeConfig, logger?: LDLogger$1, defaultAiProvider?: SupportedAIProvider): Promise<Runner | undefined>;
+    static createModel(config: LDAICompletionConfig | LDAIJudgeConfig, logger?: LDLogger$1, defaultAiProvider?: SupportedAIProvider, multiTurn?: boolean): Promise<Runner | undefined>;
     /**
      * Create a Runner for an agent AI Config.
      *
@@ -1457,9 +1351,11 @@ interface LDAIClient {
      * the message content. The keys correspond to placeholders within the template, and the values
      * are the corresponding replacements.
      *
-     * @returns The AI `config`, customized `messages`, and a `tracker`. If the configuration cannot be accessed from
-     * LaunchDarkly, then the return value will include information from the `defaultValue`. The returned `tracker` can
-     * be used to track AI operation metrics (latency, token usage, etc.).
+     * @returns An {@link LDAICompletionConfig} with `enabled`, `model`, `provider`,
+     * `messages`, and a `createTracker()` factory. Call `createTracker()` on the
+     * returned config to obtain a tracker for each AI run. If the configuration
+     * cannot be accessed from LaunchDarkly, the return value will include
+     * information from the `defaultValue`.
      *
      * @example
      * ```
@@ -1472,35 +1368,15 @@ interface LDAIClient {
      *  provider: { name: 'openai' },
      * };
      *
-     * const result = completionConfig(key, context, defaultValue, variables);
-     * // Output:
-     * {
-     *   enabled: true,
-     *   config: {
-     *     modelId: "gpt-4o",
-     *     temperature: 0.2,
-     *     maxTokens: 4096,
-     *     userDefinedKey: "myValue",
-     *   },
-     *   messages: [
-     *     {
-     *       role: "system",
-     *       content: "You are an amazing GPT."
-     *     },
-     *     {
-     *       role: "user",
-     *       content: "Explain how you're an amazing GPT."
-     *     }
-     *   ],
-     *   tracker: ...
+     * const completionConfig = await client.completionConfig(key, context, defaultValue, variables);
+     * if (completionConfig.enabled) {
+     *   const tracker = completionConfig.createTracker();
+     *   // Use completionConfig.messages and completionConfig.model with your LLM,
+     *   // then record metrics with tracker.trackSuccess(), tracker.trackTokens(), etc.
      * }
      * ```
      */
     completionConfig(key: string, context: LDContext, defaultValue?: LDAICompletionConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<LDAICompletionConfig>;
-    /**
-     * @deprecated Use `completionConfig` instead. This method will be removed in a future version.
-     */
-    config(key: string, context: LDContext, defaultValue?: LDAICompletionConfigDefault, variables?: Record<string, unknown>): Promise<LDAICompletionConfig>;
     /**
      * Retrieves and processes a single AI Config agent based on the provided key, LaunchDarkly context,
      * and variables. This includes the model configuration and the customized instructions.
@@ -1515,9 +1391,11 @@ interface LDAIClient {
      * the instructions. The keys correspond to placeholders within the template, and the values
      * are the corresponding replacements.
      *
-     * @returns An AI agent with customized `instructions` and a `tracker`. If the configuration
-     * cannot be accessed from LaunchDarkly, then the return value will include information from the
-     * `defaultValue`. The returned `tracker` can be used to track AI operation metrics (latency, token usage, etc.).
+     * @returns An {@link LDAIAgentConfig} with customized `instructions`, `model`,
+     * `provider`, and a `createTracker()` factory. Call `createTracker()` on the
+     * returned config to obtain a tracker for each AI run. If the configuration
+     * cannot be accessed from LaunchDarkly, the return value will include
+     * information from the `defaultValue`.
      *
      * @example
      * ```
@@ -1531,15 +1409,14 @@ interface LDAIClient {
      *   instructions: 'You are a research assistant.',
      * }, variables);
      *
-     * const researchResult = agentConfig.instructions; // Interpolated instructions
-     * agentConfig.tracker.trackSuccess();
+     * if (agentConfig.enabled) {
+     *   const tracker = agentConfig.createTracker();
+     *   const researchResult = agentConfig.instructions; // Interpolated instructions
+     *   tracker.trackSuccess();
+     * }
      * ```
      */
     agentConfig(key: string, context: LDContext, defaultValue?: LDAIAgentConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<LDAIAgentConfig>;
-    /**
-     * @deprecated Use `agentConfig` instead. This method will be removed in a future version.
-     */
-    agent(key: string, context: LDContext, defaultValue?: LDAIAgentConfigDefault, variables?: Record<string, unknown>): Promise<LDAIAgentConfig>;
     /**
      * Retrieves and processes a Judge AI Config based on the provided key, LaunchDarkly context,
      * and variables. This includes the model configuration and the customized messages for evaluation.
@@ -1551,7 +1428,10 @@ interface LDAIClient {
      * @param defaultValue Optional fallback when the configuration is not available from LaunchDarkly.
      * When omitted or null, a disabled default is used.
      * @param variables Optional variables for template interpolation in messages and instructions.
-     * @returns A promise that resolves to a tracked judge configuration.
+     * @returns A promise that resolves to an {@link LDAIJudgeConfig} with `enabled`,
+     * `model`, `provider`, `messages`, `evaluationMetricKey`, and a `createTracker()`
+     * factory. Call `createTracker()` on the returned config to obtain a tracker for
+     * each AI run.
      *
      * @example
      * ```typescript
@@ -1563,8 +1443,11 @@ interface LDAIClient {
      *   messages: [{ role: 'system', content: 'You are a relevance judge.' }]
      * }, variables);
      *
-     * const config = judgeConf.config; // Interpolated configuration
-     * judgeConf.tracker.trackSuccess();
+     * if (judgeConf.enabled) {
+     *   const tracker = judgeConf.createTracker();
+     *   // Use judgeConf.messages and judgeConf.model with your LLM,
+     *   // then record metrics with tracker.trackSuccess(), tracker.trackJudgeResult(), etc.
+     * }
      * ```
      */
     judgeConfig(key: string, context: LDContext, defaultValue?: LDAIJudgeConfigDefault, variables?: Record<string, unknown>): Promise<LDAIJudgeConfig>;
@@ -1578,10 +1461,11 @@ interface LDAIClient {
      * current environment, user, or session. This context may influence how the configuration is
      * processed or personalized.
      *
-     * @returns A map of agent keys to their respective AI agents with customized `instructions` and `tracker`.
-     * If a configuration cannot be accessed from LaunchDarkly, then the return value will include information
-     * from the respective `defaultValue`. The returned `tracker` can be used to track AI operation metrics
-     * (latency, token usage, etc.).
+     * @returns A map of agent keys to their respective {@link LDAIAgentConfig}s,
+     * each with customized `instructions` and a `createTracker()` factory. Call
+     * `createTracker()` on a returned config to obtain a tracker for each AI run.
+     * If a configuration cannot be accessed from LaunchDarkly, the return value
+     * will include information from the respective `defaultValue`.
      *
      * @example
      * ```
@@ -1610,15 +1494,14 @@ interface LDAIClient {
      * const context = {...};
      *
      * const configs = await client.agentConfigs(agentConfigsList, context);
-     * const researchResult = configs["research_agent"].instructions; // Interpolated instructions
-     * configs["research_agent"].tracker.trackSuccess();
+     * if (configs["research_agent"].enabled) {
+     *   const tracker = configs["research_agent"].createTracker();
+     *   const researchResult = configs["research_agent"].instructions; // Interpolated instructions
+     *   tracker.trackSuccess();
+     * }
      * ```
      */
     agentConfigs<const T extends readonly LDAIAgentRequestConfig[]>(agentConfigs: T, context: LDContext): Promise<Record<T[number]['key'], LDAIAgentConfig>>;
-    /**
-     * @deprecated Use `agentConfigs` instead. This method will be removed in a future version.
-     */
-    agents<const T extends readonly LDAIAgentRequestConfig[]>(agentConfigs: T, context: LDContext): Promise<Record<T[number]['key'], LDAIAgentConfig>>;
     /**
      * Creates and returns a new ManagedModel instance for LLM model interactions.
      *
@@ -1666,14 +1549,6 @@ interface LDAIClient {
      * @returns A promise that resolves to the ManagedAgent instance, or undefined if disabled.
      */
     createAgent(key: string, context: LDContext, defaultValue?: LDAIAgentConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<ManagedAgent | undefined>;
-    /**
-     * @deprecated Use `createModel` instead. This method will be removed in a future version.
-     */
-    createChat(key: string, context: LDContext, defaultValue?: LDAICompletionConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<ManagedModel | undefined>;
-    /**
-     * @deprecated Use `createModel` instead. This method will be removed in a future version.
-     */
-    initChat(key: string, context: LDContext, defaultValue?: LDAICompletionConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<ManagedModel | undefined>;
     /**
      * Creates and returns a new Judge instance for AI evaluation.
      *
@@ -1713,7 +1588,7 @@ interface LDAIClient {
     /**
      * Reconstructs an AIConfigTracker from a resumption token string previously
      * obtained from a tracker's `resumptionToken` property. Use this to associate
-     * deferred events (such as user feedback) with the original invocation's runId.
+     * deferred events (such as user feedback) with the original tracker's runId.
      *
      * @param token A URL-safe Base64-encoded resumption token string.
      * @param context The evaluation context to use for subsequent track calls.
@@ -1777,6 +1652,42 @@ interface LDClientMin {
     readonly logger?: LDLogger$1;
 }
 
+/**
+ * ManagedAgentGraph wraps an AgentGraphDefinition and provides a managed run()
+ * method that returns ManagedGraphResult with async judge evaluations.
+ *
+ * The runner function is responsible for executing the graph and returning
+ * an AgentGraphRunnerResult. ManagedAgentGraph builds the managed result from
+ * the runner result, including LDAIGraphMetricSummary with the graphTracker's
+ * resumptionToken.
+ */
+declare class ManagedAgentGraph {
+    private readonly _graphDefinition;
+    private readonly _logger?;
+    constructor(_graphDefinition: AgentGraphDefinition, _logger?: LDLogger$1 | undefined);
+    /**
+     * Runs the agent graph using the provided runner function and returns a ManagedGraphResult.
+     *
+     * The runner function receives the graph tracker and AgentGraphDefinition,
+     * executes the graph, and returns an AgentGraphRunnerResult.
+     *
+     * run() returns before ManagedGraphResult.evaluations resolves.
+     *
+     * @param runner Async function that executes the graph and returns AgentGraphRunnerResult.
+     * @returns ManagedGraphResult with LDAIGraphMetricSummary and evaluations promise.
+     */
+    run(runner: (graphDefinition: AgentGraphDefinition, graphTracker: LDGraphTracker) => Promise<AgentGraphRunnerResult>): Promise<ManagedGraphResult>;
+    /**
+     * Converts per-node LDAIMetrics from the runner into LDAIMetricSummary by
+     * creating a per-node tracker, firing tracking events, and calling getSummary().
+     */
+    private _trackNodeMetrics;
+    /**
+     * Returns the underlying AgentGraphDefinition.
+     */
+    getGraphDefinition(): AgentGraphDefinition;
+}
+
 /**
  * Concrete implementation of {@link LDGraphTracker}.
  *
@@ -1839,4 +1750,4 @@ declare class LDGraphTrackerImpl implements LDGraphTracker {
 declare function initAi(ldClient: LDClientMin): LDAIClient;
 type LDLogger = common.LDLogger;
 
-export { AIProvider, AgentGraphDefinition, AgentGraphNode, type AgentGraphRunner, type AgentGraphRunnerResult, type ChatResponse, Judge, type LDAIAgentConfig, type LDAIAgentConfigDefault, type LDAIAgentRequestConfig, type LDAIClient, type LDAICompletionConfig, type LDAICompletionConfigDefault, type LDAIConfig, type LDAIConfigDefault, type LDAIConfigDefaultKind, type LDAIConfigKind, type LDAIConfigMode, type LDAIConfigTracker, type LDAIGraphMetricSummary, type LDAIGraphMetrics, type LDAIJudgeConfig, type LDAIJudgeConfigDefault, type LDAIMetricSummary, type LDAIMetrics, type LDAgentGraphFlagValue, LDFeedbackKind, type LDGraphEdge, type LDGraphTrackData, type LDGraphTracker, LDGraphTrackerImpl, type LDJudge, type LDJudgeConfiguration, type LDJudgeResult, type LDLogger, type LDMessage, type LDModelConfig, type LDProviderConfig, type LDTokenUsage, type LDTool, ManagedAgent, ManagedAgentGraph, type ManagedGraphResult, ManagedModel, type ManagedResult, type Runner, RunnerFactory, type RunnerResult, SUPPORTED_AI_PROVIDERS, type SupportedAIProvider, type ToolRegistry, type TraversalFn, createBedrockTokenUsage, createOpenAiUsage, createVercelAISDKTokenUsage, initAi };
+export { AIProvider, AgentGraphDefinition, AgentGraphNode, type AgentGraphRunner, type AgentGraphRunnerResult, Judge, type LDAIAgentConfig, type LDAIAgentConfigDefault, type LDAIAgentRequestConfig, type LDAIClient, type LDAICompletionConfig, type LDAICompletionConfigDefault, type LDAIConfig, type LDAIConfigDefault, type LDAIConfigDefaultKind, type LDAIConfigKind, type LDAIConfigMode, type LDAIConfigTracker, type LDAIGraphMetricSummary, type LDAIGraphMetrics, type LDAIJudgeConfig, type LDAIJudgeConfigDefault, type LDAIMetricSummary, type LDAIMetrics, type LDAgentGraphFlagValue, LDFeedbackKind, type LDGraphEdge, type LDGraphTrackData, type LDGraphTracker, LDGraphTrackerImpl, type LDJudge, type LDJudgeConfiguration, type LDJudgeResult, type LDLogger, type LDMessage, type LDModelConfig, type LDProviderConfig, type LDTokenUsage, type LDTool, ManagedAgent, ManagedAgentGraph, type ManagedGraphResult, ManagedModel, type ManagedResult, type Runner, RunnerFactory, type RunnerResult, SUPPORTED_AI_PROVIDERS, type SupportedAIProvider, type ToolRegistry, type TraversalFn, initAi };