feat!: Add per-execution runId, at-most-once tracking, and cross-process tracker resumption (#133)

Author: jsonbailey

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

@@ -260,8 +260,7 @@ def route(state: WorkflowState) -> str:
 
         self._graph.traverse(fn=handle_traversal)
 
-        tracker = self._graph.get_tracker()
-        graph_key_str = tracker.graph_key if tracker else 'unknown'
+        graph_key_str = self._graph._agent_graph.key or 'unknown'
         log.debug(
             f"LangGraphAgentGraphRunner: graph='{graph_key_str}', root='{root_key}', "
             f"structure: {' | '.join(graph_structure)}"
@@ -281,7 +280,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() if self._graph.create_tracker is not None else None
         start_ns = time.perf_counter_ns()
 
         try:

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

@@ -196,13 +196,17 @@ def flush(self, graph: AgentGraphDefinition) -> None:
 
         :param graph: The AgentGraphDefinition whose nodes hold the LD config trackers.
         """
+        node_trackers: Dict[str, Any] = {}
         for node_key in self._path:
+            if node_key in node_trackers:
+                continue
             node = graph.get_node(node_key)
             if not node:
                 continue
-            config_tracker = node.get_config().tracker
+            config_tracker = node.get_config().create_tracker()
             if not config_tracker:
                 continue
+            node_trackers[node_key] = config_tracker
 
             usage = self._node_tokens.get(node_key)
             if usage:

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

@@ -530,13 +530,13 @@ def sync_tool(x: str = '') -> str:
         cfg = AIAgentConfig(
             key='n',
             enabled=True,
+            create_tracker=MagicMock(),
             model=ModelConfig(
                 name='gpt-4',
                 parameters={'tools': [{'name': 'my_tool', 'type': 'function', 'parameters': {}}]},
             ),
             provider=ProviderConfig(name='openai'),
             instructions='',
-            tracker=MagicMock(),
         )
         tools = build_structured_tools(cfg, {'my_tool': sync_tool})
         assert len(tools) == 1
@@ -553,13 +553,13 @@ async def async_tool(x: str = '') -> str:
         cfg = AIAgentConfig(
             key='n',
             enabled=True,
+            create_tracker=MagicMock(),
             model=ModelConfig(
                 name='gpt-4',
                 parameters={'tools': [{'name': 'my_tool', 'type': 'function', 'parameters': {}}]},
             ),
             provider=ProviderConfig(name='openai'),
             instructions='',
-            tracker=MagicMock(),
         )
         tools = build_structured_tools(cfg, {'my_tool': async_tool})
         assert len(tools) == 1

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

@@ -11,13 +11,15 @@
 
 
 def _make_graph(enabled: bool = True) -> AgentGraphDefinition:
+    graph_tracker = MagicMock()
+    node_tracker = MagicMock()
     root_config = AIAgentConfig(
         key='root-agent',
         enabled=enabled,
+        create_tracker=MagicMock(return_value=node_tracker),
         model=ModelConfig(name='gpt-4'),
         provider=ProviderConfig(name='openai'),
         instructions='You are a helpful assistant.',
-        tracker=MagicMock(),
     )
     graph_config = AIAgentGraphConfig(
         key='test-graph',
@@ -31,7 +33,7 @@ def _make_graph(enabled: bool = True) -> AgentGraphDefinition:
         nodes=nodes,
         context=MagicMock(),
         enabled=enabled,
-        tracker=MagicMock(),
+        create_tracker=lambda: graph_tracker,
     )
 
 
@@ -78,7 +80,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}):
@@ -92,7 +94,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

@@ -35,6 +35,7 @@ def _make_graph(mock_ld_client: MagicMock, node_key: str = 'root-agent', graph_k
         model_name='gpt-4',
         provider_name='openai',
         context=context,
+        run_id='test-run-id',
         graph_key=graph_key,
     )
     graph_tracker = AIGraphTracker(
@@ -50,7 +51,7 @@ def _make_graph(mock_ld_client: MagicMock, node_key: str = 'root-agent', graph_k
         model=ModelConfig(name='gpt-4', parameters={}),
         provider=ProviderConfig(name='openai'),
         instructions='Be helpful.',
-        tracker=node_tracker,
+        create_tracker=lambda: node_tracker,
     )
     graph_config = AIAgentGraphConfig(
         key=graph_key,
@@ -64,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,
     )
 
 
@@ -320,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()
@@ -339,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()
@@ -355,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()
@@ -377,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()
@@ -402,14 +403,15 @@ def test_flush_with_no_graph_key_on_node_tracker():
         model_name='gpt-4',
         provider_name='openai',
         context=context,
+        run_id='test-run-id',
     )
     node_config = AIAgentConfig(
         key='root-agent',
         enabled=True,
         model=ModelConfig(name='gpt-4', parameters={}),
         provider=ProviderConfig(name='openai'),
         instructions='Be helpful.',
-        tracker=node_tracker,
+        create_tracker=lambda: node_tracker,
     )
     graph_config = AIAgentGraphConfig(
         key='test-graph',
@@ -423,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'}, {})
@@ -441,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'}, {})
@@ -460,10 +462,10 @@ def test_flush_skips_node_without_tracker():
     node_config_no_tracker = AIAgentConfig(
         key='no-track',
         enabled=True,
+        create_tracker=lambda: None,
         model=ModelConfig(name='gpt-4', parameters={}),
         provider=ProviderConfig(name='openai'),
         instructions='',
-        tracker=None,
     )
     graph_config = AIAgentGraphConfig(
         key='g', root_config_key='no-track', edges=[], enabled=True
@@ -474,7 +476,7 @@ def test_flush_skips_node_without_tracker():
         nodes=nodes,
         context=context,
         enabled=True,
-        tracker=None,
+        create_tracker=lambda: None,
     )
 
     handler = LDMetricsCallbackHandler({'no-track'}, {})