feat: Add ManagedGraphResult, GraphMetricSummary, and AgentGraphRunnerResult types

jsonbailey · claude · jsonbailey · commit ba64a62f7d27 · 2026-04-29T08:49:46.000-05:00
- 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 &lt;noreply@anthropic.com&gt;
diff --git a/packages/sdk/server-ai/src/ldai/__init__.py b/packages/sdk/server-ai/src/ldai/__init__.py
@@ -34,7 +34,11 @@
 from ldai.providers import (
     AgentGraphResult,
     AgentGraphRunner,
+    AgentGraphRunnerResult,
     AgentRunner,
+    GraphMetrics,
+    GraphMetricSummary,
+    ManagedGraphResult,
     ManagedResult,
     Runner,
     RunnerResult,
@@ -49,6 +53,10 @@
     'AgentRunner',
     'AgentGraphRunner',
     'AgentGraphResult',
+    'AgentGraphRunnerResult',
+    'GraphMetrics',
+    'GraphMetricSummary',
+    'ManagedGraphResult',
     'ManagedResult',
     'Runner',
     'RunnerResult',
diff --git a/packages/sdk/server-ai/src/ldai/managed_agent_graph.py b/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:
         """
diff --git a/packages/sdk/server-ai/src/ldai/providers/__init__.py b/packages/sdk/server-ai/src/ldai/providers/__init__.py
@@ -6,8 +6,12 @@
 from ldai.providers.runner_factory import RunnerFactory
 from ldai.providers.types import (
     AgentGraphResult,
+    AgentGraphRunnerResult,
+    GraphMetrics,
+    GraphMetricSummary,
     JudgeResult,
     LDAIMetrics,
+    ManagedGraphResult,
     ManagedResult,
     RunnerResult,
     ToolRegistry,
@@ -17,9 +21,13 @@
     'AIProvider',
     'AgentGraphResult',
     'AgentGraphRunner',
+    'AgentGraphRunnerResult',
     'AgentRunner',
+    'GraphMetrics',
+    'GraphMetricSummary',
     'JudgeResult',
     'LDAIMetrics',
+    'ManagedGraphResult',
     'ManagedResult',
     'ModelRunner',
     'Runner',
diff --git a/packages/sdk/server-ai/src/ldai/providers/types.py b/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.tracker import LDAIMetricSummary, TokenUsage
@@ -86,6 +86,80 @@ class ManagedResult:
     """Optional asyncio Task that resolves to the list of :class:`JudgeResult` instances when awaited."""
 
 
+@dataclass
+class GraphMetrics:
+    """Contains raw metrics from a single agent graph run."""
+
+    success: bool
+    """Whether the graph run succeeded."""
+
+    path: List[str] = field(default_factory=list)
+    """Ordered list of node keys visited during the run."""
+
+    duration_ms: Optional[int] = None
+    """Wall-clock duration of the graph run in milliseconds."""
+
+    usage: Optional[TokenUsage] = None
+    """Optional aggregate token usage information across all nodes in the graph run."""
+
+    node_metrics: Dict[str, LDAIMetrics] = field(default_factory=dict)
+    """Per-node metrics keyed by node key."""
+
+
+@dataclass
+class GraphMetricSummary:
+    """Contains a summary of metrics for an agent graph run."""
+
+    success: bool
+    """Whether the graph run succeeded."""
+
+    path: List[str] = field(default_factory=list)
+    """Ordered list of node keys visited during the run."""
+
+    duration_ms: Optional[int] = None
+    """Wall-clock duration of the graph run in milliseconds."""
+
+    usage: Optional[TokenUsage] = None
+    """Optional aggregate token usage information across all nodes in the graph run."""
+
+    node_metrics: Dict[str, LDAIMetrics] = field(default_factory=dict)
+    """Per-node metrics keyed by node key."""
+
+    resumption_token: Optional[str] = None
+    """Optional resumption token from the graph tracker for cross-process resumption."""
+
+
+@dataclass
+class ManagedGraphResult:
+    """Contains the result of a managed agent graph run, including metrics and optional judge evaluations."""
+
+    content: str
+    """The graph's final output content."""
+
+    metrics: GraphMetricSummary
+    """Aggregated metric summary from the graph tracker for this run."""
+
+    raw: Optional[Any] = None
+    """Optional provider-native response object for advanced consumers."""
+
+    evaluations: Optional[asyncio.Task[List[JudgeResult]]] = None
+    """Optional asyncio Task that resolves to the list of :class:`JudgeResult` instances when awaited."""
+
+
+@dataclass
+class AgentGraphRunnerResult:
+    """Contains the result of an agent graph runner invocation."""
+
+    content: str
+    """The graph's final output content."""
+
+    metrics: GraphMetrics
+    """Metrics from the graph run."""
+
+    raw: Optional[Any] = None
+    """Optional provider-native response object for advanced consumers."""
+
+
 @dataclass
 class JudgeResult:
     """Contains the result of a single judge evaluation."""
diff --git a/packages/sdk/server-ai/src/ldai/tracker.py b/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:
diff --git a/packages/sdk/server-ai/tests/test_managed_agent_graph.py b/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
 
 
