@launchdarkly/server-sdk-ai 0.19.1 → 1.0.0

package/dist/index.d.ts

@@ -1,6 +1,40 @@
 import * as common from '@launchdarkly/js-server-sdk-common';
 import { LDLogger as LDLogger$1, LDContext, LDFlagValue } from '@launchdarkly/js-server-sdk-common';
 
+/**
+ * Result from a judge evaluation containing score, reasoning, and metadata.
+ */
+interface LDJudgeResult {
+    /** The key of the judge configuration that was used to generate this result */
+    judgeConfigKey?: string;
+    /** Whether the evaluation completed successfully */
+    success: boolean;
+    /** Error message if evaluation failed */
+    errorMessage?: string;
+    /** Whether this evaluation was sampled (i.e. actually run). False when skipped by sampling. */
+    sampled: boolean;
+    /** The metric key for this evaluation */
+    metricKey?: string;
+    /** Score between 0.0 and 1.0 indicating the evaluation result */
+    score?: number;
+    /** Reasoning behind the provided score */
+    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.
  */
@@ -32,105 +66,116 @@ interface LDAIMetrics {
      * Token usage information for the operation.
      * This will be undefined if no token usage data is available.
      */
-    usage?: LDTokenUsage;
+    tokens?: LDTokenUsage;
+    /**
+     * List of tool call identifiers made during the operation.
+     * This will be undefined if no tool calls were made.
+     */
+    toolCalls?: string[];
+    /**
+     * Duration of the operation in milliseconds.
+     * This will be undefined if duration was not tracked.
+     */
+    durationMs?: number;
 }
 
 /**
- * Structured response from AI models.
+ * Summary metrics returned in a ManagedResult or from LDAIConfigTracker.getSummary().
+ * Provides a flat view of the key metrics for the completed operation.
  */
-interface StructuredResponse {
-    /** The structured data returned by the model */
-    data: Record<string, unknown>;
-    /** The raw response from the model */
-    rawResponse: string;
+interface LDAIMetricSummary {
     /**
-     * Metrics information including success status and token usage.
+     * Whether the AI operation was successful.
      */
-    metrics: LDAIMetrics;
-}
-/**
- * Result from a judge evaluation containing score, reasoning, and metadata.
- */
-interface LDJudgeResult {
-    /** The key of the judge configuration that was used to generate this result */
-    judgeConfigKey?: string;
-    /** Whether the evaluation completed successfully */
-    success: boolean;
-    /** Error message if evaluation failed */
-    errorMessage?: string;
-    /** Whether this evaluation was sampled (i.e. actually run). False when skipped by sampling. */
-    sampled: boolean;
-    /** The metric key for this evaluation */
-    metricKey?: string;
-    /** Score between 0.0 and 1.0 indicating the evaluation result */
-    score?: number;
-    /** Reasoning behind the provided score */
-    reasoning?: string;
+    success?: boolean;
+    /**
+     * Token usage information, if available.
+     */
+    tokens?: LDTokenUsage;
+    /**
+     * List of tool call identifiers made during the operation, if any.
+     */
+    toolCalls?: string[];
+    /**
+     * Duration of the operation in milliseconds, if tracked.
+     */
+    durationMs?: number;
+    /**
+     * Time to first token in milliseconds, if tracked.
+     */
+    timeToFirstTokenMs?: number;
+    /**
+     * User feedback sentiment for this generation, if provided.
+     */
+    feedback?: {
+        kind: LDFeedbackKind;
+    };
+    /**
+     * Resumption token for deferred feedback association.
+     */
+    resumptionToken?: string;
 }
-
-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.
+ * The result returned by a Runner (provider-level) invocation.
+ * Providers implement Runner and return RunnerResult from run().
+ * This type does NOT include evaluations — those are wired in the managed layer.
  */
-declare enum LDFeedbackKind {
+interface RunnerResult {
     /**
-     * The sentiment was positive.
+     * The text content of the model's response.
      */
-    Positive = "positive",
+    content: string;
     /**
-     * The sentiment is negative.
+     * Metrics information for the operation.
      */
-    Negative = "negative"
+    metrics: LDAIMetrics;
+    /**
+     * The raw response object from the provider, if available.
+     */
+    raw?: unknown;
+    /**
+     * Parsed structured output, if the provider returned structured data.
+     */
+    parsed?: Record<string, unknown>;
 }
-
-declare function createVercelAISDKTokenUsage(data: {
-    totalTokens?: number;
-    inputTokens?: number;
-    promptTokens?: number;
-    outputTokens?: number;
-    completionTokens?: number;
-}): LDTokenUsage;
-
 /**
- * Metrics which have been tracked.
+ * The result returned by a managed model invocation (ManagedModel.run()).
+ * Includes a promise for asynchronous judge evaluations.
  */
-interface LDAIMetricSummary {
+interface ManagedResult {
     /**
-     * The duration of generation.
+     * The text content of the model's response.
      */
-    durationMs?: number;
+    content: string;
     /**
-     * Information about token usage.
+     * Summarized metrics for this invocation.
      */
-    tokens?: LDTokenUsage;
+    metrics: LDAIMetricSummary;
     /**
-     * Was generation successful.
+     * The raw response object from the provider, if available.
      */
-    success?: boolean;
+    raw?: unknown;
     /**
-     * Any sentiment about the generation.
+     * Parsed structured output, if available.
      */
-    feedback?: {
-        kind: LDFeedbackKind;
-    };
+    parsed?: Record<string, unknown>;
     /**
-     * Time to first token for this generation.
+     * Promise that resolves to the judge evaluation results.
+     * This promise encapsulates both evaluation and tracking
+     * (tracker.trackJudgeResult is called when it resolves).
+     * Awaiting this promise guarantees both evaluation and tracking are complete.
      */
-    timeToFirstTokenMs?: number;
+    evaluations: Promise<LDJudgeResult[]>;
 }
+
 /**
- * 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 {
     /**
@@ -149,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;
@@ -201,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;
     /**
@@ -213,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.
@@ -237,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 operation result
-     * @param func Function which executes the operation
-     * @returns The result of the operation
+     * @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
+     *
+     * @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
@@ -274,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.
-     */
-    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.
+     * @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.
      */
-    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.
      */
@@ -444,11 +446,12 @@ 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;
+    createTracker: () => LDAIConfigTracker;
 }
 /**
  * Default Agent-specific AI Config with instructions.
@@ -503,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.
@@ -567,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.
@@ -601,244 +592,136 @@ interface LDAIAgentRequestConfig {
 type LDAIConfigMode = 'completion' | 'agent' | 'judge';
 
 /**
- * Chat response structure.
+ * Represents a directed edge in an agent graph, connecting a source node to a target node.
  */
-interface ChatResponse {
-    /**
-     * The response message from the AI.
-     */
-    message: LDMessage;
+interface LDGraphEdge {
     /**
-     * Metrics information including success status and token usage.
+     * The key of the target AIAgentConfig node.
      */
-    metrics: LDAIMetrics;
+    key: string;
     /**
-     * Promise that resolves to judge evaluation results.
-     * Only present when judges are configured for evaluation.
+     * Optional handoff options that customize how data flows between nodes.
      */
-    evaluations?: Promise<LDJudgeResult[]>;
+    handoff?: Record<string, unknown>;
 }
-
 /**
- * Abstract base class for AI providers that implement chat model functionality.
- * This class provides the contract that all provider implementations must follow
- * to integrate with LaunchDarkly's tracking and configuration capabilities.
- *
- * Following the AICHAT spec recommendation to use base classes with non-abstract methods
- * for better extensibility and backwards compatibility.
+ * Raw flag value for an agent graph configuration as returned by LaunchDarkly.
+ * This represents the data structure delivered by LaunchDarkly for graph configurations.
  */
-declare abstract class AIProvider {
-    protected readonly logger?: LDLogger$1;
-    constructor(logger?: LDLogger$1);
-    /**
-     * Invoke the chat model with an array of messages.
-     * This method should convert messages to provider format, invoke the model,
-     * and return a ChatResponse with the result and metrics.
-     *
-     * Default implementation takes no action and returns a placeholder response.
-     * Provider implementations should override this method.
-     *
-     * @param messages Array of LDMessage objects representing the conversation
-     * @returns Promise that resolves to a ChatResponse containing the model's response
-     */
-    invokeModel(_messages: LDMessage[]): Promise<ChatResponse>;
+interface LDAgentGraphFlagValue {
+    _ldMeta?: {
+        variationKey?: string;
+        version?: number;
+        enabled?: boolean;
+    };
     /**
-     * Invoke the chat model with structured output support.
-     * This method should convert messages to provider format, invoke the model with
-     * structured output configuration, and return a structured response.
-     *
-     * Default implementation takes no action and returns a placeholder response.
-     * Provider implementations should override this method.
-     *
-     * @param messages Array of LDMessage objects representing the conversation
-     * @param responseStructure Dictionary of output configurations keyed by output name
-     * @returns Promise that resolves to a structured response
+     * The key of the root AIAgentConfig in the graph.
      */
-    invokeStructuredModel(_messages: LDMessage[], _responseStructure: Record<string, unknown>): Promise<StructuredResponse>;
+    root: string;
     /**
-     * Static method that constructs an instance of the provider.
-     * Each provider implementation must provide their own static create method
-     * that accepts an AIConfig and returns a configured instance.
-     *
-     * @param aiConfig The LaunchDarkly AI configuration
-     * @param logger Optional logger for the provider
-     * @returns Promise that resolves to a configured provider instance
+     * Object mapping source agent config keys to arrays of target edges.
      */
-    static create(aiConfig: LDAIConfigKind, logger?: LDLogger$1): Promise<AIProvider>;
+    edges?: Record<string, LDGraphEdge[]>;
 }
-
 /**
- * Judge implementation that handles evaluation functionality and conversation management.
+ * Summarized graph-level metrics for a completed graph invocation, as
+ * returned by {@link ManagedAgentGraph.run} via {@link ManagedGraphResult.metrics}.
  *
- * According to the AIEval spec, judges are AI Configs with mode: "judge" that evaluate
- * other AI Configs using structured output.
+ * For the tracker-layer incremental view (where fields populate as tracking
+ * calls arrive), see {@link LDGraphTracker.getSummary}, which returns a
+ * `Partial<LDAIGraphMetricSummary>`.
  */
-declare class Judge {
-    private readonly _aiConfig;
-    private readonly _aiProvider;
-    private readonly _logger?;
-    constructor(_aiConfig: LDAIJudgeConfig, _aiProvider: AIProvider, logger?: LDLogger$1);
+interface LDAIGraphMetricSummary {
     /**
-     * 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.
-     * Treats empty strings and whitespace-only strings as invalid.
-     * @returns The evaluation metric key, or undefined if not available
+     * Whether the graph invocation succeeded.
      */
-    private _getEvaluationMetricKey;
-    /**
-     * Evaluates an AI response using the judge's configuration.
-     *
-     * @param input The input prompt or question that was provided to the AI
-     * @param output The AI-generated response to be evaluated
-     * @param samplingRate Sampling rate (0-1) to determine if evaluation should be processed (defaults to 1)
-     * @returns Promise that resolves to evaluation results
-     */
-    evaluate(input: string, output: string, samplingRate?: number): Promise<LDJudgeResult>;
-    /**
-     * Evaluates an AI response from chat messages and response.
-     *
-     * @param messages Array of messages representing the conversation history
-     * @param response The AI response to be evaluated
-     * @param samplingRatio Sampling ratio (0-1) to determine if evaluation should be processed (defaults to 1)
-     * @returns Promise that resolves to evaluation results
-     */
-    evaluateMessages(messages: LDMessage[], response: ChatResponse, samplingRatio?: number): Promise<LDJudgeResult>;
+    success: boolean;
     /**
-     * Returns the AI Config used by this judge.
+     * Execution path through the graph as an ordered array of config keys.
      */
-    getAIConfig(): LDAIJudgeConfig;
+    path: string[];
     /**
-     * Returns the AI provider used by this judge.
+     * Per-node metric summaries keyed by agent config key.
      */
-    getProvider(): AIProvider;
+    nodeMetrics: Record<string, LDAIMetricSummary>;
     /**
-     * Constructs evaluation messages by combining judge's config messages with input/output.
+     * Total graph execution duration in milliseconds, if tracked.
      */
-    private _constructEvaluationMessages;
+    durationMs?: number;
     /**
-     * Interpolates message content with variables using Mustache templating.
+     * Aggregate token usage across the entire graph invocation, if available.
      */
-    private _interpolateMessage;
+    tokens?: LDTokenUsage;
     /**
-     * Parses the structured evaluation response. Expects top-level {score, reasoning}.
-     * Returns score and reasoning, or undefined if parsing fails.
+     * Resumption token for deferred feedback association.
      */
-    private _parseEvaluationResponse;
+    resumptionToken?: string;
 }
-
 /**
- * Concrete implementation of TrackedChat that provides chat functionality
- * by delegating to an AIProvider implementation.
- * This class handles conversation management and tracking, while delegating
- * the actual model invocation to the provider.
+ * Graph-level metrics for a completed graph run, as returned by a graph runner.
+ * Does NOT include handoffs or evaluations — those are managed-layer concerns.
  */
-declare class TrackedChat {
-    protected readonly aiConfig: LDAICompletionConfig;
-    protected readonly provider: AIProvider;
-    protected readonly judges: Record<string, Judge>;
-    private readonly _logger?;
-    protected messages: LDMessage[];
-    constructor(aiConfig: LDAICompletionConfig, provider: AIProvider, judges?: Record<string, Judge>, _logger?: LDLogger$1 | undefined);
-    /**
-     * Invoke the chat model with a prompt string.
-     * This method handles conversation management and tracking, delegating to the provider's invokeModel method.
-     */
-    invoke(prompt: string): Promise<ChatResponse>;
+interface LDAIGraphMetrics {
     /**
-     * Evaluates the response with all configured judges.
-     * Returns a promise that resolves to an array of evaluation results.
-     *
-     * @param messages Array of messages representing the conversation history
-     * @param response The AI response to be evaluated
-     * @returns Promise resolving to array of judge evaluation results
-     */
-    private _evaluateWithJudges;
-    /**
-     * Get the underlying AI configuration used to initialize this TrackedChat.
+     * Whether the graph invocation succeeded.
      */
-    getConfig(): LDAICompletionConfig;
+    success: boolean;
     /**
-     * Get the underlying AI provider instance.
-     * This provides direct access to the provider for advanced use cases.
+     * Execution path through the graph as an ordered array of config keys.
      */
-    getProvider(): AIProvider;
+    path: string[];
     /**
-     * Get the judges associated with this TrackedChat.
-     * Returns a record of judge instances keyed by their configuration keys.
+     * Total graph execution duration in milliseconds, if tracked.
      */
-    getJudges(): Record<string, Judge>;
+    durationMs?: number;
     /**
-     * Append messages to the conversation history.
-     * Adds messages to the conversation history without invoking the model,
-     * which is useful for managing multi-turn conversations or injecting context.
-     *
-     * @param messages Array of messages to append to the conversation history
+     * Aggregate token usage across the entire graph invocation, if available.
      */
-    appendMessages(messages: LDMessage[]): void;
+    tokens?: LDTokenUsage;
     /**
-     * Get all messages in the conversation history.
-     *
-     * @param includeConfigMessages Whether to include the config messages from the AIConfig.
-     *                              Defaults to false.
-     * @returns Array of messages. When includeConfigMessages is true, returns both config
-     *          messages and conversation history with config messages prepended. When false,
-     *          returns only the conversation history messages.
+     * Per-node metrics keyed by agent config key.
      */
-    getMessages(includeConfigMessages?: boolean): LDMessage[];
+    nodeMetrics: Record<string, LDAIMetrics>;
 }
-
 /**
- * Represents a directed edge in an agent graph, connecting a source node to a target node.
+ * The result returned by a graph runner invocation (provider-level).
+ * Does NOT include evaluations or handoffs.
  */
-interface LDGraphEdge {
+interface AgentGraphRunnerResult {
     /**
-     * The key of the target AIAgentConfig node.
+     * The text content of the graph's final response.
      */
-    key: string;
-    /**
-     * Optional handoff options that customize how data flows between nodes.
-     */
-    handoff?: Record<string, unknown>;
-}
-/**
- * Raw flag value for an agent graph configuration as returned by LaunchDarkly.
- * This represents the data structure delivered by LaunchDarkly for graph configurations.
- */
-interface LDAgentGraphFlagValue {
-    _ldMeta?: {
-        variationKey?: string;
-        version?: number;
-        enabled?: boolean;
-    };
+    content: string;
     /**
-     * The key of the root AIAgentConfig in the graph.
+     * Graph-level metrics for this invocation.
      */
-    root: string;
+    metrics: LDAIGraphMetrics;
     /**
-     * Object mapping source agent config keys to arrays of target edges.
+     * The raw response object from the provider, if available.
      */
-    edges?: Record<string, LDGraphEdge[]>;
+    raw?: unknown;
 }
 /**
- * Accumulated graph-level metrics collected by an LDGraphTracker.
+ * The result returned by a managed graph invocation (ManagedAgentGraph.run()).
  */
-interface LDGraphMetricSummary {
+interface ManagedGraphResult {
     /**
-     * Whether the graph invocation succeeded. Absent if not yet tracked.
+     * The text content of the graph's final response.
      */
-    success?: boolean;
+    content: string;
     /**
-     * Total graph execution duration in milliseconds. Absent if not yet tracked.
+     * Summarized metrics for this graph invocation.
      */
-    durationMs?: number;
+    metrics: LDAIGraphMetricSummary;
     /**
-     * Aggregate token usage across the entire graph invocation. Absent if not yet tracked.
+     * The raw response object from the provider, if available.
      */
-    tokens?: LDTokenUsage;
+    raw?: unknown;
     /**
-     * Execution path through the graph as an array of config keys. Absent if not yet tracked.
+     * Promise that resolves to the judge evaluation results.
+     * Awaiting this promise guarantees both evaluation and tracking are complete.
      */
-    path?: string[];
+    evaluations: Promise<LDJudgeResult[]>;
 }
 /**
  * Tracking metadata returned by {@link LDGraphTracker.getTrackData}.
@@ -863,7 +746,111 @@ interface LDGraphTrackData {
 }
 
 /**
- * Tracks graph-level and edge-level metrics for an agent graph invocation.
+ * Runner protocol for AI model providers.
+ *
+ * A single Runner interface covers completion, agent, and judge use cases.
+ * For structured output (e.g., judge evaluation), pass an `outputType` schema
+ * and access the parsed result via `RunnerResult.parsed`.
+ */
+interface Runner {
+    /**
+     * Invoke the model with the given input string.
+     *
+     * @param input The string input to the model.
+     * @param outputType Optional JSON schema for structured output. When provided,
+     *   the model should return structured data accessible via `RunnerResult.parsed`.
+     * @returns Promise resolving to a RunnerResult.
+     */
+    run(input: string, outputType?: Record<string, unknown>): Promise<RunnerResult>;
+}
+/**
+ * Runner protocol for agent graph providers.
+ *
+ * Providers implementing AgentGraphRunner can execute an entire agent graph
+ * and return a structured AgentGraphRunnerResult.
+ */
+interface AgentGraphRunner {
+    /**
+     * Execute the agent graph with the given input.
+     *
+     * @param input The user input to process through the graph.
+     * @returns Promise resolving to an AgentGraphRunnerResult.
+     */
+    run(input: string): Promise<AgentGraphRunnerResult>;
+}
+
+/**
+ * ManagedAgent provides agent invocation with automatic tracking and automatic
+ * judge evaluation.
+ *
+ * The class is stateless: each `run()` call sends the prompt directly to the
+ * underlying `Runner` and returns a `ManagedResult`. Conversation history,
+ * if any, must be managed by the caller (or by the Runner implementation).
+ *
+ * Obtain an instance via `LDAIClient.createAgent()`.
+ */
+declare class ManagedAgent {
+    protected readonly aiAgentConfig: LDAIAgentConfig;
+    protected readonly runner: Runner;
+    private readonly _logger?;
+    constructor(aiAgentConfig: LDAIAgentConfig, runner: Runner, _logger?: LDLogger$1 | undefined);
+    /**
+     * Invoke the agent with a prompt string and return a ManagedResult.
+     *
+     * `run()` resolves before `ManagedResult.evaluations` resolves. Awaiting
+     * `evaluations` guarantees both judge evaluation and tracker.trackJudgeResult()
+     * are complete.
+     *
+     * @param prompt The user input to send to the agent.
+     * @returns Promise resolving to ManagedResult (before evaluations settle).
+     */
+    run(prompt: string): Promise<ManagedResult>;
+    /**
+     * Get the underlying AI agent configuration used to initialize this ManagedAgent.
+     */
+    getConfig(): LDAIAgentConfig;
+}
+
+/**
+ * ManagedModel provides chat-completion invocation with automatic tracking and
+ * automatic judge evaluation.
+ *
+ * The class is stateless: each `run()` call sends the prompt directly to the
+ * underlying `Runner` and returns a `ManagedResult`. Conversation history,
+ * if any, must be managed by the caller (or by the Runner implementation).
+ *
+ * Obtain an instance via `LDAIClient.createModel()`.
+ */
+declare class ManagedModel {
+    protected readonly aiConfig: LDAICompletionConfig;
+    protected readonly runner: Runner;
+    private readonly _logger?;
+    constructor(aiConfig: LDAICompletionConfig, runner: Runner, _logger?: LDLogger$1 | undefined);
+    /**
+     * Invoke the model with a prompt string and return a ManagedResult.
+     *
+     * `run()` resolves before `ManagedResult.evaluations` resolves. Awaiting
+     * `evaluations` guarantees both judge evaluation and tracker.trackJudgeResult()
+     * are complete.
+     *
+     * @param prompt The user input to send to the model.
+     * @returns Promise resolving to ManagedResult (before evaluations settle).
+     */
+    run(prompt: string): Promise<ManagedResult>;
+    /**
+     * Get the underlying AI configuration used to initialize this ManagedModel.
+     */
+    getConfig(): LDAICompletionConfig;
+}
+
+/**
+ * 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.
@@ -886,11 +873,20 @@ interface LDGraphTracker {
     /**
      * Returns tracking metadata to be included in every LDClient.track call.
      */
-    getTrackData(): LDGraphTrackData;
+    getTrackData(): {
+        runId: string;
+        graphKey: string;
+        variationKey?: string;
+        version: number;
+    };
     /**
-     * Returns a snapshot of all graph-level metrics tracked so far.
+     * 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 run has
+     * completed via `ManagedAgentGraph.run()`, prefer `ManagedGraphResult.metrics`
+     * which is fully populated.
      */
-    getSummary(): LDGraphMetricSummary;
+    getSummary(): Partial<LDAIGraphMetricSummary>;
     /**
      * A URL-safe Base64-encoded (RFC 4648, no padding) token encoding the tracker's
      * identity. Pass this token to {@link LDGraphTrackerImpl.fromResumptionToken} to
@@ -902,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.
      *
@@ -922,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.
      *
@@ -930,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;
     /**
@@ -1054,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;
     /**
@@ -1103,6 +1099,139 @@ declare class AgentGraphDefinition {
     static collectAllKeys(graph: LDAgentGraphFlagValue): Set<string>;
 }
 
+/**
+ * Judge implementation that handles evaluation functionality and conversation management.
+ *
+ * According to the AIEval spec, judges are AI Configs with mode: "judge" that evaluate
+ * other AI Configs using structured output.
+ */
+declare class Judge {
+    private readonly _aiConfig;
+    private readonly _runner;
+    private readonly _sampleRate;
+    private readonly _logger?;
+    constructor(_aiConfig: LDAIJudgeConfig, _runner: Runner, _sampleRate?: number, logger?: LDLogger$1);
+    /**
+     * The default sampling rate baked in at construction. Used by `evaluate` /
+     * `evaluateMessages` when no per-call rate is supplied.
+     */
+    get sampleRate(): number;
+    /**
+     * 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
+     */
+    private _getEvaluationMetricKey;
+    /**
+     * Evaluates an AI response using the judge's configuration.
+     *
+     * @param input The input prompt or question that was provided to the AI
+     * @param output The AI-generated response to be evaluated
+     * @param samplingRate Sampling rate (0-1) to determine if evaluation should be processed.
+     *   When omitted, the Judge's constructor-default rate is used. An explicit `0` overrides
+     *   the default — only `undefined` falls through.
+     * @returns Promise that resolves to evaluation results
+     */
+    evaluate(input: string, output: string, samplingRate?: number): Promise<LDJudgeResult>;
+    /**
+     * 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 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: RunnerResult, samplingRatio?: number): Promise<LDJudgeResult>;
+    /**
+     * Returns the AI Config used by this judge.
+     */
+    getAIConfig(): LDAIJudgeConfig;
+    /**
+     * Returns the runner used by this judge.
+     */
+    getRunner(): Runner;
+    /**
+     * Builds the evaluation input string passed to the runner.
+     *
+     * Combines the original prompt and the response into a single, well-known
+     * format the judge model is expected to evaluate.
+     */
+    private _buildEvaluationInput;
+    /**
+     * Parses the structured evaluation response. Expects top-level {score, reasoning}.
+     * Returns score and reasoning, or undefined if parsing fails.
+     */
+    private _parseEvaluationResponse;
+}
+
+/**
+ * A registry of callable tools keyed by tool name.
+ * Mirrors Python's `Dict[str, Callable]` — values are typically functions
+ * that the provider invokes when the model requests a tool call.
+ */
+type ToolRegistry = Record<string, (...args: any[]) => unknown>;
+/**
+ * Abstract base class for AI providers.
+ *
+ * An `AIProvider` is a per-provider factory: it is instantiated once per
+ * provider package and is responsible for constructing focused runtime
+ * capability objects via {@link createModel}, {@link createAgent}, and
+ * {@link createAgentGraph}.
+ *
+ * Provider packages subclass `AIProvider` and override the methods they
+ * support. The default implementations return `undefined`, mirroring Python's
+ * base-class behaviour, so providers only need to implement the modes they
+ * actually support.
+ */
+declare abstract class AIProvider {
+    protected _logger?: LDLogger$1;
+    constructor(logger?: LDLogger$1);
+    /**
+     * Create a Runner for a completion or judge AI Config.
+     *
+     * Override in provider subclasses to return a configured {@link Runner}.
+     * 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, _multiTurn?: boolean): Promise<Runner | undefined>;
+    /**
+     * Create a Runner for an agent AI Config.
+     *
+     * Override in provider subclasses to return a configured {@link Runner}.
+     * Default implementation returns `undefined`.
+     *
+     * @param config The agent AI configuration.
+     * @param tools Optional registry of callable tools.
+     * @returns Promise resolving to a {@link Runner}, or `undefined` if this
+     *   provider does not support agent creation.
+     */
+    createAgent(_config: LDAIAgentConfig, _tools?: ToolRegistry): Promise<Runner | undefined>;
+    /**
+     * Create an AgentGraphRunner for an agent graph definition.
+     *
+     * Override in provider subclasses to return a configured {@link AgentGraphRunner}.
+     * Default implementation returns `undefined`.
+     *
+     * @param graphDef The agent graph definition.
+     * @param tools Optional registry of callable tools.
+     * @returns Promise resolving to an {@link AgentGraphRunner}, or `undefined` if
+     *   this provider does not support graph execution.
+     */
+    createAgentGraph(_graphDef: AgentGraphDefinition, _tools?: ToolRegistry): Promise<AgentGraphRunner | undefined>;
+}
+
 /**
  * List of supported AI providers.
  */
@@ -1112,27 +1241,96 @@ declare const SUPPORTED_AI_PROVIDERS: readonly ["openai", "langchain", "vercel"]
  */
 type SupportedAIProvider = (typeof SUPPORTED_AI_PROVIDERS)[number];
 /**
- * Factory for creating AIProvider instances based on the provider configuration.
+ * Sole entry point for runner creation.
+ *
+ * RunnerFactory is the single factory for creating {@link Runner} and
+ * {@link AgentGraphRunner} instances. It mirrors the Python RunnerFactory
+ * pattern: it knows about supported provider packages, loads them dynamically
+ * via {@link _getProviderFactory}, and delegates creation to the factory
+ * instance methods on {@link AIProvider}.
+ *
+ * Provider packages subclass {@link AIProvider} and override its factory
+ * methods (`createModel`, `createAgent`, `createAgentGraph`).
  */
-declare class AIProviderFactory {
+declare class RunnerFactory {
     /**
-     * Create an AIProvider instance based on the AI configuration.
-     * This method attempts to load provider-specific implementations dynamically.
-     * Returns undefined if the provider is not supported.
+     * Load and return the AIProvider factory for the given provider type.
+     *
+     * This is the single place in the codebase that knows provider package names.
+     * Each supported provider package exports a `*RunnerFactory` class that
+     * extends {@link AIProvider}; this method instantiates it directly.
      *
-     * @param aiConfig The AI configuration
-     * @param logger Optional logger for logging provider initialization
-     * @param defaultAiProvider Optional default AI provider to use
+     * @param providerType One of the {@link SUPPORTED_AI_PROVIDERS} values.
+     * @param logger Optional logger forwarded to the provider factory.
+     * @returns A configured {@link AIProvider} instance, or `undefined` if the
+     *   package cannot be loaded.
      */
-    static create(aiConfig: LDAIConfigKind, logger?: LDLogger$1, defaultAiProvider?: SupportedAIProvider): Promise<AIProvider | undefined>;
+    private static _getProviderFactory;
     /**
      * Determine which providers to try based on defaultAiProvider and providerName.
+     *
+     * Mirrors Python's `_get_providers_to_try` helper.
      */
     private static _getProvidersToTry;
     /**
-     * Try to create a provider of the specified type.
+     * Try each provider in order and return the first non-undefined result.
+     *
+     * Mirrors Python's `_with_fallback` helper. Loads each provider factory via
+     * {@link _getProviderFactory} and calls `fn` with it. Returns the first
+     * truthy result, or `undefined` if no provider succeeds.
+     *
+     * @param providers Ordered list of provider types to try.
+     * @param fn Callback that calls the appropriate factory method on the provider.
+     * @param logger Optional logger forwarded to each provider factory.
+     */
+    private static _withFallback;
+    /**
+     * Create a Runner for the given AI configuration.
+     *
+     * Suitable for completion, judge, and agent config modes. Dynamically
+     * loads the matching provider package via {@link _getProviderFactory} and
+     * delegates to its {@link AIProvider.createModel} method.
+     *
+     * @param config The AI configuration (completion, agent, or judge).
+     * @param logger Optional logger forwarded to the underlying provider.
+     * @param defaultAiProvider Optional provider override
+     *   ('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, multiTurn?: boolean): Promise<Runner | undefined>;
+    /**
+     * Create a Runner for an agent AI Config.
+     *
+     * Delegates to the provider factory's {@link AIProvider.createAgent} method.
+     *
+     * @param config The agent AI configuration.
+     * @param tools Optional registry of callable tools.
+     * @param logger Optional logger forwarded to the underlying provider.
+     * @param defaultAiProvider Optional provider override.
+     * @returns A configured {@link Runner}, or `undefined` if no suitable
+     *   provider could be loaded.
      */
-    private static _tryCreateProvider;
+    static createAgent(config: LDAIAgentConfig, tools?: ToolRegistry, logger?: LDLogger$1, defaultAiProvider?: SupportedAIProvider): Promise<Runner | undefined>;
+    /**
+     * Create an AgentGraphRunner for the given agent graph definition.
+     *
+     * Delegates to the provider factory's {@link AIProvider.createAgentGraph} method.
+     *
+     * @param graphDef The agent graph definition.
+     * @param tools Optional registry of callable tools.
+     * @param logger Optional logger forwarded to the underlying provider.
+     * @param defaultAiProvider Optional provider override.
+     * @returns A configured {@link AgentGraphRunner}, or `undefined` if no
+     *   suitable provider could be loaded.
+     */
+    static createAgentGraph(graphDef: AgentGraphDefinition, tools?: ToolRegistry, logger?: LDLogger$1, defaultAiProvider?: SupportedAIProvider): Promise<AgentGraphRunner | undefined>;
 }
 
 /**
@@ -1153,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
      * ```
@@ -1168,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>): 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>;
+    completionConfig(key: string, context: LDContext, defaultValue?: LDAICompletionConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): 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.
@@ -1211,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
      * ```
@@ -1227,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>): 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>;
+    agentConfig(key: string, context: LDContext, defaultValue?: LDAIAgentConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): 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.
@@ -1247,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
@@ -1259,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>;
@@ -1274,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
      * ```
@@ -1306,20 +1494,18 @@ 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>>;
-    /**
-     * Returns a TrackedChat instance for chat interactions.
-     * This method serves as the primary entry point for creating TrackedChat instances from configuration.
+     * Creates and returns a new ManagedModel instance for LLM model interactions.
      *
-     * @param key The key identifying the AI chat configuration to use.
+     * @param key The key identifying the AI completion configuration to use.
      * @param context The standard LDContext used when evaluating flags.
      * @param defaultValue Optional fallback when the configuration is not available from LaunchDarkly.
      * When omitted or null, a disabled default is used.
@@ -1327,7 +1513,7 @@ interface LDAIClient {
      * The variables will also be used for judge evaluation. For the judge only, the variables
      * `message_history` and `response_to_evaluate` are reserved and will be ignored.
      * @param defaultAiProvider Optional default AI provider to use.
-     * @returns A promise that resolves to the TrackedChat instance, or null if the configuration is disabled.
+     * @returns A promise that resolves to the ManagedModel instance, or undefined if the configuration is disabled.
      *
      * @example
      * ```
@@ -1343,18 +1529,26 @@ interface LDAIClient {
      * };
      * const variables = { customerName: 'John' };
      *
-     * const chat = await client.createChat(key, context, defaultValue, variables);
-     * if (chat) {
-     *   const response = await chat.invoke("I need help with my order");
-     *   console.log(response.message.content);
+     * const model = await client.createModel(key, context, defaultValue, variables);
+     * if (model) {
+     *   const result = await model.run("I need help with my order");
+     *   console.log(result.content);
      * }
      * ```
      */
-    createChat(key: string, context: LDContext, defaultValue?: LDAICompletionConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<TrackedChat | undefined>;
+    createModel(key: string, context: LDContext, defaultValue?: LDAICompletionConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<ManagedModel | undefined>;
     /**
-     * @deprecated Use `createChat` instead. This method will be removed in a future version.
+     * Creates and returns a new ManagedAgent instance for agent interactions.
+     * Evaluations are wired automatically and exposed on ManagedResult.evaluations.
+     *
+     * @param key The key identifying the agent AI config to use.
+     * @param context The standard LDContext used when evaluating flags.
+     * @param defaultValue Optional fallback when the configuration is not available from LaunchDarkly.
+     * @param variables Dictionary of values for instruction interpolation.
+     * @param defaultAiProvider Optional default AI provider to use.
+     * @returns A promise that resolves to the ManagedAgent instance, or undefined if disabled.
      */
-    initChat(key: string, context: LDContext, defaultValue?: LDAICompletionConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<TrackedChat | undefined>;
+    createAgent(key: string, context: LDContext, defaultValue?: LDAIAgentConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<ManagedAgent | undefined>;
     /**
      * Creates and returns a new Judge instance for AI evaluation.
      *
@@ -1365,6 +1559,8 @@ interface LDAIClient {
      * @param variables Dictionary of values for instruction interpolation.
      * The variables `message_history` and `response_to_evaluate` are reserved for the judge and will be ignored.
      * @param defaultAiProvider Optional default AI provider to use.
+     * @param sampleRate Optional default sampling rate (0-1) baked into the Judge.
+     *   Used by `Judge.evaluate()` when no per-call rate is supplied. Defaults to 1.0.
      * @returns Promise that resolves to a Judge instance or undefined if disabled/unsupported
      *
      * @example
@@ -1388,11 +1584,11 @@ interface LDAIClient {
      * }
      * ```
      */
-    createJudge(key: string, context: LDContext, defaultValue?: LDAIJudgeConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<Judge | undefined>;
+    createJudge(key: string, context: LDContext, defaultValue?: LDAIJudgeConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider, sampleRate?: number): Promise<Judge | undefined>;
     /**
      * 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.
@@ -1456,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}.
  *
@@ -1483,8 +1715,13 @@ declare class LDGraphTrackerImpl implements LDGraphTracker {
      * @param context LDContext for the new tracker.
      */
     static fromResumptionToken(token: string, ldClient: LDClientMin, context: LDContext): LDGraphTrackerImpl;
-    getTrackData(): LDGraphTrackData;
-    getSummary(): LDGraphMetricSummary;
+    getTrackData(): {
+        runId: string;
+        graphKey: string;
+        variationKey?: string;
+        version: number;
+    };
+    getSummary(): Partial<LDAIGraphMetricSummary>;
     get resumptionToken(): string;
     trackInvocationSuccess(): void;
     trackInvocationFailure(): void;
@@ -1513,4 +1750,4 @@ declare class LDGraphTrackerImpl implements LDGraphTracker {
 declare function initAi(ldClient: LDClientMin): LDAIClient;
 type LDLogger = common.LDLogger;
 
-export { AIProvider, AIProviderFactory, AgentGraphDefinition, AgentGraphNode, 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 LDAIJudgeConfig, type LDAIJudgeConfigDefault, type LDAIMetrics, type LDAgentGraphFlagValue, LDFeedbackKind, type LDGraphEdge, type LDGraphMetricSummary, type LDGraphTrackData, type LDGraphTracker, LDGraphTrackerImpl, type LDJudge, type LDJudgeConfiguration, type LDJudgeResult, type LDLogger, type LDMessage, type LDModelConfig, type LDProviderConfig, type LDTokenUsage, type LDTool, SUPPORTED_AI_PROVIDERS, type StructuredResponse, type SupportedAIProvider, TrackedChat, 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 };