feat!: Replace AgentGraphDefinition.get_tracker() with create_tracker factory

Per AIGRAPH spec 1.4.3, AgentGraphDefinition now has a create_tracker
callable that returns a new AIGraphTracker per invocation instead of
storing a pre-created instance. Removes get_tracker() method entirely.

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

Author: jsonbailey

packages/ai-providers/server-ai-langchain/src/ldai_langchain/langgraph_agent_graph_runner.py

@@ -260,7 +260,7 @@ def route(state: WorkflowState) -> str:
 
         self._graph.traverse(fn=handle_traversal)
 
-        tracker = self._graph.get_tracker()
+        tracker = self._graph.create_tracker()
         graph_key_str = tracker.graph_key if tracker else 'unknown'
         log.debug(
             f"LangGraphAgentGraphRunner: graph='{graph_key_str}', root='{root_key}', "
@@ -281,7 +281,7 @@ async def run(self, input: Any) -> AgentGraphResult:
         :param input: The string prompt to send to the agent graph
         :return: AgentGraphResult with the final output and metrics
         """
-        tracker = self._graph.get_tracker()
+        tracker = self._graph.create_tracker()
         start_ns = time.perf_counter_ns()
 
         try:

packages/ai-providers/server-ai-langchain/tests/test_langgraph_agent_graph_runner.py

@@ -11,6 +11,7 @@
 
 
 def _make_graph(enabled: bool = True) -> AgentGraphDefinition:
+    graph_tracker = MagicMock()
     root_config = AIAgentConfig(
         key='root-agent',
         enabled=enabled,
@@ -30,7 +31,7 @@ def _make_graph(enabled: bool = True) -> AgentGraphDefinition:
         nodes=nodes,
         context=MagicMock(),
         enabled=enabled,
-        tracker=MagicMock(),
+        create_tracker=lambda: graph_tracker,
     )
 
 
@@ -77,7 +78,7 @@ async def test_langgraph_runner_run_raises_when_langgraph_not_installed():
 @pytest.mark.asyncio
 async def test_langgraph_runner_run_tracks_failure_on_exception():
     graph = _make_graph()
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
     runner = LangGraphAgentGraphRunner(graph, {})
 
     with patch.dict('sys.modules', {'langgraph': None, 'langgraph.graph': None}):
@@ -91,7 +92,7 @@ async def test_langgraph_runner_run_tracks_failure_on_exception():
 @pytest.mark.asyncio
 async def test_langgraph_runner_run_success():
     graph = _make_graph()
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
 
     mock_message = MagicMock()
     mock_message.content = "langgraph answer"

packages/ai-providers/server-ai-langchain/tests/test_langgraph_callback_handler.py

@@ -65,7 +65,7 @@ def _make_graph(mock_ld_client: MagicMock, node_key: str = 'root-agent', graph_k
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=graph_tracker,
+        create_tracker=lambda: graph_tracker,
     )
 
 
@@ -321,7 +321,7 @@ def test_flush_emits_token_events_to_ld_tracker():
     """flush() calls track_tokens on the node's config tracker."""
     mock_ld_client = MagicMock()
     graph = _make_graph(mock_ld_client, node_key='root-agent', graph_key='g1')
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
 
     handler = LDMetricsCallbackHandler({'root-agent'}, {})
     node_run_id = uuid4()
@@ -340,7 +340,7 @@ def test_flush_emits_duration():
     """flush() calls track_duration when duration was recorded."""
     mock_ld_client = MagicMock()
     graph = _make_graph(mock_ld_client)
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
 
     handler = LDMetricsCallbackHandler({'root-agent'}, {})
     run_id = uuid4()
@@ -356,7 +356,7 @@ def test_flush_emits_tool_calls():
     """flush() calls track_tool_call for each recorded tool invocation."""
     mock_ld_client = MagicMock()
     graph = _make_graph(mock_ld_client)
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
 
     handler = LDMetricsCallbackHandler({'root-agent'}, {'fn_search': 'search'})
     # The agent node must be started first so it appears in the path for flush()
@@ -378,7 +378,7 @@ def test_flush_includes_graph_key_in_node_events():
     """flush() passes graph_key to the node tracker so graphKey appears in events."""
     mock_ld_client = MagicMock()
     graph = _make_graph(mock_ld_client, graph_key='my-graph')
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
 
     handler = LDMetricsCallbackHandler({'root-agent'}, {})
     node_run_id = uuid4()
@@ -425,7 +425,7 @@ def test_flush_with_no_graph_key_on_node_tracker():
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=None,
+        create_tracker=lambda: None,
     )
 
     handler = LDMetricsCallbackHandler({'root-agent'}, {})
@@ -443,7 +443,7 @@ def test_flush_skips_nodes_not_in_path():
     """flush() only emits events for nodes that were actually executed."""
     mock_ld_client = MagicMock()
     graph = _make_graph(mock_ld_client)
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
 
     # Handler with 'root-agent' in node_keys but never started
     handler = LDMetricsCallbackHandler({'root-agent'}, {})
@@ -475,7 +475,7 @@ def test_flush_skips_node_without_tracker():
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=None,
+        create_tracker=lambda: None,
     )
 
     handler = LDMetricsCallbackHandler({'no-track'}, {})

packages/ai-providers/server-ai-langchain/tests/test_tracking_langgraph.py

@@ -85,7 +85,7 @@ def _make_graph(
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=graph_tracker,
+        create_tracker=lambda: graph_tracker,
     )
 
 
@@ -199,7 +199,7 @@ def _make_two_node_graph(mock_ld_client: MagicMock) -> 'AgentGraphDefinition':
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=graph_tracker,
+        create_tracker=lambda: graph_tracker,
     )
 
 
@@ -231,7 +231,7 @@ async def test_tracks_node_and_graph_tokens_on_success():
     # (mock models don't fire LangChain callbacks, so we test flush directly)
     mock_ld_client2 = MagicMock()
     graph2 = _make_graph(mock_ld_client2)
-    tracker2 = graph2.get_tracker()
+    tracker2 = graph2.create_tracker()
 
     handler = LDMetricsCallbackHandler({'root-agent'}, {})
     node_run_id = uuid4()
@@ -311,7 +311,7 @@ def get_weather(location: str = 'NYC') -> str:
     # Simulate tool call tracking via the callback handler directly
     mock_ld_client2 = MagicMock()
     graph2 = _make_graph(mock_ld_client2, tool_names=['get_weather'])
-    tracker2 = graph2.get_tracker()
+    tracker2 = graph2.create_tracker()
 
     handler = LDMetricsCallbackHandler({'root-agent'}, {'get_weather': 'get_weather'})
     # Agent node must appear in path for flush() to emit its events
@@ -363,7 +363,7 @@ def summarize(text: str = '') -> str:
     # Simulate multiple tool calls via the callback handler directly
     mock_ld_client2 = MagicMock()
     graph2 = _make_graph(mock_ld_client2, tool_names=['search', 'summarize'])
-    tracker2 = graph2.get_tracker()
+    tracker2 = graph2.create_tracker()
 
     fn_map = {'search': 'search', 'summarize': 'summarize'}
     handler = LDMetricsCallbackHandler({'root-agent'}, fn_map)
@@ -391,7 +391,7 @@ async def test_tracks_graph_key_on_node_events():
 
     mock_ld_client = MagicMock()
     graph = _make_graph(mock_ld_client, graph_key='my-graph')
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
 
     handler = LDMetricsCallbackHandler({'root-agent'}, {})
     node_run_id = uuid4()
@@ -464,7 +464,7 @@ def model_factory(node_config, **kwargs):
     # Simulate per-node token events via callback handler (mock models don't fire callbacks)
     mock_ld_client2 = MagicMock()
     graph2 = _make_two_node_graph(mock_ld_client2)
-    tracker2 = graph2.get_tracker()
+    tracker2 = graph2.create_tracker()
 
     handler = LDMetricsCallbackHandler({'root-agent', 'child-agent'}, {})
 
@@ -578,7 +578,7 @@ def _node_tracker(key: str) -> LDAIConfigTracker:
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=graph_tracker,
+        create_tracker=lambda: graph_tracker,
     )
 
 
@@ -691,7 +691,7 @@ def _node_tracker(key: str) -> LDAIConfigTracker:
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=graph_tracker,
+        create_tracker=lambda: graph_tracker,
     )
 
 

packages/ai-providers/server-ai-openai/src/ldai_openai/openai_agent_graph_runner.py

@@ -69,7 +69,7 @@ async def run(self, input: Any) -> AgentGraphResult:
         :param input: The string prompt to send to the agent graph
         :return: AgentGraphResult with the final output and metrics
         """
-        tracker = self._graph.get_tracker()
+        tracker = self._graph.create_tracker()
         path: List[str] = []
         root_node = self._graph.root()
         root_key = root_node.get_key() if root_node else ''
@@ -142,7 +142,7 @@ def _build_agents(self, path: List[str], state: _RunState) -> Any:
                 "Install it with: pip install openai-agents"
             ) from exc
 
-        tracker = self._graph.get_tracker()
+        tracker = self._graph.create_tracker()
         name_map: Dict[str, str] = {}
         tool_name_map: Dict[str, str] = {}
 

packages/ai-providers/server-ai-openai/tests/test_openai_agent_graph_runner.py

@@ -13,6 +13,7 @@
 def _make_graph(enabled: bool = True) -> AgentGraphDefinition:
     """Build a minimal single-node AgentGraphDefinition for testing."""
     node_tracker = MagicMock()
+    graph_tracker = MagicMock()
     root_config = AIAgentConfig(
         key='root-agent',
         enabled=enabled,
@@ -33,7 +34,7 @@ def _make_graph(enabled: bool = True) -> AgentGraphDefinition:
         nodes=nodes,
         context=MagicMock(),
         enabled=enabled,
-        tracker=MagicMock(),
+        create_tracker=lambda: graph_tracker,
     )
 
 
@@ -82,7 +83,7 @@ async def test_openai_agent_graph_runner_run_raises_when_agents_not_installed():
 @pytest.mark.asyncio
 async def test_openai_agent_graph_runner_run_tracks_invocation_failure_on_exception():
     graph = _make_graph()
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
     runner = OpenAIAgentGraphRunner(graph, {})
 
     with patch.dict('sys.modules', {'agents': None}):
@@ -96,7 +97,7 @@ async def test_openai_agent_graph_runner_run_tracks_invocation_failure_on_except
 @pytest.mark.asyncio
 async def test_openai_agent_graph_runner_run_success():
     graph = _make_graph()
-    tracker = graph.get_tracker()
+    tracker = graph.create_tracker()
 
     mock_result = MagicMock()
     mock_result.final_output = "agent answer"

packages/ai-providers/server-ai-openai/tests/test_tracking_openai_agents.py

@@ -80,7 +80,7 @@ def _make_graph(
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=graph_tracker,
+        create_tracker=lambda: graph_tracker,
     )
 
 
@@ -236,7 +236,7 @@ def _make_two_node_graph(mock_ld_client: MagicMock) -> AgentGraphDefinition:
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=graph_tracker,
+        create_tracker=lambda: graph_tracker,
     )
 
 

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

@@ -54,21 +54,13 @@ def __init__(
         nodes: Dict[str, AgentGraphNode],
         context: Context,
         enabled: bool,
-        tracker: Optional[AIGraphTracker] = None,
+        create_tracker: Callable[[], AIGraphTracker] = lambda: None,
     ):
         self._agent_graph = agent_graph
         self._context = context
         self._nodes = nodes
         self.enabled = enabled
-        self._tracker = tracker
-
-    def get_tracker(self) -> Optional[AIGraphTracker]:
-        """
-        Get the graph tracker for this graph definition.
-
-        :return: The AIGraphTracker instance, or None if not available.
-        """
-        return self._tracker
+        self.create_tracker = create_tracker
 
     def is_enabled(self) -> bool:
         """Check if the graph is enabled."""

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

@@ -596,14 +596,15 @@ def agent_graph(
         variation_key = variation.get("_ldMeta", {}).get("variationKey", "")
         version = int(variation.get("_ldMeta", {}).get("version", 1))
 
-        # Create graph tracker
-        tracker = AIGraphTracker(
-            self._client,
-            variation_key,
-            key,
-            version,
-            context,
-        )
+        # Create graph tracker factory
+        def graph_tracker_factory() -> AIGraphTracker:
+            return AIGraphTracker(
+                self._client,
+                variation_key,
+                key,
+                version,
+                context,
+            )
 
         if not variation.get("root"):
             log.debug(f"Agent graph {key} is disabled, no root config key found")
@@ -617,7 +618,7 @@ def agent_graph(
                 nodes={},
                 context=context,
                 enabled=False,
-                tracker=tracker,
+                create_tracker=graph_tracker_factory,
             )
 
         edge_keys = list[str](variation.get("edges", {}).keys())
@@ -648,7 +649,7 @@ def agent_graph(
                 nodes={},
                 context=context,
                 enabled=False,
-                tracker=tracker,
+                create_tracker=graph_tracker_factory,
             )
 
         try:
@@ -679,7 +680,7 @@ def agent_graph(
                 nodes={},
                 context=context,
                 enabled=False,
-                tracker=tracker,
+                create_tracker=graph_tracker_factory,
             )
 
         nodes = AgentGraphDefinition.build_nodes(
@@ -692,7 +693,7 @@ def agent_graph(
             nodes=nodes,
             context=context,
             enabled=agent_graph_config.enabled,
-            tracker=tracker,
+            create_tracker=graph_tracker_factory,
         )
 
     async def create_agent_graph(