Summary

Adds first-class support for agent graphs to LaunchDarkly.ServerSdk.Ai. An agent graph is a LaunchDarkly-managed directed graph whose nodes are existing LdAiAgentConfigs and whose edges describe handoffs between agents. The SDK fetches the graph flag, resolves every referenced agent config, validates connectivity, and hands the caller a typed object they can traverse and instrument — without exposing the underlying flag shape.

AgentGraph and CreateGraphTracker on ILdAiGraphClient

// New interface — does not modify ILdAiClient
public interface ILdAiGraphClient
{
    AgentGraphDefinition AgentGraph(
        string graphKey,
        Context context,
        IReadOnlyDictionary<string, object> variables = null);

    AiGraphTracker CreateGraphTracker(string resumptionToken, Context context);
}

LdAiClient now implements both ILdAiClient and the new ILdAiGraphClient. The existing ILdAiClient interface is unchanged — no members added, removed, or modified. Graph functionality lives entirely on the separate ILdAiGraphClient interface, making this a purely additive change.

AgentGraph fires a $ld:ai:usage:agent-graph usage event, evaluates the graph flag, fetches every child LdAiAgentConfig, runs connectivity validation, and returns an AgentGraphDefinition. The returned definition's Enabled property reflects the result of all validation checks combined: _ldMeta.enabled, root present, every node reachable from the root, and every child agent config fetchable and enabled. When any check fails, the SDK logs a warning and returns a disabled definition whose traversal/inspection methods are safe no-ops; only GetConfig() (raw flag value + _ldMeta) and CreateTracker() remain meaningful.

CreateGraphTracker reconstructs an AiGraphTracker from a base64url resumption token, enabling cross-process continuation (e.g. emitting graph-level events from a worker that didn't run the original evaluation).

AgentGraphDefinition

public AgentGraphNode RootNode();
public AgentGraphNode GetNode(string nodeKey);
public IReadOnlyList<AgentGraphNode> GetChildNodes(string nodeKey);
public IReadOnlyList<AgentGraphNode> GetParentNodes(string nodeKey);
public IReadOnlyList<AgentGraphNode> TerminalNodes();
public AgentGraphFlagValue GetConfig();
public AiGraphTracker CreateTracker();

public void Traverse(
    Func<AgentGraphNode, Dictionary<string, object>, object> fn,
    Dictionary<string, object> initialContext = null);

public void ReverseTraverse(
    Func<AgentGraphNode, Dictionary<string, object>, object> fn,
    Dictionary<string, object> initialContext = null);

Traverse does a breadth-first walk from the root; ReverseTraverse walks from terminals back toward the root (the root is always processed last unless it is the only node). Both are cycle-safe — each node is visited at most once. The callback receives the current node and an accumulator dictionary; whatever the callback returns is stored in the accumulator under that node's key and is visible to subsequent visits.

Node and edge types

• AgentGraphNode — wraps an LdAiAgentConfig plus its outgoing GraphEdges and exposes IsTerminal (true when there are no outgoing edges). Per-node metrics are recorded via the wrapped config's existing CreateTracker().
• GraphEdge — record carrying the target Key and an optional Handoff dictionary (IReadOnlyDictionary<string, LdValue>). Handoff maps are wrapped in ReadOnlyDictionary to enforce immutability; edge lists are frozen via AsReadOnly().
• AgentGraphFlagValue / LdMeta — the parsed raw flag value, including _ldMeta. Always non-null on the returned definition, even when the graph is disabled.

AiGraphTracker

public void TrackInvocationSuccess();       // at-most-once (shares slot with TrackInvocationFailure)
public void TrackInvocationFailure();       // at-most-once
public void TrackDuration(double durationMs); // at-most-once
public void TrackTotalTokens(Usage tokens); // at-most-once (skips slot claim when usage is empty)
public void TrackPath(IReadOnlyList<string> path); // at-most-once

public void TrackRedirect(string sourceKey, string redirectedTarget); // multi-fire
public void TrackHandoffSuccess(string sourceKey, string targetKey);  // multi-fire
public void TrackHandoffFailure(string sourceKey, string targetKey);  // multi-fire

public string ResumptionToken { get; }
public AiGraphMetricSummary Summary { get; }
public AiGraphTrackData GetTrackData();
public static AiGraphTracker FromResumptionToken(string token, ILaunchDarklyClient client, Context context);

Graph-scoped tracker emitting $ld:ai:graph:* events. At-most-once methods use Interlocked.CompareExchange so the contract holds under racing callers — a second call logs a warning and is silently dropped. TrackTotalTokens short-circuits before claiming the slot when usage is empty, consistent with LdAiConfigTracker.TrackTokens. Multi-fire methods may be called once per edge traversal. Every event carries the standard runId + graphKey + version track data (plus variationKey when non-empty). ResumptionToken is a base64url-encoded JSON payload of those fields; FromResumptionToken validates and round-trips it, throwing ArgumentException on malformed or missing-required-fields input.

graphKey propagation through LdAiConfigTracker

When a per-node tracker is created via AgentGraph (rather than via the standalone AgentConfig path), the parent graph's key is threaded through to LdAiConfigTracker so every per-node event includes graphKey in its track data and resumption token. The wire format omits empty optional fields, so existing non-graph trackers continue to round-trip exactly.

Other touched files

• ConfigFactory.BuildAgentConfig and TrackerFactoryFor accept an optional graphKey parameter (default null). The default-path helper BuildAgentFromDefault is now internal (was private) so the graph code path can reuse it. All existing call sites are unchanged.
• Polyfills/IsExternalInit.cs enables init accessors and positional records on the net462/netstandard2.0 targets used by the new graph types.

Migration

None required. ILdAiClient is unchanged — no new members were added. Graph functionality is on the new ILdAiGraphClient interface, which LdAiClient implements alongside ILdAiClient. Existing consumers, including hand-rolled test doubles that implement ILdAiClient, will continue to compile and work without modification. The wire format is backward-compatible (the new graphKey field on config resumption tokens is omitted when empty).

Test plan

• dotnet build succeeds across netstandard2.0, net462, net6.0, net8.0
• dotnet test pkgs/sdk/server-ai/test/LaunchDarkly.ServerSdk.Ai.Tests.csproj --framework net8.0 passes
• AgentGraphDefinitionTest covers node lookup, parent/child/terminal queries, BFS and reverse-BFS traversal, cycle safety, and disabled-graph no-op behavior
• AiGraphTrackerTest covers track-data shape, at-most-once vs. multi-fire semantics, TrackTotalTokens empty-usage short-circuit, ResumptionToken round-trip, FromResumptionToken error handling, and the Summary snapshot
• LdAiAgentGraphConfigTest covers graphKey propagation into per-node track data and resumption tokens
• LdAiClientAgentGraphTest covers end-to-end AgentGraph retrieval and every validation path: disabled _ldMeta, missing root, unreachable node, and unfetchable/disabled child agent config — plus the $ld:ai:usage:agent-graph usage event
• Reviewer confirms graph event names, at-most-once semantics, and resumption-token wire format match the cross-SDK contract