adjust return types and graph tracker creation

Author: jsonbailey

packages/sdk/server-ai/src/LDAIClientImpl.ts

@@ -392,23 +392,26 @@ export class LDAIClientImpl implements LDAIClient {
     return LDAIConfigTrackerImpl.fromResumptionToken(token, this._ldClient, context);
   }
 
-  async agentGraph(
-    graphKey: string,
-    context: LDContext,
-  ): Promise<{ enabled: false } | { enabled: true; graph: AgentGraphDefinition }> {
+  async agentGraph(graphKey: string, context: LDContext): Promise<AgentGraphDefinition> {
     this._ldClient.track(TRACK_USAGE_AGENT_GRAPH, context, graphKey, 1);
 
-    const disabled = { enabled: false as const };
-
-    // Step 1: Fetch the graph flag value
     const defaultGraphValue: LDAgentGraphFlagValue = { root: '' };
     const graphFlagValue = (await this._ldClient.variation(
       graphKey,
       context,
       defaultGraphValue,
     )) as LDAgentGraphFlagValue;
 
-    // Step 2: Validate - graph must be enabled and have a root
+    // eslint-disable-next-line no-underscore-dangle
+    const variationKey = graphFlagValue._ldMeta?.variationKey;
+    // eslint-disable-next-line no-underscore-dangle
+    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);
+
     // eslint-disable-next-line no-underscore-dangle
     if (graphFlagValue._ldMeta?.enabled === false) {
       this._logger?.debug(`agentGraph: graph "${graphKey}" is disabled.`);
@@ -420,7 +423,6 @@ export class LDAIClientImpl implements LDAIClient {
       return disabled;
     }
 
-    // Step 3: Validate - collect all node keys and check connectivity from root
     const allKeys = AgentGraphDefinition.collectAllKeys(graphFlagValue);
     const reachableKeys = this._collectReachableKeys(graphFlagValue);
 
@@ -432,7 +434,6 @@ export class LDAIClientImpl implements LDAIClient {
       return disabled;
     }
 
-    // Step 4: Validate - fetch all child agent configs
     const agentConfigs: Record<string, LDAIAgentConfig> = {};
     const fetchResults = await Promise.all(
       [...allKeys].map(async (key) => {
@@ -452,23 +453,8 @@ export class LDAIClientImpl implements LDAIClient {
       agentConfigs[key] = config;
     });
 
-    // Build the node map
     const nodes = AgentGraphDefinition.buildNodes(graphFlagValue, agentConfigs);
-
-    // eslint-disable-next-line no-underscore-dangle
-    const variationKey = graphFlagValue._ldMeta?.variationKey;
-    // eslint-disable-next-line no-underscore-dangle
-    const version = graphFlagValue._ldMeta?.version ?? 1;
-    const ldClient = this._ldClient;
-
-    const graph = new AgentGraphDefinition(
-      graphFlagValue,
-      nodes,
-      () =>
-        new LDGraphTrackerImpl(ldClient, randomUUID(), graphKey, variationKey, version, context),
-    );
-
-    return { enabled: true, graph };
+    return new AgentGraphDefinition(graphFlagValue, nodes, true, trackerFactory);
   }
 
   createGraphTracker(token: string, context: LDContext): LDGraphTracker {

packages/sdk/server-ai/src/LDGraphTrackerImpl.ts

@@ -9,8 +9,8 @@ import type { LDClientMin } from './LDClientMin';
 /**
  * Concrete implementation of {@link LDGraphTracker}.
  *
- * Instantiate via {@link AgentGraphDefinition.createTracker} or reconstruct from
- * a resumption token via {@link LDGraphTrackerImpl.fromResumptionToken}.
+ * Construct directly or reconstruct from a resumption token via
+ * {@link LDGraphTrackerImpl.fromResumptionToken}.
  */
 export class LDGraphTrackerImpl implements LDGraphTracker {
   private _summary: LDGraphMetricSummary = {};

packages/sdk/server-ai/src/api/LDAIClient.ts

@@ -341,39 +341,36 @@ export interface LDAIClient {
 
   /**
    * Fetches an agent graph configuration from LaunchDarkly and returns an
-   * {@link AgentGraphDefinition} that can be traversed and tracked.
+   * {@link AgentGraphDefinition}.
    *
-   * The method validates that:
+   * When the graph is enabled the method validates that:
    * - The graph flag can be evaluated.
    * - A single root node is present.
    * - All nodes in the graph are reachable from the root (no disconnected nodes).
    * - Every referenced agent config can be fetched and is enabled.
    *
-   * If any validation check fails, `{ enabled: false }` is returned and, when the
-   * logger level is DEBUG, a warning is emitted describing the failure.
+   * If any validation check fails, the returned definition has
+   * {@link AgentGraphDefinition.enabled | enabled} set to `false` with an empty
+   * node collection. When the logger level is DEBUG, a message describing the
+   * failure is emitted.
    *
    * @param graphKey The LaunchDarkly flag key for the agent graph configuration.
    * @param context The LaunchDarkly context used for flag evaluation and tracking.
    *
-   * @returns A promise that resolves to `{ enabled: false }` when the graph is
-   *   invalid or disabled, or `{ enabled: true, graph: AgentGraphDefinition }` otherwise.
+   * @returns A promise that resolves to an {@link AgentGraphDefinition}. Check
+   *   {@link AgentGraphDefinition.enabled | enabled} before traversing.
    *
    * @example
    * ```typescript
-   * const result = await aiClient.agentGraph('my-agent-graph', context);
-   * if (result.enabled) {
-   *   const tracker = result.graph.createTracker();
-   *   result.graph.traverse((node, ctx) => {
+   * const graph = await aiClient.agentGraph('my-agent-graph', context);
+   * if (graph.enabled) {
+   *   graph.traverse((node, ctx) => {
    *     // build your provider-specific node here
    *   });
-   *   tracker.trackInvocationSuccess();
    * }
    * ```
    */
-  agentGraph(
-    graphKey: string,
-    context: LDContext,
-  ): Promise<{ enabled: false } | { enabled: true; graph: AgentGraphDefinition }>;
+  agentGraph(graphKey: string, context: LDContext): Promise<AgentGraphDefinition>;
 
   /**
    * Reconstructs an {@link LDGraphTracker} from a resumption token, preserving

packages/sdk/server-ai/src/api/graph/AgentGraphDefinition.ts

@@ -15,14 +15,17 @@ export type TraversalFn = (
  * Encapsulates an agent graph configuration and its pre-built node collection.
  *
  * Provides graph-level orchestration including relationship queries (parent/child),
- * breadth-first traversal in both forward and reverse directions, and tracker creation.
+ * breadth-first traversal in both forward and reverse directions, and graph tracker creation.
  *
- * Obtain an instance via {@link LDAIClient.agentGraph}.
+ * Obtain an instance via {@link LDAIClient.agentGraph}. When the graph is disabled
+ * or invalid, the returned instance has {@link enabled} set to `false` and an
+ * empty node collection.
  */
 export class AgentGraphDefinition {
   constructor(
     private readonly _agentGraph: LDAgentGraphFlagValue,
     private readonly _nodes: Record<string, AgentGraphNode>,
+    readonly enabled: boolean,
     private readonly _createTracker: () => LDGraphTracker,
   ) {}
 
@@ -52,22 +55,6 @@ export class AgentGraphDefinition {
     return nodes;
   }
 
-  /**
-   * Whether the graph is enabled. Always `true` for a successfully constructed definition
-   * (disabled graphs are not surfaced as AgentGraphDefinition instances).
-   */
-  get enabled(): boolean {
-    // eslint-disable-next-line no-underscore-dangle
-    return this._agentGraph._ldMeta?.enabled ?? true;
-  }
-
-  /**
-   * Returns whether the graph is enabled.
-   */
-  isEnabled(): boolean {
-    return this.enabled;
-  }
-
   /**
    * Returns the children of the node identified by `nodeKey`.
    *

packages/sdk/server-ai/src/api/graph/LDGraphTracker.ts

@@ -12,7 +12,7 @@ import type { LDGraphMetricSummary, LDGraphTrackData } from './types';
  *
  * @example
  * ```typescript
- * const tracker = graph.createTracker();
+ * const tracker = graphDefinition.createTracker();
  * try {
  *   // ... execute graph ...
  *   tracker.trackInvocationSuccess();