feat: Add ManagedGraphResult, GraphMetricSummary, and AgentGraphRunnerResult types

- Add GraphMetrics dataclass (runner-layer return type for graph runs)
- Add GraphMetricSummary dataclass (managed-layer metrics, analogous to
  LDAIMetricSummary for single-model invocations)
- Add ManagedGraphResult dataclass (managed-layer return type from ManagedAgentGraph)
- Add AgentGraphRunnerResult dataclass (future runner return type, no evaluations field)
- ManagedAgentGraph.run() now returns ManagedGraphResult with GraphMetricSummary
  built from the runner's AgentGraphResult metrics
- Export all new types from ldai package

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jsonbailey

packages/sdk/server-ai/src/ldai/__init__.py

@@ -34,8 +34,12 @@
 from ldai.providers import (
     AgentGraphResult,
     AgentGraphRunner,
+    AgentGraphRunnerResult,
     AgentResult,
     AgentRunner,
+    GraphMetrics,
+    GraphMetricSummary,
+    ManagedGraphResult,
     ManagedResult,
     Runner,
     RunnerResult,
@@ -51,6 +55,10 @@
     'AgentGraphRunner',
     'AgentResult',
     'AgentGraphResult',
+    'AgentGraphRunnerResult',
+    'GraphMetrics',
+    'GraphMetricSummary',
+    'ManagedGraphResult',
     'ManagedResult',
     'Runner',
     'RunnerResult',

packages/sdk/server-ai/src/ldai/managed_agent_graph.py

@@ -1,17 +1,19 @@
 """ManagedAgentGraph — LaunchDarkly managed wrapper for agent graph execution."""
 
-from typing import Any
+import asyncio
+from typing import Any, List
 
 from ldai.providers import AgentGraphResult, AgentGraphRunner
+from ldai.providers.types import GraphMetricSummary, JudgeResult, ManagedGraphResult
 
 
 class ManagedAgentGraph:
     """
     LaunchDarkly managed wrapper for AI agent graph execution.
 
-    Holds an AgentGraphRunner. Auto-tracking of path,
-    tool calls, handoffs, latency, and invocation success/failure is handled
-    by the runner implementation.
+    Holds an AgentGraphRunner. Wraps the runner result in a
+    :class:`~ldai.providers.types.ManagedGraphResult` and builds a
+    :class:`~ldai.providers.types.GraphMetricSummary` from the runner's metrics.
 
     Obtain an instance via ``LDAIClient.create_agent_graph()``.
     """
@@ -27,17 +29,37 @@ def __init__(
         """
         self._runner = runner
 
-    async def run(self, input: Any) -> AgentGraphResult:
+    async def run(self, input: Any) -> ManagedGraphResult:
         """
         Run the agent graph with the given input.
 
-        Delegates to the underlying AgentGraphRunner, which handles
-        execution and all auto-tracking internally.
+        Delegates to the underlying AgentGraphRunner, builds a
+        :class:`GraphMetricSummary` from the result, and wraps everything in a
+        :class:`ManagedGraphResult`.
 
         :param input: The input prompt or structured input for the graph
-        :return: AgentGraphResult containing the output, raw response, and metrics
+        :return: ManagedGraphResult containing the content, metric summary, raw response,
+            and an optional evaluations task (currently always ``None`` for graphs —
+            per-graph evaluations will be added in a future PR).
         """
-        return await self._runner.run(input)
+        result: AgentGraphResult = await self._runner.run(input)
+
+        # Build a GraphMetricSummary from the runner result's LDAIMetrics.
+        # path and node_metrics will be populated once graph runners are migrated
+        # to return AgentGraphRunnerResult with GraphMetrics (PR 11).
+        metrics = result.metrics
+        summary = GraphMetricSummary(
+            success=metrics.success,
+            usage=metrics.usage,
+            duration_ms=getattr(metrics, 'duration_ms', None),
+        )
+
+        return ManagedGraphResult(
+            content=result.output,
+            metrics=summary,
+            raw=result.raw,
+            evaluations=None,
+        )
 
     def get_agent_graph_runner(self) -> AgentGraphRunner:
         """

packages/sdk/server-ai/src/ldai/providers/__init__.py

@@ -6,9 +6,13 @@
 from ldai.providers.runner_factory import RunnerFactory
 from ldai.providers.types import (
     AgentGraphResult,
+    AgentGraphRunnerResult,
     AgentResult,
+    GraphMetrics,
+    GraphMetricSummary,
     JudgeResult,
     LDAIMetrics,
+    ManagedGraphResult,
     ManagedResult,
     ModelResponse,
     RunnerResult,
@@ -20,10 +24,14 @@
     'AIProvider',
     'AgentGraphResult',
     'AgentGraphRunner',
+    'AgentGraphRunnerResult',
     'AgentResult',
     'AgentRunner',
+    'GraphMetrics',
+    'GraphMetricSummary',
     'JudgeResult',
     'LDAIMetrics',
+    'ManagedGraphResult',
     'ManagedResult',
     'ModelResponse',
     'ModelRunner',

packages/sdk/server-ai/src/ldai/providers/types.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, List, Optional
 
 from ldai.models import LDMessage
@@ -87,6 +87,81 @@ class ManagedResult:
     evaluations: Optional[asyncio.Task[List[JudgeResult]]] = None
 
 
+@dataclass
+class GraphMetrics:
+    """
+    Metrics from a single agent graph run.
+
+    Returned by graph runner implementations (e.g. ``OpenAIAgentGraphRunner``,
+    ``LangGraphAgentGraphRunner``) and consumed by :class:`ManagedAgentGraph` to
+    build a :class:`GraphMetricSummary`.
+
+    ``path`` is the ordered list of node keys visited during the run.
+    ``node_metrics`` maps node keys to the :class:`LDAIMetrics` recorded for each
+    node.  Both fields default to empty so that runners that do not yet populate
+    them remain compatible.
+    """
+    success: bool
+    path: List[str] = field(default_factory=list)
+    duration_ms: Optional[int] = None
+    usage: Optional[TokenUsage] = None
+    node_metrics: Dict[str, LDAIMetrics] = field(default_factory=dict)
+
+
+@dataclass
+class GraphMetricSummary:
+    """
+    Summary of metrics for an agent graph run, as returned by
+    :attr:`ManagedGraphResult.metrics`.
+
+    Mirrors :class:`LDAIMetricSummary` for single-model invocations but adds
+    graph-specific fields (``path``, ``node_metrics``).
+
+    ``resumption_token`` is set from the graph tracker at instantiation so it is
+    always available on the returned result.
+    """
+    success: bool
+    path: List[str] = field(default_factory=list)
+    duration_ms: Optional[int] = None
+    usage: Optional[TokenUsage] = None
+    node_metrics: Dict[str, LDAIMetrics] = field(default_factory=dict)
+    resumption_token: Optional[str] = None
+
+
+@dataclass
+class ManagedGraphResult:
+    """
+    Result returned by :class:`~ldai.ManagedAgentGraph` after a single graph run.
+
+    ``metrics`` is a :class:`GraphMetricSummary` built from the runner result and
+    the graph tracker.
+    ``evaluations`` is an optional asyncio Task that resolves to a list of
+    :class:`JudgeResult` instances when awaited.
+    """
+    content: str
+    metrics: GraphMetricSummary
+    raw: Optional[Any] = None
+    evaluations: Optional[asyncio.Task[List[JudgeResult]]] = None
+
+
+@dataclass
+class AgentGraphRunnerResult:
+    """
+    Result returned by an agent graph runner (e.g. ``OpenAIAgentGraphRunner``).
+
+    This is the new runner-layer return type for graph runners. ``evaluations``
+    is intentionally absent — evaluations are dispatched by the managed layer
+    and live on :class:`ManagedGraphResult`.
+
+    .. note::
+        Graph runners have not yet been migrated to return this type (that is
+        PR 11). Until then, :class:`AgentGraphResult` is still in use.
+    """
+    content: str
+    metrics: GraphMetrics
+    raw: Optional[Any] = None
+
+
 @dataclass
 class ModelResponse:
     """
@@ -166,6 +241,12 @@ class AgentResult:
 class AgentGraphResult:
     """
     Result from an agent graph run.
+
+    .. deprecated::
+        Use :class:`AgentGraphRunnerResult` (runner layer) and
+        :class:`ManagedGraphResult` (managed layer) instead. This type is
+        retained for backward compatibility with existing graph runners until
+        PR 11 migrates them to return :class:`AgentGraphRunnerResult`.
     """
     output: str
     raw: Any

packages/sdk/server-ai/src/ldai/tracker.py

@@ -410,17 +410,6 @@ def track_feedback(self, feedback: Dict[str, FeedbackKind]) -> None:
                 1,
             )
 
-    def track_tool_calls(self, tool_calls: List[str]) -> None:
-        """
-        Track the tool calls made during an AI operation.
-
-        :param tool_calls: List of tool call names.
-        """
-        if self._summary.tool_calls is not None:
-            log.warning("Tool calls have already been tracked for this execution. %s", self.__get_track_data())
-            return
-        self._summary._tool_calls = list(tool_calls)
-
     def track_success(self) -> None:
         """
         Track a successful AI generation.
@@ -560,9 +549,20 @@ def track_tool_calls(self, tool_keys: Iterable[str]) -> None:
         """
         Track multiple tool invocations for this configuration.
 
+        Records the tool keys on :class:`LDAIMetricSummary` and emits a
+        ``$ld:ai:tool_call`` event for each one.
+
         :param tool_keys: Tool identifiers (e.g. from a model response).
         """
-        for tool_key in tool_keys:
+        if self._summary.tool_calls is not None:
+            log.warning(
+                "Tool calls have already been tracked for this execution. %s",
+                self.__get_track_data(),
+            )
+            return
+        keys = list(tool_keys)
+        self._summary._tool_calls = keys
+        for tool_key in keys:
             self.track_tool_call(tool_key)
 
     def get_summary(self) -> LDAIMetricSummary:

packages/sdk/server-ai/tests/test_managed_agent_graph.py

@@ -5,7 +5,7 @@
 from ldclient import Config, Context, LDClient
 from ldclient.integrations.test_data import TestData
 
-from ldai import LDAIClient, ManagedAgentGraph
+from ldai import LDAIClient, ManagedAgentGraph, ManagedGraphResult
 from ldai.providers.types import LDAIMetrics
 from ldai.providers import AgentGraphResult, AgentGraphRunner, ToolRegistry
 
@@ -31,7 +31,8 @@ async def test_managed_agent_graph_run_delegates_to_runner():
     runner = StubAgentGraphRunner("hello world")
     managed = ManagedAgentGraph(runner)
     result = await managed.run("test input")
-    assert result.output == "hello world"
+    assert isinstance(result, ManagedGraphResult)
+    assert result.content == "hello world"
     assert result.metrics.success is True
 
 
@@ -172,7 +173,8 @@ async def test_create_agent_graph_run_produces_result(ldai_client: LDAIClient):
 
     assert managed is not None
     result = await managed.run("find restaurants")
-    assert result.output == "final answer"
+    assert isinstance(result, ManagedGraphResult)
+    assert result.content == "final answer"
     assert result.metrics.success is True