@launchdarkly/server-sdk-ai 0.19.0 → 0.20.0

package/dist/index.d.ts

@@ -1,53 +1,6 @@
 import * as common from '@launchdarkly/js-server-sdk-common';
 import { LDLogger as LDLogger$1, LDContext, LDFlagValue } from '@launchdarkly/js-server-sdk-common';
 
-/**
- * Information about token usage.
- */
-interface LDTokenUsage {
-    /**
-     * Combined token usage.
-     */
-    total: number;
-    /**
-     * Number of tokens in the input.
-     */
-    input: number;
-    /**
-     * Number of tokens in the output.
-     */
-    output: number;
-}
-
-/**
- * Metrics information for AI operations that includes success status and token usage.
- * This class combines success/failure tracking with token usage metrics.
- */
-interface LDAIMetrics {
-    /**
-     * Whether the AI operation was successful.
-     */
-    success: boolean;
-    /**
-     * Token usage information for the operation.
-     * This will be undefined if no token usage data is available.
-     */
-    usage?: LDTokenUsage;
-}
-
-/**
- * Structured response from AI models.
- */
-interface StructuredResponse {
-    /** The structured data returned by the model */
-    data: Record<string, unknown>;
-    /** The raw response from the model */
-    rawResponse: string;
-    /**
-     * Metrics information including success status and token usage.
-     */
-    metrics: LDAIMetrics;
-}
 /**
  * Result from a judge evaluation containing score, reasoning, and metadata.
  */
@@ -68,6 +21,24 @@ interface LDJudgeResult {
     reasoning?: string;
 }
 
+/**
+ * Information about token usage.
+ */
+interface LDTokenUsage {
+    /**
+     * Combined token usage.
+     */
+    total: number;
+    /**
+     * Number of tokens in the input.
+     */
+    input: number;
+    /**
+     * Number of tokens in the output.
+     */
+    output: number;
+}
+
 declare function createBedrockTokenUsage(data: {
     totalTokens?: number;
     inputTokens?: number;
@@ -94,6 +65,32 @@ declare enum LDFeedbackKind {
     Negative = "negative"
 }
 
+/**
+ * Metrics information for AI operations that includes success status and token usage.
+ * This class combines success/failure tracking with token usage metrics.
+ */
+interface LDAIMetrics {
+    /**
+     * Whether the AI operation was successful.
+     */
+    success: boolean;
+    /**
+     * Token usage information for the operation.
+     * This will be undefined if no token usage data is available.
+     */
+    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;
+}
+
 declare function createVercelAISDKTokenUsage(data: {
     totalTokens?: number;
     inputTokens?: number;
@@ -103,32 +100,94 @@ declare function createVercelAISDKTokenUsage(data: {
 }): LDTokenUsage;
 
 /**
- * Metrics which have been tracked.
+ * Summary metrics returned in a ManagedResult or from LDAIConfigTracker.getSummary().
+ * Provides a flat view of the key metrics for the completed operation.
  */
 interface LDAIMetricSummary {
     /**
-     * The duration of generation.
+     * Whether the AI operation was successful.
      */
-    durationMs?: number;
+    success?: boolean;
     /**
-     * Information about token usage.
+     * Token usage information, if available.
      */
     tokens?: LDTokenUsage;
     /**
-     * Was generation successful.
+     * List of tool call identifiers made during the operation, if any.
      */
-    success?: boolean;
+    toolCalls?: string[];
     /**
-     * Any sentiment about the generation.
+     * 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;
     };
     /**
-     * Time to first token for this generation.
+     * Resumption token for deferred feedback association.
      */
-    timeToFirstTokenMs?: number;
+    resumptionToken?: string;
+}
+/**
+ * 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.
+ */
+interface RunnerResult {
+    /**
+     * The text content of the model's response.
+     */
+    content: string;
+    /**
+     * Metrics information for the operation.
+     */
+    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>;
 }
+/**
+ * The result returned by a managed model invocation (ManagedModel.run()).
+ * Includes a promise for asynchronous judge evaluations.
+ */
+interface ManagedResult {
+    /**
+     * The text content of the model's response.
+     */
+    content: string;
+    /**
+     * Summarized metrics for this invocation.
+     */
+    metrics: LDAIMetricSummary;
+    /**
+     * The raw response object from the provider, if available.
+     */
+    raw?: unknown;
+    /**
+     * Parsed structured output, if available.
+     */
+    parsed?: Record<string, unknown>;
+    /**
+     * 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.
+     */
+    evaluations: Promise<LDJudgeResult[]>;
+}
+
 /**
  * The LDAIConfigTracker is used to track various details about AI operations.
  */
@@ -448,7 +507,7 @@ interface LDAIConfig extends Omit<LDAIConfigDefault, 'enabled'> {
      * 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.
      */
-    createTracker?: () => LDAIConfigTracker;
+    createTracker: () => LDAIConfigTracker;
 }
 /**
  * Default Agent-specific AI Config with instructions.
@@ -601,244 +660,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>;
+    success: boolean;
     /**
-     * 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
+     * Execution path through the graph as an ordered array of config keys.
      */
-    evaluateMessages(messages: LDMessage[], response: ChatResponse, samplingRatio?: number): Promise<LDJudgeResult>;
+    path: string[];
     /**
-     * Returns the AI Config used by this judge.
+     * Per-node metric summaries keyed by agent config key.
      */
-    getAIConfig(): LDAIJudgeConfig;
+    nodeMetrics: Record<string, LDAIMetricSummary>;
     /**
-     * Returns the AI provider used by this judge.
+     * Total graph execution duration in milliseconds, if tracked.
      */
-    getProvider(): AIProvider;
+    durationMs?: number;
     /**
-     * Constructs evaluation messages by combining judge's config messages with input/output.
+     * Aggregate token usage across the entire graph invocation, if available.
      */
-    private _constructEvaluationMessages;
+    tokens?: LDTokenUsage;
     /**
-     * Interpolates message content with variables using Mustache templating.
+     * Resumption token for deferred feedback association.
      */
-    private _interpolateMessage;
-    /**
-     * Parses the structured evaluation response. Expects top-level {score, reasoning}.
-     * Returns score and reasoning, or undefined if parsing fails.
-     */
-    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>;
-    /**
-     * 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;
+interface LDAIGraphMetrics {
     /**
-     * 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}.
@@ -862,6 +813,104 @@ interface LDGraphTrackData {
     version: number;
 }
 
+/**
+ * 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;
+}
+
 /**
  * Tracks graph-level and edge-level metrics for an agent graph invocation.
  *
@@ -886,11 +935,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 invocation 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
@@ -1103,6 +1161,187 @@ 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.
+ *
+ * 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, 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
+     */
+    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 response.
+     *
+     * @param messages Array of messages representing the conversation history
+     * @param response The AI response to be evaluated
+     * @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>;
+    /**
+     * 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.
+     * @returns Promise resolving to a {@link Runner}, or `undefined` if this
+     *   provider does not support model creation.
+     */
+    createModel(_config: LDAICompletionConfig | LDAIJudgeConfig): 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 +1351,92 @@ 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 _tryCreateProvider;
+    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.
+     * @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>;
+    /**
+     * 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.
+     */
+    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>;
 }
 
 /**
@@ -1192,7 +1496,7 @@ interface LDAIClient {
      * }
      * ```
      */
-    completionConfig(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>;
     /**
      * @deprecated Use `completionConfig` instead. This method will be removed in a future version.
      */
@@ -1231,7 +1535,7 @@ interface LDAIClient {
      * agentConfig.tracker.trackSuccess();
      * ```
      */
-    agentConfig(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>;
     /**
      * @deprecated Use `agentConfig` instead. This method will be removed in a future version.
      */
@@ -1316,10 +1620,9 @@ interface LDAIClient {
      */
     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 +1630,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 +1646,34 @@ 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>;
+    /**
+     * 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.
+     */
+    createAgent(key: string, context: LDContext, defaultValue?: LDAIAgentConfigDefault, variables?: Record<string, unknown>, defaultAiProvider?: SupportedAIProvider): Promise<ManagedAgent | undefined>;
     /**
-     * @deprecated Use `createChat` instead. This method will be removed in a future version.
+     * @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<TrackedChat | undefined>;
+    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.
      *
@@ -1365,6 +1684,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,7 +1709,7 @@ 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
@@ -1483,8 +1804,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 +1839,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, 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 };