fix(langgraph): restore created_at + docstring-only deprecation for tracing handler (PR 5/6)

AGX1-378: wire workflow_now_if_in_workflow() into stream_langgraph_events so
Temporal callers get deterministic message timestamps, matching the pattern
used by the openai/litellm providers.

Deprecation alignment: remove runtime warnings.warn from
create_langgraph_tracing_handler (and unused import warnings) to match PR 4/6
pydantic-ai convention. Deprecation remains in docstrings on module, class,
and function. Callers under -W error are no longer broken.

Test alignment after rebase onto unified-harness-surface (b4b8b33):
- FakeStreamingModule.streaming_task_message_context in test_langgraph_async.py
  and test_pydantic_ai_async.py updated to accept **kw (foundation now passes
  created_at).
- Three "no tool spans for Full events" tests updated to assert the new
  SpanDeriver behaviour: Full(ToolRequestContent) opens a span,
  Full(ToolResponseContent) closes it.
- Two "accumulates all text" multi-step tests corrected to last-segment
  semantics (auto_send resets final_text_parts on each new Start(TextContent)).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: declan-scale

src/agentex/lib/adk/_modules/_langgraph_async.py

@@ -16,6 +16,8 @@
 handles Full events correctly; no coalescing wrapper is needed.
 """
 
+from agentex.lib.utils.temporal import workflow_now_if_in_workflow
+
 
 async def stream_langgraph_events(stream, task_id: str) -> str:
     """Stream LangGraph events to Agentex via Redis.
@@ -37,6 +39,11 @@ async def stream_langgraph_events(stream, task_id: str) -> str:
     NOT Start+Delta+Done like pydantic-ai. ``auto_send`` handles Full events
     correctly; no coalescing wrapper is needed.
 
+    AGX1-378 note: ``created_at`` is set from ``workflow.now()`` when called inside a
+    Temporal workflow, matching the pattern used by the openai/litellm providers.
+    Outside a workflow (plain async activities, sync agents) it is ``None`` and the
+    server's wall clock is used.
+
     Args:
         stream: Async iterator from graph.astream(..., stream_mode=["messages", "updates"])
         task_id: The Agentex task ID to stream messages to.
@@ -50,7 +57,9 @@ async def stream_langgraph_events(stream, task_id: str) -> str:
     # AGX1-377 note: LangGraph emits tool requests as Full events (from "updates"),
     # NOT Start+Delta+Done like pydantic-ai. auto_send handles Full events correctly;
     # no coalescing wrapper is needed.
+    # AGX1-378: stamp messages with workflow.now() inside Temporal for deterministic
+    # created_at ordering; falls back to None (server wall clock) outside a workflow.
     turn = LangGraphTurn(stream, model=None)
     emitter = UnifiedEmitter(task_id=task_id, trace_id=None, parent_span_id=None)
-    result = await emitter.auto_send_turn(turn)
+    result = await emitter.auto_send_turn(turn, created_at=workflow_now_if_in_workflow())
     return result.final_text

src/agentex/lib/adk/_modules/_langgraph_tracing.py

@@ -14,7 +14,6 @@
 
 from __future__ import annotations
 
-import warnings
 from uuid import UUID
 from typing import Any, override
 
@@ -268,13 +267,6 @@ def create_langgraph_tracing_handler(
 
         This function remains available for backward compatibility.
     """
-    warnings.warn(
-        "create_langgraph_tracing_handler is deprecated. Use LangGraphTurn with "
-        "UnifiedEmitter instead — the unified harness derives equivalent spans from "
-        "the canonical event stream without a LangChain callback handler.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
     return AgentexLangGraphTracingHandler(
         trace_id=trace_id,
         parent_span_id=parent_span_id,

tests/lib/adk/test_langgraph_async.py

@@ -79,7 +79,7 @@ class FakeStreamingModule:
     def __init__(self) -> None:
         self.contexts: list[FakeContext] = []
 
-    def streaming_task_message_context(self, *, task_id: str, initial_content: Any) -> FakeContext:
+    def streaming_task_message_context(self, *, task_id: str, initial_content: Any, **kw: Any) -> FakeContext:
         tm = TaskMessage(
             id=f"m{len(self.contexts) + 1}",
             task_id=task_id,
@@ -226,14 +226,15 @@ async def test_tool_response_posted_via_streaming_context(
         assert content.content == "Sunny, 72F"
         assert streaming.contexts[0].closed is True
 
-    async def test_multi_step_text_then_tool_then_text_accumulates_all_text(
+    async def test_multi_step_text_then_tool_then_text_last_segment(
         self, fake_adk: tuple[FakeStreamingModule, FakeMessagesModule]
     ) -> None:
-        """Unified surface: final_text accumulates all text across the turn.
+        """Unified surface: final_text uses last-segment semantics.
 
-        Old bespoke impl only returned the last text segment (reset final_text
-        each time a new text context opened). The unified surface accumulates
-        all text because auto_send appends every TextDelta.
+        auto_send resets final_text_parts when a new Start(TextContent) is seen,
+        so multi-step turns (text -> tool -> text) return only the LAST text segment.
+        Both text contexts are still opened and streamed to Redis; only the
+        return value is last-segment. This matches stream_pydantic_ai_events.
         """
         from langchain_core.messages import AIMessage, ToolMessage, AIMessageChunk
 
@@ -256,10 +257,9 @@ async def test_multi_step_text_then_tool_then_text_accumulates_all_text(
 
         final = await stream_langgraph_events(stream, TASK_ID)
 
-        # Unified surface accumulates all text (not just the last segment)
-        assert "Looking up..." in final
-        assert "Found it!" in final
-        # Two text streaming contexts (one per text segment)
+        # Last segment only — first text segment is NOT in final_text
+        assert final == "Found it!"
+        # Two text streaming contexts (one per text segment) — both streamed to Redis
         text_ctxs = [c for c in streaming.contexts if isinstance(c.initial_content, TextContent)]
         assert len(text_ctxs) == 2
         assert all(ctx.closed for ctx in text_ctxs)

tests/lib/adk/test_langgraph_sync.py

@@ -3,7 +3,8 @@
 Covers:
 - Basic text, tool call, and tool response emission
 - on_final_ai_message callback for usage capture
-- Deprecation warning emitted by create_langgraph_tracing_handler
+- create_langgraph_tracing_handler symbol is importable and functional
+  (runtime DeprecationWarning removed; deprecation is docstring-only)
 
 NOTE: langchain_core imports must be deferred to test-function scope because
 conftest.py stubs out ``langchain_core.messages`` with MagicMock for ADK
@@ -13,7 +14,6 @@
 from __future__ import annotations
 
 import sys
-import warnings
 from typing import Any, AsyncIterator
 
 import pytest
@@ -197,13 +197,21 @@ def _cb(msg):
         assert yield_order.index("event") < yield_order.index("callback")
 
 
-class TestDeprecationWarning:
-    def test_create_langgraph_tracing_handler_emits_deprecation_warning(self):
+class TestLangGraphTracingHandlerBackwardCompat:
+    def test_create_langgraph_tracing_handler_no_runtime_warning(self):
+        """Deprecated symbol remains importable and emits no runtime DeprecationWarning.
+
+        The runtime warnings.warn was removed (docstring-only deprecation) to
+        align with PR 4/6 and avoid breaking callers under warnings-as-errors.
+        Using ``warnings.simplefilter("error", DeprecationWarning)`` verifies
+        that calling the function is safe under -W error conditions.
+        """
+        import warnings
+
         from agentex.lib.adk._modules._langgraph_tracing import create_langgraph_tracing_handler
 
         with warnings.catch_warnings(record=True) as w:
-            warnings.simplefilter("always")
-            create_langgraph_tracing_handler(trace_id="t1")
-        assert any(issubclass(warning.category, DeprecationWarning) for warning in w), (
-            "create_langgraph_tracing_handler must emit a DeprecationWarning"
-        )
+            warnings.simplefilter("error", DeprecationWarning)
+            create_langgraph_tracing_handler(trace_id="t1", parent_span_id="p1")
+
+        assert w == [], "create_langgraph_tracing_handler must NOT emit a runtime DeprecationWarning"

tests/lib/adk/test_langgraph_sync_unified.py

@@ -149,16 +149,13 @@ def fake_tracer(self):
         )
         return tracer, backend
 
-    async def test_tool_span_not_derived_from_full_events(self, fake_tracer):
-        """AGX1-377: LangGraph emits tool calls as Full events (not Start+Done).
-        The SpanDeriver opens tool spans from Start(ToolRequestContent)+Done
-        sequences. Since LangGraph uses Full, no tool span is opened by the
-        SpanDeriver -- this is the documented AGX1-377 gap resolved by the
-        unified surface (Full events are emitted identically; cross-channel
-        span equivalence arrives with AGX1-373).
-
-        The tracer must still be invoked (SpanDeriver.observe is called for each
-        event); it just produces no open-span signals for LangGraph Full tool events.
+    async def test_tool_span_derived_from_full_events(self, fake_tracer):
+        """AGX1-377: SpanDeriver now handles Full tool events for LangGraph.
+
+        Full(ToolRequestContent) opens a tool span keyed by tool_call_id;
+        Full(ToolResponseContent) closes it. This bridges the previous gap where
+        LangGraph's Full-event path produced no spans, aligning it with
+        Start+Done harnesses (pydantic-ai, openai-agents).
         """
         from langchain_core.messages import AIMessage, ToolMessage
 
@@ -175,13 +172,10 @@ async def test_tool_span_not_derived_from_full_events(self, fake_tracer):
         emitter = UnifiedEmitter(task_id="t", trace_id="trace1", parent_span_id=None, tracer=tracer)
         _ = [e async for e in emitter.yield_turn(LangGraphTurn(_make_stream(events_raw)))]
 
-        # AGX1-377: Full events don't produce tool spans via SpanDeriver today.
-        # This is the documented gap; full cross-channel equivalence arrives with AGX1-373.
-        assert backend.spans_started == [], (
-            "Expected no tool spans for LangGraph Full events (AGX1-377); if this "
-            "assertion fails it means SpanDeriver now handles Full events — update "
-            "the test to assert the new span names."
-        )
+        assert len(backend.spans_started) == 1, "Full(ToolRequestContent) opens one tool span"
+        started = backend.spans_started[0]
+        assert started["name"] == "get_weather"
+        assert started["input"] == {"city": "Paris"}
 
     async def test_no_spans_when_no_tool_calls(self, fake_tracer):
         """yield_turn with tracer but no tool calls emits no spans."""

tests/lib/adk/test_pydantic_ai_async.py

@@ -82,7 +82,7 @@ class FakeStreamingModule:
     def __init__(self) -> None:
         self.contexts: list[FakeContext] = []
 
-    def streaming_task_message_context(self, *, task_id: str, initial_content: Any) -> FakeContext:
+    def streaming_task_message_context(self, *, task_id: str, initial_content: Any, **kw: Any) -> FakeContext:
         tm = TaskMessage(
             id=f"m{len(self.contexts) + 1}",
             task_id=task_id,

tests/lib/core/harness/test_harness_langgraph_async.py

@@ -213,8 +213,14 @@ async def test_tool_response_posted_via_streaming_context(self):
         assert tool_resp_ctxs[0].initial_content.content == "Sunny, 72F"
         assert tool_resp_ctxs[0].closed is True
 
-    async def test_multi_step_accumulates_all_text(self):
-        """Unified surface: final_text accumulates all text, not just last segment."""
+    async def test_multi_step_final_text_is_last_segment(self):
+        """Unified surface: final_text uses last-segment semantics.
+
+        auto_send resets final_text_parts when a new Start(TextContent) is seen,
+        so multi-step turns (text -> tool -> text) return only the LAST text segment.
+        This matches the behaviour documented in auto_send.py and mirrors
+        stream_pydantic_ai_events.
+        """
         from langchain_core.messages import AIMessage, ToolMessage, AIMessageChunk
 
         chunk1 = AIMessageChunk(content="Searching...")
@@ -232,11 +238,10 @@ async def test_multi_step_accumulates_all_text(self):
         ]
         result, fake_streaming, _ = await _run_auto_send_turn(events)
 
-        # All text accumulated
-        assert "Searching..." in result.final_text
-        assert "Found it!" in result.final_text
+        # Last segment only — first text segment is NOT in final_text
+        assert result.final_text == "Found it!"
 
-        # Two text streaming contexts
+        # Two text streaming contexts still opened (both streamed to Redis)
         text_ctxs = [c for c in fake_streaming.contexts if isinstance(c.initial_content, TextContent)]
         assert len(text_ctxs) == 2
 
@@ -269,8 +274,12 @@ async def test_turn_usage_populated_after_events_consumed(self):
         assert usage.output_tokens == 5
         assert usage.total_tokens == 15
 
-    async def test_tracer_does_not_produce_tool_spans_for_full_events(self):
-        """AGX1-377: Full events don't trigger SpanDeriver tool spans."""
+    async def test_tracer_produces_tool_spans_for_full_events(self):
+        """AGX1-377: SpanDeriver now handles Full tool events (request opens, response closes).
+
+        Full(ToolRequestContent) opens a tool span; Full(ToolResponseContent) closes it.
+        This aligns LangGraph tracing with Start+Done harnesses (pydantic-ai, openai-agents).
+        """
         from langchain_core.messages import AIMessage, ToolMessage
 
         tc = {"id": "c1", "name": "t", "args": {}}
@@ -284,4 +293,6 @@ async def test_tracer_does_not_produce_tool_spans_for_full_events(self):
         _, _, fake_tracing = await _run_auto_send_turn(events, trace_id="trace-1")
 
         assert fake_tracing is not None
-        assert fake_tracing.started == [], "AGX1-377: Full events don't trigger tool spans"
+        assert len(fake_tracing.started) == 1, "Full(ToolRequestContent) opens one tool span"
+        assert fake_tracing.started[0][0] == "t", "span name matches the tool name"
+        assert len(fake_tracing.ended) == 1, "Full(ToolResponseContent) closes the span"

tests/lib/core/harness/test_harness_langgraph_sync.py

@@ -189,9 +189,12 @@ async def test_empty_stream_yields_nothing(self):
         out, _ = await _run_yield_turn([])
         assert out == []
 
-    async def test_tracer_invoked_but_no_tool_spans_for_full_events(self):
-        """AGX1-377: tool spans are NOT derived from Full events (SpanDeriver uses Start+Done).
-        This is the documented gap; full cross-channel equivalence arrives with AGX1-373."""
+    async def test_tracer_produces_tool_spans_for_full_events(self):
+        """AGX1-377: SpanDeriver now handles Full tool events (request opens, response closes).
+
+        Full(ToolRequestContent) opens a tool span; Full(ToolResponseContent) closes it.
+        This aligns LangGraph tracing with Start+Done harnesses (pydantic-ai, openai-agents).
+        """
         from langchain_core.messages import AIMessage, ToolMessage
 
         tc = {"id": "c1", "name": "t", "args": {}}
@@ -205,8 +208,9 @@ async def test_tracer_invoked_but_no_tool_spans_for_full_events(self):
         _, fake_tracing = await _run_yield_turn(events, trace_id="trace-1")
 
         assert fake_tracing is not None
-        # No tool spans opened — Full events don't trigger OpenSpan in SpanDeriver
-        assert fake_tracing.started == [], "Expected no tool spans for LangGraph Full events (AGX1-377)"
+        assert len(fake_tracing.started) == 1, "Full(ToolRequestContent) opens one tool span"
+        assert fake_tracing.started[0][0] == "t", "span name matches the tool name"
+        assert len(fake_tracing.ended) == 1, "Full(ToolResponseContent) closes the span"
 
     async def test_usage_captured_after_yield(self):
         from langchain_core.messages import AIMessage