@launchdarkly/server-sdk-ai 0.16.7 → 0.17.0

package/dist/index.js

@@ -1,11 +1,11 @@
 // src/LDAIClientImpl.ts
 import Mustache2 from "mustache";
+import { randomUUID } from "crypto";
 
 // src/api/chat/TrackedChat.ts
 var TrackedChat = class {
-  constructor(aiConfig, tracker, provider, judges = {}, _logger) {
+  constructor(aiConfig, provider, judges = {}, _logger) {
     this.aiConfig = aiConfig;
-    this.tracker = tracker;
     this.provider = provider;
     this.judges = judges;
     this._logger = _logger;
@@ -16,6 +16,7 @@ var TrackedChat = class {
    * This method handles conversation management and tracking, delegating to the provider's invokeModel method.
    */
   async invoke(prompt) {
+    const tracker = this.aiConfig.createTracker();
     const userMessage = {
       role: "user",
       content: prompt
@@ -23,12 +24,19 @@ var TrackedChat = class {
     this.messages.push(userMessage);
     const configMessages = this.aiConfig.messages || [];
     const allMessages = [...configMessages, ...this.messages];
-    const response = await this.tracker.trackMetricsOf(
+    const response = await tracker.trackMetricsOf(
       (result) => result.metrics,
       () => this.provider.invokeModel(allMessages)
     );
     if (this.aiConfig.judgeConfiguration?.judges && this.aiConfig.judgeConfiguration.judges.length > 0) {
-      response.evaluations = this._evaluateWithJudges(this.messages, response);
+      response.evaluations = this._evaluateWithJudges(this.messages, response).then(
+        (evaluations) => {
+          evaluations.forEach((judgeResult) => {
+            tracker.trackJudgeResult(judgeResult);
+          });
+          return evaluations;
+        }
+      );
     }
     this.messages.push(response.message);
     return response;
@@ -47,23 +55,29 @@ var TrackedChat = class {
       const judge = this.judges[judgeConfig.key];
       if (!judge) {
         this._logger?.warn(
-          `Judge configuration is not enabled: ${judgeConfig.key}`,
-          this.tracker.getTrackData()
+          `Judge configuration is not enabled for ${judgeConfig.key} in ${this.aiConfig.key}`
         );
-        return void 0;
-      }
-      const judgeResponse = await judge.evaluateMessages(
-        messages,
-        response,
-        judgeConfig.samplingRate
-      );
-      if (judgeResponse && judgeResponse.success) {
-        this.tracker.trackJudgeResponse(judgeResponse);
+        const result = {
+          success: false,
+          sampled: true,
+          errorMessage: `Judge configuration is not enabled for ${judgeConfig.key}`
+        };
+        return result;
       }
-      return judgeResponse;
+      return judge.evaluateMessages(messages, response, judgeConfig.samplingRate);
     });
     const results = await Promise.allSettled(evaluationPromises);
-    return results.map((result) => result.status === "fulfilled" ? result.value : void 0);
+    return results.map((settled) => {
+      if (settled.status === "fulfilled") {
+        return settled.value;
+      }
+      const result = {
+        success: false,
+        sampled: true,
+        errorMessage: "Judge evaluation failed"
+      };
+      return result;
+    });
   }
   /**
    * Get the underlying AI configuration used to initialize this TrackedChat.
@@ -71,12 +85,6 @@ var TrackedChat = class {
   getConfig() {
     return this.aiConfig;
   }
-  /**
-   * Get the underlying AI configuration tracker used to initialize this TrackedChat.
-   */
-  getTracker() {
-    return this.tracker;
-  }
   /**
    * Get the underlying AI provider instance.
    * This provides direct access to the provider for advanced use cases.
@@ -161,20 +169,21 @@ var LDAIConfigUtils = class {
   /**
    * Converts a LaunchDarkly flag value to the appropriate AI configuration type.
    *
+   * @param key The configuration key
    * @param flagValue The flag value from LaunchDarkly
-   * @param tracker The tracker to add to the config
+   * @param trackerFactory A factory function that creates a new tracker for each execution
    * @returns The appropriate AI configuration type
    */
-  static fromFlagValue(key, flagValue, tracker) {
+  static fromFlagValue(key, flagValue, trackerFactory) {
     const flagValueMode = flagValue._ldMeta?.mode;
     switch (flagValueMode) {
       case "agent":
-        return this.toAgentConfig(key, flagValue, tracker);
+        return this.toAgentConfig(key, flagValue, trackerFactory);
       case "judge":
-        return this.toJudgeConfig(key, flagValue, tracker);
+        return this.toJudgeConfig(key, flagValue, trackerFactory);
       case "completion":
       default:
-        return this.toCompletionConfig(key, flagValue, tracker);
+        return this.toCompletionConfig(key, flagValue, trackerFactory);
     }
   }
   /**
@@ -189,20 +198,20 @@ var LDAIConfigUtils = class {
         return {
           key,
           enabled: false,
-          tracker: void 0
+          createTracker: void 0
         };
       case "judge":
         return {
           key,
           enabled: false,
-          tracker: void 0
+          createTracker: void 0
         };
       case "completion":
       default:
         return {
           key,
           enabled: false,
-          tracker: void 0
+          createTracker: void 0
         };
     }
   }
@@ -224,14 +233,15 @@ var LDAIConfigUtils = class {
   /**
    * Creates a completion config from flag value data.
    *
+   * @param key The configuration key
    * @param flagValue The flag value from LaunchDarkly
-   * @param tracker The tracker to add to the config
+   * @param trackerFactory A factory function that creates a new tracker for each execution
    * @returns A completion configuration
    */
-  static toCompletionConfig(key, flagValue, tracker) {
+  static toCompletionConfig(key, flagValue, trackerFactory) {
     return {
       ...this._toBaseConfig(key, flagValue),
-      tracker,
+      createTracker: trackerFactory,
       messages: flagValue.messages,
       judgeConfiguration: flagValue.judgeConfiguration
     };
@@ -239,14 +249,15 @@ var LDAIConfigUtils = class {
   /**
    * Creates an agent config from flag value data.
    *
+   * @param key The configuration key
    * @param flagValue The flag value from LaunchDarkly
-   * @param tracker The tracker to add to the config
+   * @param trackerFactory A factory function that creates a new tracker for each execution
    * @returns An agent configuration
    */
-  static toAgentConfig(key, flagValue, tracker) {
+  static toAgentConfig(key, flagValue, trackerFactory) {
     return {
       ...this._toBaseConfig(key, flagValue),
-      tracker,
+      createTracker: trackerFactory,
       instructions: flagValue.instructions,
       judgeConfiguration: flagValue.judgeConfiguration
     };
@@ -254,11 +265,12 @@ var LDAIConfigUtils = class {
   /**
    * Creates a judge config from flag value data.
    *
+   * @param key The configuration key
    * @param flagValue The flag value from LaunchDarkly
-   * @param tracker The tracker to add to the config
+   * @param trackerFactory A factory function that creates a new tracker for each execution
    * @returns A judge configuration
    */
-  static toJudgeConfig(key, flagValue, tracker) {
+  static toJudgeConfig(key, flagValue, trackerFactory) {
     let evaluationMetricKey;
     if (flagValue.evaluationMetricKey && flagValue.evaluationMetricKey.trim().length > 0) {
       evaluationMetricKey = flagValue.evaluationMetricKey.trim();
@@ -270,69 +282,269 @@ var LDAIConfigUtils = class {
     }
     return {
       ...this._toBaseConfig(key, flagValue),
-      tracker,
+      createTracker: trackerFactory,
       messages: flagValue.messages,
       evaluationMetricKey
     };
   }
 };
 
-// src/api/judge/Judge.ts
-import Mustache from "mustache";
+// src/api/graph/AgentGraphNode.ts
+var AgentGraphNode = class {
+  constructor(_key, _config, _edges) {
+    this._key = _key;
+    this._config = _config;
+    this._edges = _edges;
+  }
+  /**
+   * Returns the agent config key that identifies this node in the graph.
+   */
+  getKey() {
+    return this._key;
+  }
+  /**
+   * Returns the underlying AIAgentConfig for this node.
+   * Use `getConfig().tracker` to record node-level metrics.
+   */
+  getConfig() {
+    return this._config;
+  }
+  /**
+   * Returns the outgoing edges from this node to its children.
+   */
+  getEdges() {
+    return this._edges;
+  }
+  /**
+   * Returns `true` if this node has no outgoing edges (i.e., it is a terminal/leaf node).
+   */
+  isTerminal() {
+    return this._edges.length === 0;
+  }
+};
 
-// src/api/judge/EvaluationSchemaBuilder.ts
-var EvaluationSchemaBuilder = class {
-  static build(evaluationMetricKey) {
-    if (!evaluationMetricKey) {
-      return {};
+// src/api/graph/AgentGraphDefinition.ts
+var AgentGraphDefinition = class _AgentGraphDefinition {
+  constructor(_agentGraph, _nodes, enabled, _createTracker) {
+    this._agentGraph = _agentGraph;
+    this._nodes = _nodes;
+    this.enabled = enabled;
+    this._createTracker = _createTracker;
+  }
+  /**
+   * Builds a node map from a raw agent graph flag value and a map of pre-fetched agent configs.
+   *
+   * @param graph Raw graph flag value from LaunchDarkly.
+   * @param agentConfigs Map of agent config key to resolved LDAIAgentConfig.
+   * @returns Record mapping agent config keys to AgentGraphNode instances.
+   */
+  static buildNodes(graph, agentConfigs) {
+    const nodes = {};
+    const allKeys = _AgentGraphDefinition.collectAllKeys(graph);
+    allKeys.forEach((key) => {
+      const config = agentConfigs[key];
+      if (!config) {
+        return;
+      }
+      const outgoingEdges = graph.edges?.[key] ?? [];
+      nodes[key] = new AgentGraphNode(key, config, outgoingEdges);
+    });
+    return nodes;
+  }
+  /**
+   * Returns the children of the node identified by `nodeKey`.
+   *
+   * @param nodeKey The agent config key of the parent node.
+   */
+  getChildNodes(nodeKey) {
+    const node = this._nodes[nodeKey];
+    if (!node) {
+      return [];
     }
-    return {
-      type: "object",
-      properties: {
-        evaluations: {
-          type: "object",
-          description: `Object containing evaluation results for ${evaluationMetricKey} metric`,
-          properties: {
-            [evaluationMetricKey]: this._buildKeySchema(evaluationMetricKey)
-          },
-          required: [evaluationMetricKey],
-          additionalProperties: false
+    return node.getEdges().map((edge) => this._nodes[edge.key]).filter((n) => n !== void 0);
+  }
+  /**
+   * Returns all nodes that have a direct edge to the node identified by `nodeKey`.
+   *
+   * @param nodeKey The agent config key of the child node.
+   */
+  getParentNodes(nodeKey) {
+    return Object.values(this._nodes).filter(
+      (node) => node.getEdges().some((edge) => edge.key === nodeKey)
+    );
+  }
+  /**
+   * Returns all terminal nodes (nodes with no outgoing edges).
+   */
+  terminalNodes() {
+    return Object.values(this._nodes).filter((node) => node.isTerminal());
+  }
+  /**
+   * Returns the root node of the graph.
+   */
+  rootNode() {
+    return this._nodes[this._agentGraph.root];
+  }
+  /**
+   * Returns the node with the given key, or `null` if not found.
+   *
+   * @param nodeKey The agent config key to look up.
+   */
+  getNode(nodeKey) {
+    return this._nodes[nodeKey] ?? null;
+  }
+  /**
+   * Returns the underlying raw graph configuration from LaunchDarkly.
+   */
+  getConfig() {
+    return this._agentGraph;
+  }
+  /**
+   * Returns a new {@link LDGraphTracker} for this graph invocation.
+   *
+   * Call this once per invocation. Each call produces a tracker with a fresh `runId`
+   * that groups all events for that invocation.
+   */
+  createTracker() {
+    return this._createTracker();
+  }
+  /**
+   * Traverses the graph breadth-first from the root to all terminal nodes.
+   *
+   * Nodes at the same depth are processed before advancing to the next depth.
+   * The value returned by `fn` is stored in the mutable `executionContext` under
+   * the node's key, making upstream results available to downstream nodes.
+   *
+   * Cyclic graphs are handled safely — each node is visited at most once.
+   *
+   * @param fn Callback invoked for each node. Its return value is added to
+   *   `executionContext` keyed by the node's config key.
+   * @param initialExecutionContext Optional initial context to seed the traversal.
+   */
+  traverse(fn, initialExecutionContext = {}) {
+    const root = this.rootNode();
+    if (!root) {
+      return;
+    }
+    const executionContext = { ...initialExecutionContext };
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [root];
+    visited.add(root.getKey());
+    while (queue.length > 0) {
+      const node = queue.shift();
+      const result = fn(node, executionContext);
+      executionContext[node.getKey()] = result;
+      node.getEdges().forEach((edge) => {
+        if (!visited.has(edge.key)) {
+          const child = this._nodes[edge.key];
+          if (child) {
+            visited.add(edge.key);
+            queue.push(child);
+          }
         }
-      },
-      required: ["evaluations"],
-      additionalProperties: false
-    };
+      });
+    }
   }
-  static _buildKeySchema(key) {
-    return {
-      type: "object",
-      properties: {
-        score: {
-          type: "number",
-          minimum: 0,
-          maximum: 1,
-          description: `Score between 0.0 and 1.0 for ${key}`
-        },
-        reasoning: {
-          type: "string",
-          description: `Reasoning behind the score for ${key}`
+  /**
+   * Traverses the graph from terminal nodes up to the root.
+   *
+   * Uses BFS upward via parent edges so that each node is processed only after
+   * all of its reachable descendants have been processed. The root is always
+   * visited last. Cyclic graphs are handled safely — each node is visited at
+   * most once; if the graph has no terminal nodes, this method returns without
+   * invoking `fn`.
+   *
+   * **Ordering note:** Within a single BFS level (nodes at the same depth from a
+   * terminal) the visit order is not strictly guaranteed. The guarantee is only
+   * that a node is visited before any of its ancestors — not that siblings at the
+   * same depth are visited in a specific order relative to each other.
+   *
+   * The value returned by `fn` is stored in the mutable `executionContext` under
+   * the node's key.
+   *
+   * @param fn Callback invoked for each node. Its return value is added to
+   *   `executionContext` keyed by the node's config key.
+   * @param initialExecutionContext Optional initial context to seed the traversal.
+   */
+  reverseTraverse(fn, initialExecutionContext = {}) {
+    const terminals = this.terminalNodes();
+    if (terminals.length === 0) {
+      return;
+    }
+    const executionContext = { ...initialExecutionContext };
+    const rootKey = this._agentGraph.root;
+    const visited = /* @__PURE__ */ new Set();
+    let queue = terminals;
+    while (queue.length > 0) {
+      const nextQueue = [];
+      queue.forEach((node) => {
+        const key = node.getKey();
+        if (visited.has(key)) {
+          return;
         }
-      },
-      required: ["score", "reasoning"],
-      additionalProperties: false
-    };
+        visited.add(key);
+        if (key === rootKey) {
+          return;
+        }
+        const result = fn(node, executionContext);
+        executionContext[key] = result;
+        this.getParentNodes(key).forEach((parent) => {
+          if (!visited.has(parent.getKey())) {
+            nextQueue.push(parent);
+          }
+        });
+      });
+      queue = nextQueue;
+    }
+    const root = this._nodes[rootKey];
+    if (root && visited.has(rootKey)) {
+      const result = fn(root, executionContext);
+      executionContext[rootKey] = result;
+    }
+  }
+  /**
+   * Collects every unique node key referenced in the graph (root + all edge sources
+   * and targets).
+   */
+  static collectAllKeys(graph) {
+    const keys = /* @__PURE__ */ new Set();
+    keys.add(graph.root);
+    if (graph.edges) {
+      Object.entries(graph.edges).forEach(([sourceKey, edges]) => {
+        keys.add(sourceKey);
+        edges.forEach((edge) => {
+          keys.add(edge.key);
+        });
+      });
+    }
+    return keys;
   }
 };
 
 // src/api/judge/Judge.ts
+import Mustache from "mustache";
+var EVALUATION_SCHEMA = {
+  type: "object",
+  properties: {
+    score: {
+      type: "number",
+      minimum: 0,
+      maximum: 1,
+      description: "Score between 0.0 and 1.0."
+    },
+    reasoning: {
+      type: "string",
+      description: "Reasoning behind the score."
+    }
+  },
+  required: ["score", "reasoning"],
+  additionalProperties: false
+};
 var Judge = class {
-  constructor(_aiConfig, _aiConfigTracker, _aiProvider, logger) {
+  constructor(_aiConfig, _aiProvider, logger) {
     this._aiConfig = _aiConfig;
-    this._aiConfigTracker = _aiConfigTracker;
     this._aiProvider = _aiProvider;
     this._logger = logger;
-    const evaluationMetricKey = this._getEvaluationMetricKey();
-    this._evaluationResponseStructure = EvaluationSchemaBuilder.build(evaluationMetricKey);
   }
   /**
    * Gets the evaluation metric key, prioritizing evaluationMetricKey over evaluationMetricKeys.
@@ -358,56 +570,62 @@ var Judge = class {
    * @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 or undefined if not sampled
+   * @returns Promise that resolves to evaluation results
    */
   async evaluate(input, output, samplingRate = 1) {
+    const result = {
+      success: false,
+      sampled: false,
+      judgeConfigKey: this._aiConfig.key
+    };
+    const tracker = this._aiConfig.createTracker();
     try {
       const evaluationMetricKey = this._getEvaluationMetricKey();
       if (!evaluationMetricKey) {
         this._logger?.warn(
           "Judge configuration is missing required evaluation metric key",
-          this._aiConfigTracker.getTrackData()
+          tracker.getTrackData()
         );
-        return void 0;
+        result.sampled = true;
+        result.errorMessage = "Judge configuration is missing required evaluation metric key";
+        return result;
       }
       if (!this._aiConfig.messages) {
-        this._logger?.warn(
-          "Judge configuration must include messages",
-          this._aiConfigTracker.getTrackData()
-        );
-        return void 0;
+        this._logger?.warn("Judge configuration must include messages", tracker.getTrackData());
+        result.sampled = true;
+        result.errorMessage = "Judge configuration must include messages";
+        return result;
       }
       if (Math.random() > samplingRate) {
         this._logger?.debug(`Judge evaluation skipped due to sampling rate: ${samplingRate}`);
-        return void 0;
+        return result;
       }
+      result.sampled = true;
       const messages = this._constructEvaluationMessages(input, output);
-      const response = await this._aiConfigTracker.trackMetricsOf(
-        (result) => result.metrics,
-        () => this._aiProvider.invokeStructuredModel(messages, this._evaluationResponseStructure)
+      const response = await tracker.trackMetricsOf(
+        (r) => r.metrics,
+        () => this._aiProvider.invokeStructuredModel(messages, EVALUATION_SCHEMA)
       );
-      let { success } = response.metrics;
-      const evals = this._parseEvaluationResponse(response.data, evaluationMetricKey);
-      if (!evals[evaluationMetricKey]) {
+      const evalResult = this._parseEvaluationResponse(response.data);
+      if (!evalResult) {
         this._logger?.warn(
-          "Judge evaluation did not return the expected evaluation",
-          this._aiConfigTracker.getTrackData()
+          `Could not parse evaluation response: ${JSON.stringify(response.data)}`,
+          tracker.getTrackData()
         );
-        success = false;
+        return result;
       }
       return {
-        evals,
-        success,
-        judgeConfigKey: this._aiConfig.key
+        ...result,
+        success: response.metrics.success,
+        score: evalResult.score,
+        reasoning: evalResult.reasoning,
+        metricKey: evaluationMetricKey
       };
     } catch (error) {
       this._logger?.error("Judge evaluation failed:", error);
-      return {
-        evals: {},
-        success: false,
-        error: error instanceof Error ? error.message : "Unknown error",
-        judgeConfigKey: this._aiConfig.key
-      };
+      result.sampled = true;
+      result.errorMessage = error instanceof Error ? error.message : "Unknown error";
+      return result;
     }
   }
   /**
@@ -416,7 +634,7 @@ var Judge = class {
    * @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 or undefined if not sampled
+   * @returns Promise that resolves to evaluation results
    */
   async evaluateMessages(messages, response, samplingRatio = 1) {
     const input = messages.length === 0 ? "" : messages.map((msg) => msg.content).join("\r\n");
@@ -429,12 +647,6 @@ var Judge = class {
   getAIConfig() {
     return this._aiConfig;
   }
-  /**
-   * Returns the tracker associated with this judge.
-   */
-  getTracker() {
-    return this._aiConfigTracker;
-  }
   /**
    * Returns the AI provider used by this judge.
    */
@@ -461,43 +673,23 @@ var Judge = class {
     return Mustache.render(content, variables, void 0, { escape: (item) => item });
   }
   /**
-   * Parses the structured evaluation response from the AI provider.
+   * Parses the structured evaluation response. Expects top-level {score, reasoning}.
+   * Returns score and reasoning, or undefined if parsing fails.
    */
-  _parseEvaluationResponse(data, evaluationMetricKey) {
-    const evaluations = data.evaluations;
-    const results = {};
-    if (!data.evaluations || typeof data.evaluations !== "object") {
-      this._logger?.warn("Invalid response: missing or invalid evaluations object");
-      return results;
-    }
-    const evaluation = evaluations[evaluationMetricKey];
-    if (!evaluation || typeof evaluation !== "object") {
-      this._logger?.warn(
-        `Missing evaluation for metric key: ${evaluationMetricKey}`,
-        this._aiConfigTracker.getTrackData()
-      );
-      return results;
+  _parseEvaluationResponse(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      return void 0;
     }
-    const evalData = evaluation;
-    if (typeof evalData.score !== "number" || evalData.score < 0 || evalData.score > 1) {
-      this._logger?.warn(
-        `Invalid score evaluated for ${evaluationMetricKey}: ${evalData.score}. Score must be a number between 0 and 1 inclusive`,
-        this._aiConfigTracker.getTrackData()
-      );
-      return results;
+    if (typeof data.score !== "number" || data.score < 0 || data.score > 1) {
+      return void 0;
     }
-    if (typeof evalData.reasoning !== "string") {
-      this._logger?.warn(
-        `Invalid reasoning evaluated for ${evaluationMetricKey}: ${evalData.reasoning}. Reasoning must be a string`,
-        this._aiConfigTracker.getTrackData()
-      );
-      return results;
+    if (typeof data.reasoning !== "string") {
+      return void 0;
     }
-    results[evaluationMetricKey] = {
-      score: evalData.score,
-      reasoning: evalData.reasoning
+    return {
+      score: data.score,
+      reasoning: data.reasoning
     };
-    return results;
   }
 };
 
@@ -697,27 +889,62 @@ function createVercelAISDKTokenUsage(data) {
 }
 
 // src/LDAIConfigTrackerImpl.ts
-var LDAIConfigTrackerImpl = class {
-  constructor(_ldClient, _configKey, _variationKey, _version, _modelName, _providerName, _context) {
+var LDAIConfigTrackerImpl = class _LDAIConfigTrackerImpl {
+  constructor(_ldClient, _runId, _configKey, _variationKey, _version, _modelName, _providerName, _context, _graphKey) {
     this._ldClient = _ldClient;
+    this._runId = _runId;
     this._configKey = _configKey;
     this._variationKey = _variationKey;
     this._version = _version;
     this._modelName = _modelName;
     this._providerName = _providerName;
     this._context = _context;
+    this._graphKey = _graphKey;
     this._trackedMetrics = {};
   }
   getTrackData() {
     return {
-      variationKey: this._variationKey,
+      runId: this._runId,
       configKey: this._configKey,
+      variationKey: this._variationKey,
       version: this._version,
       modelName: this._modelName,
-      providerName: this._providerName
+      providerName: this._providerName,
+      ...this._graphKey !== void 0 ? { graphKey: this._graphKey } : {}
     };
   }
+  get resumptionToken() {
+    const json = JSON.stringify({
+      runId: this._runId,
+      configKey: this._configKey,
+      variationKey: this._variationKey,
+      version: this._version,
+      ...this._graphKey !== void 0 ? { graphKey: this._graphKey } : {}
+    });
+    return Buffer.from(json).toString("base64url");
+  }
+  static fromResumptionToken(token, ldClient, context) {
+    const json = Buffer.from(token, "base64url").toString("utf8");
+    const payload = JSON.parse(json);
+    return new _LDAIConfigTrackerImpl(
+      ldClient,
+      payload.runId,
+      payload.configKey,
+      payload.variationKey ?? "",
+      payload.version,
+      "",
+      "",
+      context,
+      payload.graphKey
+    );
+  }
   trackDuration(duration) {
+    if (this._trackedMetrics.durationMs !== void 0) {
+      this._ldClient.logger?.warn(
+        "Duration has already been tracked for this execution. Use createTracker() for a new execution."
+      );
+      return;
+    }
     this._trackedMetrics.durationMs = duration;
     this._ldClient.track("$ld:ai:duration:total", this._context, this.getTrackData(), duration);
   }
@@ -733,6 +960,12 @@ var LDAIConfigTrackerImpl = class {
     }
   }
   trackTimeToFirstToken(timeToFirstTokenMs) {
+    if (this._trackedMetrics.timeToFirstTokenMs !== void 0) {
+      this._ldClient.logger?.warn(
+        "Time to first token has already been tracked for this execution. Use createTracker() for a new execution."
+      );
+      return;
+    }
     this._trackedMetrics.timeToFirstTokenMs = timeToFirstTokenMs;
     this._ldClient.track(
       "$ld:ai:tokens:ttf",
@@ -741,22 +974,30 @@ var LDAIConfigTrackerImpl = class {
       timeToFirstTokenMs
     );
   }
-  trackEvalScores(scores) {
-    Object.entries(scores).forEach(([metricKey, evalScore]) => {
-      this._ldClient.track(metricKey, this._context, this.getTrackData(), evalScore.score);
-    });
+  trackJudgeResult(result) {
+    if (!result.sampled || !result.success) {
+      return;
+    }
+    if (result.metricKey !== void 0 && result.score !== void 0) {
+      const trackData = result.judgeConfigKey ? { ...this.getTrackData(), judgeConfigKey: result.judgeConfigKey } : this.getTrackData();
+      this._ldClient.track(result.metricKey, this._context, trackData, result.score);
+    }
   }
-  trackJudgeResponse(response) {
-    Object.entries(response.evals).forEach(([metricKey, evalScore]) => {
-      this._ldClient.track(
-        metricKey,
-        this._context,
-        { ...this.getTrackData(), judgeConfigKey: response.judgeConfigKey },
-        evalScore.score
-      );
+  trackToolCall(toolKey) {
+    this._ldClient.track("$ld:ai:tool_call", this._context, { ...this.getTrackData(), toolKey }, 1);
+  }
+  trackToolCalls(toolKeys) {
+    toolKeys.forEach((toolKey) => {
+      this.trackToolCall(toolKey);
     });
   }
   trackFeedback(feedback) {
+    if (this._trackedMetrics.feedback !== void 0) {
+      this._ldClient.logger?.warn(
+        "Feedback has already been tracked for this execution. Use createTracker() for a new execution."
+      );
+      return;
+    }
     this._trackedMetrics.feedback = feedback;
     if (feedback.kind === "positive" /* Positive */) {
       this._ldClient.track("$ld:ai:feedback:user:positive", this._context, this.getTrackData(), 1);
@@ -765,10 +1006,22 @@ var LDAIConfigTrackerImpl = class {
     }
   }
   trackSuccess() {
+    if (this._trackedMetrics.success !== void 0) {
+      this._ldClient.logger?.warn(
+        "Generation result has already been tracked for this execution. Use createTracker() for a new execution."
+      );
+      return;
+    }
     this._trackedMetrics.success = true;
     this._ldClient.track("$ld:ai:generation:success", this._context, this.getTrackData(), 1);
   }
   trackError() {
+    if (this._trackedMetrics.success !== void 0) {
+      this._ldClient.logger?.warn(
+        "Generation result has already been tracked for this execution. Use createTracker() for a new execution."
+      );
+      return;
+    }
     this._trackedMetrics.success = false;
     this._ldClient.track("$ld:ai:generation:error", this._context, this.getTrackData(), 1);
   }
@@ -861,6 +1114,12 @@ var LDAIConfigTrackerImpl = class {
     }
   }
   trackTokens(tokens) {
+    if (this._trackedMetrics.tokens !== void 0) {
+      this._ldClient.logger?.warn(
+        "Token usage has already been tracked for this execution. Use createTracker() for a new execution."
+      );
+      return;
+    }
     this._trackedMetrics.tokens = tokens;
     const trackData = this.getTrackData();
     if (tokens.total > 0) {
@@ -881,9 +1140,155 @@ var LDAIConfigTrackerImpl = class {
   }
 };
 
+// src/LDGraphTrackerImpl.ts
+var LDGraphTrackerImpl = class _LDGraphTrackerImpl {
+  constructor(_ldClient, _runId, _graphKey, _variationKey, _version, _context) {
+    this._ldClient = _ldClient;
+    this._runId = _runId;
+    this._graphKey = _graphKey;
+    this._variationKey = _variationKey;
+    this._version = _version;
+    this._context = _context;
+    this._summary = {};
+  }
+  /**
+   * Reconstructs an {@link LDGraphTrackerImpl} from a resumption token, preserving
+   * the original `runId` so all events continue to be correlated under the same run.
+   *
+   * **Security note:** The token contains the flag variation key and version.
+   * Do not pass the raw token to untrusted clients.
+   *
+   * @param token URL-safe Base64-encoded token produced by {@link LDGraphTrackerImpl.resumptionToken}.
+   * @param ldClient LaunchDarkly client instance.
+   * @param context LDContext for the new tracker.
+   */
+  static fromResumptionToken(token, ldClient, context) {
+    const json = Buffer.from(token, "base64url").toString("utf8");
+    const data = JSON.parse(json);
+    return new _LDGraphTrackerImpl(
+      ldClient,
+      data.runId,
+      data.graphKey,
+      data.variationKey,
+      data.version,
+      context
+    );
+  }
+  getTrackData() {
+    const data = {
+      runId: this._runId,
+      graphKey: this._graphKey,
+      version: this._version
+    };
+    if (this._variationKey !== void 0) {
+      data.variationKey = this._variationKey;
+    }
+    return data;
+  }
+  getSummary() {
+    return { ...this._summary };
+  }
+  get resumptionToken() {
+    const parts = [
+      `"runId":${JSON.stringify(this._runId)}`,
+      `"graphKey":${JSON.stringify(this._graphKey)}`
+    ];
+    if (this._variationKey !== void 0) {
+      parts.push(`"variationKey":${JSON.stringify(this._variationKey)}`);
+    }
+    parts.push(`"version":${this._version}`);
+    const json = `{${parts.join(",")}}`;
+    return Buffer.from(json).toString("base64url");
+  }
+  trackInvocationSuccess() {
+    if (this._summary.success !== void 0) {
+      this._ldClient.logger?.warn(
+        "LDGraphTracker: invocation success/failure already recorded for this run \u2014 dropping duplicate call."
+      );
+      return;
+    }
+    this._summary.success = true;
+    this._ldClient.track("$ld:ai:graph:invocation_success", this._context, this.getTrackData(), 1);
+  }
+  trackInvocationFailure() {
+    if (this._summary.success !== void 0) {
+      this._ldClient.logger?.warn(
+        "LDGraphTracker: invocation success/failure already recorded for this run \u2014 dropping duplicate call."
+      );
+      return;
+    }
+    this._summary.success = false;
+    this._ldClient.track("$ld:ai:graph:invocation_failure", this._context, this.getTrackData(), 1);
+  }
+  trackDuration(durationMs) {
+    if (this._summary.durationMs !== void 0) {
+      this._ldClient.logger?.warn(
+        "LDGraphTracker: trackDuration already called for this run \u2014 dropping duplicate call."
+      );
+      return;
+    }
+    this._summary.durationMs = durationMs;
+    this._ldClient.track(
+      "$ld:ai:graph:duration:total",
+      this._context,
+      this.getTrackData(),
+      durationMs
+    );
+  }
+  trackTotalTokens(tokens) {
+    if (this._summary.tokens !== void 0) {
+      this._ldClient.logger?.warn(
+        "LDGraphTracker: trackTotalTokens already called for this run \u2014 dropping duplicate call."
+      );
+      return;
+    }
+    this._summary.tokens = { ...tokens };
+    this._ldClient.track(
+      "$ld:ai:graph:total_tokens",
+      this._context,
+      this.getTrackData(),
+      tokens.total
+    );
+  }
+  trackPath(path) {
+    if (this._summary.path !== void 0) {
+      this._ldClient.logger?.warn(
+        "LDGraphTracker: trackPath already called for this run \u2014 dropping duplicate call."
+      );
+      return;
+    }
+    this._summary.path = [...path];
+    this._ldClient.track("$ld:ai:graph:path", this._context, { ...this.getTrackData(), path }, 1);
+  }
+  trackRedirect(sourceKey, redirectedTarget) {
+    this._ldClient.track(
+      "$ld:ai:graph:redirect",
+      this._context,
+      { ...this.getTrackData(), sourceKey, redirectedTarget },
+      1
+    );
+  }
+  trackHandoffSuccess(sourceKey, targetKey) {
+    this._ldClient.track(
+      "$ld:ai:graph:handoff_success",
+      this._context,
+      { ...this.getTrackData(), sourceKey, targetKey },
+      1
+    );
+  }
+  trackHandoffFailure(sourceKey, targetKey) {
+    this._ldClient.track(
+      "$ld:ai:graph:handoff_failure",
+      this._context,
+      { ...this.getTrackData(), sourceKey, targetKey },
+      1
+    );
+  }
+};
+
 // src/sdkInfo.ts
 var aiSdkName = "@launchdarkly/server-sdk-ai";
-var aiSdkVersion = "0.16.7";
+var aiSdkVersion = "0.17.0";
 var aiSdkLanguage = "javascript";
 
 // src/LDAIClientImpl.ts
@@ -894,6 +1299,7 @@ var TRACK_USAGE_JUDGE_CONFIG = "$ld:ai:usage:judge-config";
 var TRACK_USAGE_CREATE_JUDGE = "$ld:ai:usage:create-judge";
 var TRACK_USAGE_AGENT_CONFIG = "$ld:ai:usage:agent-config";
 var TRACK_USAGE_AGENT_CONFIGS = "$ld:ai:usage:agent-configs";
+var TRACK_USAGE_AGENT_GRAPH = "$ld:ai:usage:agent-graph";
 var INIT_TRACK_CONTEXT = {
   kind: "ld_ai",
   key: "ld-internal-tracking",
@@ -918,7 +1324,7 @@ var LDAIClientImpl = class {
   _interpolateTemplate(template, variables) {
     return Mustache2.render(template, variables, void 0, { escape: (item) => item });
   }
-  async _evaluate(key, context, defaultValue, mode, variables) {
+  async _evaluate(key, context, defaultValue, mode, variables, graphKey) {
     const ldFlagValue = LDAIConfigUtils.toFlagValue(defaultValue, mode);
     const value = await this._ldClient.variation(key, context, ldFlagValue);
     const flagMode = value._ldMeta?.mode ?? "completion";
@@ -928,8 +1334,9 @@ var LDAIClientImpl = class {
       );
       return LDAIConfigUtils.createDisabledConfig(key, mode);
     }
-    const tracker = new LDAIConfigTrackerImpl(
+    const trackerFactory = () => new LDAIConfigTrackerImpl(
       this._ldClient,
+      randomUUID(),
       key,
       // eslint-disable-next-line no-underscore-dangle
       value._ldMeta?.variationKey ?? "",
@@ -937,9 +1344,10 @@ var LDAIClientImpl = class {
       value._ldMeta?.version ?? 1,
       value.model?.name ?? "",
       value.provider?.name ?? "",
-      context
+      context,
+      graphKey
     );
-    const config = LDAIConfigUtils.fromFlagValue(key, value, tracker);
+    const config = LDAIConfigUtils.fromFlagValue(key, value, trackerFactory);
     return this._applyInterpolation(config, context, variables);
   }
   _applyInterpolation(config, context, variables) {
@@ -1003,16 +1411,13 @@ var LDAIClientImpl = class {
     this._ldClient.track(TRACK_USAGE_JUDGE_CONFIG, context, key, 1);
     return this._judgeConfig(key, context, defaultValue ?? disabledAIConfig, variables);
   }
+  async _agentConfig(key, context, defaultValue, variables, graphKey) {
+    const config = await this._evaluate(key, context, defaultValue, "agent", variables, graphKey);
+    return config;
+  }
   async agentConfig(key, context, defaultValue, variables) {
     this._ldClient.track(TRACK_USAGE_AGENT_CONFIG, context, key, 1);
-    const config = await this._evaluate(
-      key,
-      context,
-      defaultValue ?? disabledAIConfig,
-      "agent",
-      variables
-    );
-    return config;
+    return this._agentConfig(key, context, defaultValue ?? disabledAIConfig, variables);
   }
   /**
    * @deprecated Use `agentConfig` instead. This method will be removed in a future version.
@@ -1030,11 +1435,10 @@ var LDAIClientImpl = class {
     const agents = {};
     await Promise.all(
       agentConfigs.map(async (config) => {
-        const agent = await this._evaluate(
+        const agent = await this._agentConfig(
           config.key,
           context,
           config.defaultValue ?? disabledAIConfig,
-          "agent",
           config.variables
         );
         agents[config.key] = agent;
@@ -1056,7 +1460,7 @@ var LDAIClientImpl = class {
       defaultValue ?? disabledAIConfig,
       variables
     );
-    if (!config.enabled || !config.tracker) {
+    if (!config.enabled) {
       this._logger?.info(`Chat configuration is disabled: ${key}`);
       return void 0;
     }
@@ -1070,7 +1474,7 @@ var LDAIClientImpl = class {
       variables,
       defaultAiProvider
     );
-    return new TrackedChat(config, config.tracker, provider, judges, this._logger);
+    return new TrackedChat(config, provider, judges, this._logger);
   }
   async createJudge(key, context, defaultValue, variables, defaultAiProvider) {
     this._ldClient.track(TRACK_USAGE_CREATE_JUDGE, context, key, 1);
@@ -1096,7 +1500,7 @@ var LDAIClientImpl = class {
         defaultValue ?? disabledAIConfig,
         extendedVariables
       );
-      if (!judgeConfig.enabled || !judgeConfig.tracker) {
+      if (!judgeConfig.enabled) {
         this._logger?.info(`Judge configuration is disabled: ${key}`);
         return void 0;
       }
@@ -1104,7 +1508,7 @@ var LDAIClientImpl = class {
       if (!provider) {
         return void 0;
       }
-      return new Judge(judgeConfig, judgeConfig.tracker, provider, this._logger);
+      return new Judge(judgeConfig, provider, this._logger);
     } catch (error) {
       this._logger?.error(`Failed to initialize judge ${key}:`, error);
       return void 0;
@@ -1116,6 +1520,81 @@ var LDAIClientImpl = class {
   async initChat(key, context, defaultValue, variables, defaultAiProvider) {
     return this.createChat(key, context, defaultValue, variables, defaultAiProvider);
   }
+  createTracker(token, context) {
+    return LDAIConfigTrackerImpl.fromResumptionToken(token, this._ldClient, context);
+  }
+  async agentGraph(graphKey, context, variables) {
+    this._ldClient.track(TRACK_USAGE_AGENT_GRAPH, context, graphKey, 1);
+    const defaultGraphValue = { root: "" };
+    const graphFlagValue = await this._ldClient.variation(
+      graphKey,
+      context,
+      defaultGraphValue
+    );
+    const variationKey = graphFlagValue._ldMeta?.variationKey;
+    const version = graphFlagValue._ldMeta?.version ?? 1;
+    const ldClient = this._ldClient;
+    const trackerFactory = () => new LDGraphTrackerImpl(ldClient, randomUUID(), graphKey, variationKey, version, context);
+    const disabled = new AgentGraphDefinition(graphFlagValue, {}, false, trackerFactory);
+    if (graphFlagValue._ldMeta?.enabled === false) {
+      this._logger?.debug(`agentGraph: graph "${graphKey}" is disabled.`);
+      return disabled;
+    }
+    if (!graphFlagValue.root) {
+      this._logger?.debug(`agentGraph: graph "${graphKey}" is not fetchable or has no root node.`);
+      return disabled;
+    }
+    const allKeys = AgentGraphDefinition.collectAllKeys(graphFlagValue);
+    const reachableKeys = this._collectReachableKeys(graphFlagValue);
+    const unreachableKey = [...allKeys].find((key) => !reachableKeys.has(key));
+    if (unreachableKey) {
+      this._logger?.debug(
+        `agentGraph: graph "${graphKey}" has unconnected node "${unreachableKey}" that is not reachable from the root.`
+      );
+      return disabled;
+    }
+    const agentConfigs = {};
+    const fetchResults = await Promise.all(
+      [...allKeys].map(async (key) => {
+        const config = await this._agentConfig(key, context, disabledAIConfig, variables, graphKey);
+        return { key, config };
+      })
+    );
+    const disabledResult = fetchResults.find(({ config }) => !config.enabled);
+    if (disabledResult) {
+      this._logger?.debug(
+        `agentGraph: agent config "${disabledResult.key}" in graph "${graphKey}" is not enabled or could not be fetched.`
+      );
+      return disabled;
+    }
+    fetchResults.forEach(({ key, config }) => {
+      agentConfigs[key] = config;
+    });
+    const nodes = AgentGraphDefinition.buildNodes(graphFlagValue, agentConfigs);
+    return new AgentGraphDefinition(graphFlagValue, nodes, true, trackerFactory);
+  }
+  createGraphTracker(token, context) {
+    return LDGraphTrackerImpl.fromResumptionToken(token, this._ldClient, context);
+  }
+  /**
+   * Returns the set of all node keys reachable from the root via BFS.
+   */
+  _collectReachableKeys(graph) {
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [graph.root];
+    visited.add(graph.root);
+    while (queue.length > 0) {
+      const key = queue.shift();
+      const edges = graph.edges?.[key] ?? [];
+      edges.forEach((edge) => {
+        if (!visited.has(edge.key)) {
+          visited.add(edge.key);
+          queue.push(edge.key);
+        }
+      });
+    }
+    return visited;
+  }
 };
 
 // src/index.ts
@@ -1125,8 +1604,11 @@ function initAi(ldClient) {
 export {
   AIProvider,
   AIProviderFactory,
+  AgentGraphDefinition,
+  AgentGraphNode,
   Judge,
   LDFeedbackKind,
+  LDGraphTrackerImpl,
   SUPPORTED_AI_PROVIDERS,
   TrackedChat,
   createBedrockTokenUsage,