struct-sdk 0.2.5__tar.gz → 0.2.8__tar.gz

{struct_sdk-0.2.5 → struct_sdk-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.2.5
+Version: 0.2.8
 Summary: Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry
 Project-URL: Homepage, https://struct.ai
 Project-URL: Documentation, https://struct.ai/docs
@@ -87,16 +87,18 @@ struct.init(
 import anthropic
 client = anthropic.AsyncAnthropic()
 
+# Decorate each tool — auto-captures arguments + result + tool_call_id.
+@struct.tool()
+async def search(query: str):
+    ...
+
 async with struct.agent(name="checkout"):
     msg = await client.messages.create(
         model="claude-3-5-sonnet-20241022",
         max_tokens=1024,
         messages=[{"role": "user", "content": "plan my checkout flow"}],
     )
-
-    # tool_call_id is auto-filled from the preceding Anthropic response
-    async with struct.tool(name="search"):
-        result = await search(msg)
+    result = await search(query="...")
 ```
 
 ## What gets traced
@@ -207,6 +209,14 @@ struct.init(ingest_key="pk-...", service_name="checkout-agent")
 import anthropic
 client = anthropic.AsyncAnthropic()
 
+# Recommended: define each tool as a function and DECORATE it. The decorator
+# auto-captures the tool's arguments + result on the execute_tool span and
+# auto-fills tool_call_id from the preceding Anthropic response — no manual
+# bookkeeping.
+@struct.tool()
+async def search(query: str):
+    ...
+
 # Required: wrap the agent loop yourself.
 async with struct.agent(name="checkout"):
     msg = await client.messages.create(
@@ -214,16 +224,60 @@ async with struct.agent(name="checkout"):
         max_tokens=1024,
         messages=[...],
     )
+    # Dispatching a decorated tool inside the agent emits a fully-populated
+    # execute_tool span (name, id, arguments, result):
+    result = await search(query="...")
+```
 
-    # Required: wrap each tool execution.
-    # tool_call_id is auto-filled from the preceding Anthropic response.
-    async with struct.tool(name="search"):
-        result = await search(...)
+For **dynamic dispatch** (the LLM picks a tool from a registry at runtime),
+apply the decorator at runtime — still automatic, just bind the name when you
+wrap the callable:
+
+```python
+registry = {t.name: struct.tool(name=t.name)(t.execute) for t in tools}
+result = await registry[block.name](**block.input)   # arguments + result captured
 ```
 
+> `struct.tool()` can also be used as a context manager
+> (`async with struct.tool(name=...): ...`) to instrument an arbitrary block of
+> code as a tool span. That form is a **manual escape hatch** — it does NOT
+> auto-capture arguments/result (a `with` block can't see the body's return
+> value), so prefer the decorator for actual tool calls. See
+> [Parallel tool calls](#parallel-tool-calls--pass-tool_call_id-explicitly) for
+> the one runtime value (`tool_call_id`) you must supply under concurrency.
+
 `anthropic.Anthropic`, `anthropic.AsyncAnthropic`, and the bedrock/vertex
 clients are all auto-instrumented for chat spans.
 
+#### Parallel tool calls — pass `tool_call_id` explicitly
+
+When you execute an assistant turn's tool calls **sequentially** — one
+`await` at a time, in the order the `tool_use` blocks appear — `struct.tool()`
+auto-fills `gen_ai.tool.call.id` by matching each span to the next pending
+`tool_use` of the same tool name. Nothing extra to do.
+
+When you execute them **concurrently** (e.g. `asyncio.gather`), that
+name-and-order matching is ambiguous: two `struct.tool(name="search")` spans
+can start in any order, so the auto-fill may attach the wrong id (and thus the
+wrong arguments/result) to a call. In that case **pass `tool_call_id`
+explicitly** from the originating `tool_use` block — an explicit id always
+overrides the auto-linkage:
+
+```python
+async def run_one(block):
+    # The id from THIS block overrides the name/order auto-fill.
+    async with struct.tool(name=block.name, tool_call_id=block.id):
+        return await dispatch(block.name, **block.input)
+
+# Concurrent execution — each tool span still carries the correct id.
+results = await asyncio.gather(*[run_one(b) for b in tool_use_blocks])
+```
+
+Rule of thumb: **serial tool execution → automatic; concurrent tool execution
+→ provide `tool_call_id=` yourself.** (Auto-instrumented frameworks such as
+LangChain read the id from the framework's `ToolCall`, so this only applies
+when you drive the tool loop directly against an LLM SDK.)
+
 #### LangChain `BaseChatModel` (no agent/graph)
 
 If you call `ChatAnthropic.invoke(...)` (or any other `BaseChatModel`)

{struct_sdk-0.2.5 → struct_sdk-0.2.8}/README.md

@@ -41,16 +41,18 @@ struct.init(
 import anthropic
 client = anthropic.AsyncAnthropic()
 
+# Decorate each tool — auto-captures arguments + result + tool_call_id.
+@struct.tool()
+async def search(query: str):
+    ...
+
 async with struct.agent(name="checkout"):
     msg = await client.messages.create(
         model="claude-3-5-sonnet-20241022",
         max_tokens=1024,
         messages=[{"role": "user", "content": "plan my checkout flow"}],
     )
-
-    # tool_call_id is auto-filled from the preceding Anthropic response
-    async with struct.tool(name="search"):
-        result = await search(msg)
+    result = await search(query="...")
 ```
 
 ## What gets traced
@@ -161,6 +163,14 @@ struct.init(ingest_key="pk-...", service_name="checkout-agent")
 import anthropic
 client = anthropic.AsyncAnthropic()
 
+# Recommended: define each tool as a function and DECORATE it. The decorator
+# auto-captures the tool's arguments + result on the execute_tool span and
+# auto-fills tool_call_id from the preceding Anthropic response — no manual
+# bookkeeping.
+@struct.tool()
+async def search(query: str):
+    ...
+
 # Required: wrap the agent loop yourself.
 async with struct.agent(name="checkout"):
     msg = await client.messages.create(
@@ -168,16 +178,60 @@ async with struct.agent(name="checkout"):
         max_tokens=1024,
         messages=[...],
     )
+    # Dispatching a decorated tool inside the agent emits a fully-populated
+    # execute_tool span (name, id, arguments, result):
+    result = await search(query="...")
+```
 
-    # Required: wrap each tool execution.
-    # tool_call_id is auto-filled from the preceding Anthropic response.
-    async with struct.tool(name="search"):
-        result = await search(...)
+For **dynamic dispatch** (the LLM picks a tool from a registry at runtime),
+apply the decorator at runtime — still automatic, just bind the name when you
+wrap the callable:
+
+```python
+registry = {t.name: struct.tool(name=t.name)(t.execute) for t in tools}
+result = await registry[block.name](**block.input)   # arguments + result captured
 ```
 
+> `struct.tool()` can also be used as a context manager
+> (`async with struct.tool(name=...): ...`) to instrument an arbitrary block of
+> code as a tool span. That form is a **manual escape hatch** — it does NOT
+> auto-capture arguments/result (a `with` block can't see the body's return
+> value), so prefer the decorator for actual tool calls. See
+> [Parallel tool calls](#parallel-tool-calls--pass-tool_call_id-explicitly) for
+> the one runtime value (`tool_call_id`) you must supply under concurrency.
+
 `anthropic.Anthropic`, `anthropic.AsyncAnthropic`, and the bedrock/vertex
 clients are all auto-instrumented for chat spans.
 
+#### Parallel tool calls — pass `tool_call_id` explicitly
+
+When you execute an assistant turn's tool calls **sequentially** — one
+`await` at a time, in the order the `tool_use` blocks appear — `struct.tool()`
+auto-fills `gen_ai.tool.call.id` by matching each span to the next pending
+`tool_use` of the same tool name. Nothing extra to do.
+
+When you execute them **concurrently** (e.g. `asyncio.gather`), that
+name-and-order matching is ambiguous: two `struct.tool(name="search")` spans
+can start in any order, so the auto-fill may attach the wrong id (and thus the
+wrong arguments/result) to a call. In that case **pass `tool_call_id`
+explicitly** from the originating `tool_use` block — an explicit id always
+overrides the auto-linkage:
+
+```python
+async def run_one(block):
+    # The id from THIS block overrides the name/order auto-fill.
+    async with struct.tool(name=block.name, tool_call_id=block.id):
+        return await dispatch(block.name, **block.input)
+
+# Concurrent execution — each tool span still carries the correct id.
+results = await asyncio.gather(*[run_one(b) for b in tool_use_blocks])
+```
+
+Rule of thumb: **serial tool execution → automatic; concurrent tool execution
+→ provide `tool_call_id=` yourself.** (Auto-instrumented frameworks such as
+LangChain read the id from the framework's `ToolCall`, so this only applies
+when you drive the tool loop directly against an LLM SDK.)
+
 #### LangChain `BaseChatModel` (no agent/graph)
 
 If you call `ChatAnthropic.invoke(...)` (or any other `BaseChatModel`)

{struct_sdk-0.2.5 → struct_sdk-0.2.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.2.5"
+version = "0.2.8"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -72,6 +72,11 @@ override-dependencies = [
     "starlette>=1.3.1",
 ]
 
+[tool.pytest.ini_options]
+markers = [
+    "integration: real-model integration tests (requires ANTHROPIC_API_KEY / OPENAI_API_KEY; skipped in default CI)",
+]
+
 [tool.mypy]
 [[tool.mypy.overrides]]
 module = ["anthropic", "anthropic.*", "claude_agent_sdk", "claude_agent_sdk.*", "langchain_core", "langchain_core.*", "langchain", "langchain.*", "langgraph", "langgraph.*"]

{struct_sdk-0.2.5 → struct_sdk-0.2.8}/src/struct_sdk/anthropic.py

@@ -119,44 +119,23 @@ def _create_common(
 
     Two paths:
 
-    1. **Enrich** — when ``_current_langchain_chat_span`` is set, this call
-       is happening underneath a LangChain handler that's already created
-       a ``chat <model>`` span. We do NOT create our own span (that's the
-       duplicate-Anthropic-spans issue). Instead we attach HTTP-layer
-       attrs (the real provider msg_id, exact response_model, usage,
-       finish_reasons, error info on failure) onto the langchain span.
-       Pre-call attrs are skipped — LangChain already set them.
-
-    2. **Standalone** — no LangChain in the picture. Create our own span
-       and set the full attribute set as before.
+    1. **Suppressed** — when ``is_genai_suppressed()`` is True, a framework
+       layer (e.g. the LangChain callback handler) already owns a ``chat
+       <model>`` span for this call. We run the original call to completion
+       and emit NO span — avoiding the duplicate-Anthropic-spans problem.
+
+    2. **Standalone** — no framework suppression in the picture. Create our
+       own span and set the full attribute set as before.
     """
-    from struct_sdk.core import _safe, _current_langchain_chat_span
+    from struct_sdk.core import _safe, is_genai_suppressed
 
     model = kwargs.get("model", "unknown")
 
-    # Enrich path: a LangChain handler upstream already created a ``chat
-    # <model>`` span for this call. Attach Anthropic HTTP-layer detail to it
-    # without creating a duplicate span.
-    host_span = _current_langchain_chat_span.get(None)
-    if host_span is not None:
-        try:
-            result = yield f, args, kwargs
-        except Exception as e:
-            # Capture the type name OUTSIDE the lambda — ``except X as e``
-            # binds ``e`` only for the duration of the except block, but
-            # ``_safe`` is opaque to static analysis (ruff flags F841 +
-            # F821 thinking the lambda outlives the binding). Snapshotting
-            # to a local makes the closure capture trivially correct.
-            err_type = type(e).__name__
-            _safe(
-                lambda: host_span.set_attribute("error.type", err_type),
-                site="anthropic.create.enrich.error_type",
-            )
-            raise
-        _safe(
-            lambda: _set_response_attrs(host_span, sdk, model, result, otel_logger),
-            site="anthropic.create.enrich.set_response_attrs",
-        )
+    # Suppression path: a framework layer (LangChain handler) already owns the
+    # ``chat <model>`` span for this call. Run the original call to completion
+    # and emit NO span — the framework's span covers this invocation.
+    if is_genai_suppressed():
+        result = yield f, args, kwargs
         return result  # noqa: B901
 
     with tracer.start_as_current_span(
@@ -326,14 +305,12 @@ def _wrap_stream(original: Any, tracer: trace.Tracer, sdk: StructSDK, otel_logge
     if is_async:
         @functools.wraps(original)
         async def wrapper(*args: Any, **kwargs: Any) -> Any:
-            from struct_sdk.core import _safe, _current_session_id, _current_langchain_chat_span
+            from struct_sdk.core import _safe, _current_session_id, is_genai_suppressed
             model = kwargs.get("model", "unknown")
 
-            # Enrich path: a LangChain handler upstream already owns a chat
-            # span for this call. Don't create a duplicate; just pass through.
-            # (Stream end-handling will set response attrs on the host span
-            # when the LangChain handler's on_llm_end fires.)
-            if _current_langchain_chat_span.get(None) is not None:
+            # Suppression path: a framework layer (LangChain handler) already
+            # owns the chat span. Don't create a duplicate; pass through.
+            if is_genai_suppressed():
                 return await original(*args, **kwargs) if _is_coroutine(original) else original(*args, **kwargs)
 
             span: Optional[trace.Span] = None
@@ -378,12 +355,12 @@ def _wrap_stream(original: Any, tracer: trace.Tracer, sdk: StructSDK, otel_logge
     else:
         @functools.wraps(original)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
-            from struct_sdk.core import _safe, _current_session_id, _current_langchain_chat_span
+            from struct_sdk.core import _safe, _current_session_id, is_genai_suppressed
             model = kwargs.get("model", "unknown")
 
-            # Enrich path: a LangChain handler upstream already owns a chat
-            # span for this call. Don't create a duplicate; just pass through.
-            if _current_langchain_chat_span.get(None) is not None:
+            # Suppression path: a framework layer (LangChain handler) already
+            # owns the chat span. Don't create a duplicate; pass through.
+            if is_genai_suppressed():
                 return original(*args, **kwargs)
 
             span: Optional[trace.Span] = None
@@ -552,7 +529,7 @@ def _emit_message_events(
       etc.) — human-readable signal.
     - ``attributes['body']`` (log record attribute): the JSON-serialised
       structured payload ``{"role": ..., "parts": [...]}``.
-    - Other attributes: ``event.name``, ``gen_ai.system``,
+    - Other attributes: ``event.name``, ``gen_ai.provider.name``,
       ``gen_ai.message.index``, ``gen_ai.conversation.id``.
 
     ``span`` — if provided, its span context is used for the LogRecord's
@@ -585,7 +562,7 @@ def _emit_message_events(
             attrs: dict[str, Any] = {
                 "event.name": event_name,
                 "body": payload,
-                "gen_ai.system": "anthropic",
+                "gen_ai.provider.name": "anthropic",
                 "gen_ai.message.index": msg_index,
             }
             if session_id:
@@ -618,7 +595,7 @@ def _emit_message_events(
             attrs = {
                 "event.name": event_name,
                 "body": payload,
-                "gen_ai.system": "anthropic",
+                "gen_ai.provider.name": "anthropic",
                 "gen_ai.message.index": msg_index,
             }
             if session_id:
@@ -696,7 +673,7 @@ def _emit_choice_event(
         attrs: dict[str, Any] = {
             "event.name": event_name,
             "body": payload,
-            "gen_ai.system": "anthropic",
+            "gen_ai.provider.name": "anthropic",
         }
         if session_id:
             attrs["gen_ai.conversation.id"] = session_id

{struct_sdk-0.2.5 → struct_sdk-0.2.8}/src/struct_sdk/core.py

@@ -9,6 +9,7 @@ OTel GenAI Semantic Conventions v1.37+ compliant.
 import asyncio
 import atexit
 import contextvars
+from contextvars import Token
 import functools
 import json
 import logging
@@ -16,8 +17,12 @@ import threading
 import uuid
 from enum import Enum
 from typing import Any, Callable, Optional
+from importlib.metadata import version as _pkg_version
 
+from opentelemetry import context as _otel_context
 from opentelemetry import trace
+from opentelemetry.context import create_key
+from opentelemetry.context.context import Context as _OtelContext
 from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 from opentelemetry.sdk._logs import LoggerProvider
@@ -29,6 +34,11 @@ from opentelemetry.trace import StatusCode
 
 logger = logging.getLogger("struct_sdk")
 
+try:
+    _SDK_VERSION = _pkg_version("struct-sdk")
+except Exception:  # noqa: BLE001
+    _SDK_VERSION = "0.0.0+local"
+
 DEFAULT_ENDPOINT = "https://ingest.struct.ai"
 
 
@@ -46,27 +56,11 @@ class ContentCaptureMode(str, Enum):
 _current_session_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("_current_session_id", default=None)
 _current_conversation_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("_current_conversation_id", default=None)
 _current_agent_span: contextvars.ContextVar[Optional[trace.Span]] = contextvars.ContextVar("_current_agent_span", default=None)
-
-# When the LangChain handler is creating a ``chat <model>`` span for an LLM
-# call that LangChain will dispatch through a provider SDK (anthropic,
-# openai, etc.) that we ALSO instrument, set this contextvar to the
-# in-progress langchain chat span. Provider-SDK instrumentations check it
-# at the top of their ``messages.create`` / equivalent wrapper:
-#
-#   - If set: enrich the existing langchain span with HTTP-layer attributes
-#     (real provider response.id, exact retries, rate-limit headers, etc.)
-#     and SKIP creating their own span — there's already a span for this
-#     call, we just want to attach more data to it.
-#
-#   - If not set: this is a standalone provider-SDK invocation (no LangChain
-#     in the picture); the provider instrumentation creates its own span as
-#     usual.
-#
-# This eliminates the duplicate-span / orphan-Anthropic-span problem while
-# preserving both layers' data on a single span.
-_current_langchain_chat_span: contextvars.ContextVar[Optional[trace.Span]] = contextvars.ContextVar(
-    "_current_langchain_chat_span", default=None
-)
+# Set by struct.agent() when it creates the top-level invoke_agent span. The
+# LangChain handler checks this in on_chain_start: when a manual agent already
+# owns the scope (parent_run_id is None), the handler suppresses its own
+# invoke_agent span and instead parents its children to this span.
+_manual_agent_active: contextvars.ContextVar[Optional[trace.Span]] = contextvars.ContextVar("_manual_agent_active", default=None)
 
 # Pending tool_use ids keyed by tool name (FIFO per name).
 # Populated by the Anthropic monkey-patch when a chat response arrives with
@@ -77,6 +71,53 @@ _current_langchain_chat_span: contextvars.ContextVar[Optional[trace.Span]] = con
 # working unchanged (explicit override wins).
 _pending_tool_calls: contextvars.ContextVar[Optional[dict[str, list[str]]]] = contextvars.ContextVar("_pending_tool_calls", default=None)
 
+# ---------------------------------------------------------------------------
+# OTel GenAI suppression key
+# ---------------------------------------------------------------------------
+#
+# When the LangChain callback handler owns a ``chat <model>`` span for an LLM
+# call that also flows through a provider SDK (anthropic, etc.) that we
+# instrument, the handler attaches this key to the OTel context for the
+# duration of the call.  The provider-SDK wrapper checks ``is_genai_suppressed()``
+# at entry and, when True, runs the original call to completion WITHOUT creating
+# a duplicate span.  On exit the handler detaches the key via ``reset_genai()``.
+#
+# This replaces the fragile ``_current_langchain_chat_span`` enrich contextvar
+# (which required the provider wrapper to set attributes on a span it didn't own,
+# and whose contextvar token could raise ``ValueError: Token created in a different
+# Context`` when detached from a different async context).
+_GENAI_SUPPRESS_KEY = create_key("struct.suppress_genai")
+
+
+def is_genai_suppressed() -> bool:
+    """Return True if a framework layer (e.g. LangChain handler) already owns
+    the chat span for the current call — provider SDK patches should skip
+    creating their own span."""
+    return bool(_otel_context.get_value(_GENAI_SUPPRESS_KEY))
+
+
+def suppress_genai_token() -> Token[_OtelContext]:
+    """Attach the suppression key to the current OTel context.
+
+    Returns an opaque token that MUST be passed to ``reset_genai()`` when the
+    suppression window ends.  Follows the same attach/detach contract as
+    ``opentelemetry.context.attach`` / ``detach``.
+    """
+    return _otel_context.attach(_otel_context.set_value(_GENAI_SUPPRESS_KEY, True))
+
+
+def reset_genai(token: Token[_OtelContext]) -> None:
+    """Detach the suppression key token.
+
+    Tolerant of cross-context detach (e.g. async tasks that detach from a
+    different context than the one that attached): the exception is swallowed
+    so instrumentation never fails the host call.
+    """
+    try:
+        _otel_context.detach(token)
+    except Exception:  # noqa: BLE001 — cross-context detach is a no-op, never fail the host
+        pass
+
 # Registry of patched integrations — prevents double-patching
 _patched_integrations: set[str] = set()
 
@@ -264,7 +305,7 @@ class StructSDK:
         """Get an OTel tracer from our isolated provider."""
         if self._tracer_provider is None:
             raise RuntimeError("Call struct.init() before using the SDK")
-        return self._tracer_provider.get_tracer(name)
+        return self._tracer_provider.get_tracer(name, _SDK_VERSION)
 
     def get_logger(self, name: str = "struct-sdk") -> Any:
         """Get an OTel logger from our isolated provider (for gen_ai log events)."""
@@ -439,7 +480,13 @@ class _AgentContext:
     def __init__(self, sdk: StructSDK, *, name: Optional[str] = None, session_id: Optional[str] = None, agent_id: Optional[str] = None, version: Optional[str] = None, metadata: Optional[dict[str, str]] = None):
         self._sdk = sdk
         self._name = name
-        self._session_id = session_id or str(uuid.uuid4())
+        # _explicit_session_id is the CALLER-SUPPLIED value (may be None).
+        # The resolved self._session_id is computed in _start_span after we can
+        # read the ambient _current_session_id — this lets us inherit the
+        # enclosing agent's id when the caller did not supply one, and defer the
+        # "mint a fresh UUID" case until start-span time.
+        self._explicit_session_id: Optional[str] = session_id
+        self._session_id: str = session_id or ""  # placeholder; overwritten in _start_span
         self._agent_id = agent_id
         self._version = version
         self._metadata = metadata
@@ -449,12 +496,16 @@ class _AgentContext:
         self._conversation_token: Optional[contextvars.Token[Optional[str]]] = None
         self._agent_span_token: Optional[contextvars.Token[Optional[trace.Span]]] = None
         self._pending_tool_token: Optional[contextvars.Token[Optional[dict[str, list[str]]]]] = None
+        self._manual_token: Optional[contextvars.Token[Optional[trace.Span]]] = None
 
     def __call__(self, fn: Any) -> Any:
         """Use as decorator."""
         span_name = self._name or fn.__name__
         sdk = self._sdk
-        session_id = self._session_id
+        # Preserve the CALLER-SUPPLIED value so each invocation resolves the
+        # ambient session fresh (rather than baking in the UUID minted at
+        # decoration time).
+        explicit_session_id = self._explicit_session_id
         agent_id = self._agent_id
         version = self._version
         metadata = self._metadata
@@ -462,13 +513,13 @@ class _AgentContext:
         if asyncio.iscoroutinefunction(fn):
             @functools.wraps(fn)
             async def wrapper(*args: Any, **kwargs: Any) -> Any:
-                async with _AgentContext(sdk, name=span_name, session_id=session_id, agent_id=agent_id, version=version, metadata=metadata):
+                async with _AgentContext(sdk, name=span_name, session_id=explicit_session_id, agent_id=agent_id, version=version, metadata=metadata):
                     return await fn(*args, **kwargs)
             return wrapper
         else:
             @functools.wraps(fn)
             def wrapper(*args: Any, **kwargs: Any) -> Any:
-                with _AgentContext(sdk, name=span_name, session_id=session_id, agent_id=agent_id, version=version, metadata=metadata):
+                with _AgentContext(sdk, name=span_name, session_id=explicit_session_id, agent_id=agent_id, version=version, metadata=metadata):
                     return fn(*args, **kwargs)
             return wrapper
 
@@ -481,17 +532,92 @@ class _AgentContext:
             agent_name = self._name or "agent"
             tracer = self._sdk.get_tracer("struct-sdk")
 
-            # Capture the outer session id BEFORE overwriting the contextvar so we
-            # can link nested agents (subagents) back to the agent that spawned them.
-            # Subagent pattern: an outer @struct.agent() wraps a function; that function
-            # calls a tool that itself enters another @struct.agent() scope. The inner
-            # scope's struct.agent.parent_session_id points to the outer session_id.
-            parent_session_id = _current_session_id.get(None)
+            # Capture the enclosing agent's session id and span BEFORE we overwrite
+            # the contextvars.  These are used to:
+            #   1. Detect whether this agent is a break-out (explicit, different id).
+            #   2. Attach a spawned-by OTel Link if it is.
+            #   3. Set struct.agent.parent_session_id for the UI affordance.
+            enclosing_session_id = _current_session_id.get(None)
+            enclosing_agent_span = _current_agent_span.get(None)
+
+            # ── Resolve session_id (REVISION R1 grouping model) ──────────────
+            # Resolution order:
+            #   explicit caller arg  >  ambient (enclosing agent)  >  fresh UUID
+            # A caller-supplied None means "inherit"; a caller-supplied value
+            # that equals the enclosing id also means "inline".
+            if self._explicit_session_id is not None:
+                self._session_id = self._explicit_session_id
+            elif enclosing_session_id is not None:
+                # No explicit id → inherit the enclosing agent's session (inline).
+                self._session_id = enclosing_session_id
+            else:
+                # No ambient context → mint a fresh id for this root agent.
+                self._session_id = str(uuid.uuid4())
+
+            # ── Break-out detection ──────────────────────────────────────────
+            # Condition: caller supplied an EXPLICIT id AND it differs from the
+            # enclosing agent's id AND there IS an enclosing agent span.
+            # In that case this agent starts a new root trace (no OTel parent)
+            # and carries a Link back to the enclosing span.
+            break_out = (
+                self._explicit_session_id is not None
+                and enclosing_session_id is not None
+                and self._explicit_session_id != enclosing_session_id
+                and enclosing_agent_span is not None
+            )
 
-            self._span = tracer.start_span(
-                f"invoke_agent {agent_name}",
-                kind=trace.SpanKind.INTERNAL,
+            # ── Foreign-context guard (top-level agent run) ──────────────────
+            # A top-level agent run (no enclosing STRUCT agent) must NOT inherit
+            # whatever OTel span happens to be active. That active span may be a
+            # FOREIGN span leaked across an async boundary — e.g. a tool span from
+            # a PRIOR turn that a Temporal/queue context propagator carried into
+            # this later wake-up. Inheriting it would mis-parent this brand-new
+            # turn UNDER unrelated, long-finished work (it would show up nested in
+            # that old tool call instead of as its own turn).
+            #
+            # So: when there is no enclosing Struct agent but some other span is
+            # active, start a FRESH ROOT trace and record that active span as a
+            # causal OTel Link (preserving "this turn was triggered by that") —
+            # never as the parent.
+            #
+            # Genuine in-run sub-agents are unaffected: they always run with an
+            # enclosing Struct agent in scope (``enclosing_session_id`` set, because
+            # the contextvar is live in the same task), so they fall through to the
+            # inherit path below and stay nested in the same trace.
+            active_span_context = trace.get_current_span().get_span_context()
+            foreign_root = (
+                not break_out
+                and enclosing_session_id is None
+                and active_span_context.is_valid
             )
+
+            if break_out:
+                # Start a fresh root span: pass context=trace.Context() to create
+                # a span with no parent (new TraceId) while keeping the current
+                # context vars readable for the span's children.
+                assert enclosing_agent_span is not None  # narrowing for mypy
+                links = [trace.Link(enclosing_agent_span.get_span_context())]
+                self._span = tracer.start_span(
+                    f"invoke_agent {agent_name}",
+                    kind=trace.SpanKind.INTERNAL,
+                    context=_OtelContext(),  # empty context → new root trace
+                    links=links,
+                )
+            elif foreign_root:
+                # New root trace; the leaked/foreign active span becomes a Link
+                # (causal origin), NOT this turn's parent.
+                self._span = tracer.start_span(
+                    f"invoke_agent {agent_name}",
+                    kind=trace.SpanKind.INTERNAL,
+                    context=_OtelContext(),  # empty context → new root trace
+                    links=[trace.Link(active_span_context)],
+                )
+            else:
+                self._span = tracer.start_span(
+                    f"invoke_agent {agent_name}",
+                    kind=trace.SpanKind.INTERNAL,
+                )
+
             # Required
             self._span.set_attribute("gen_ai.operation.name", "invoke_agent")
             self._span.set_attribute("gen_ai.provider.name", "struct")
@@ -508,8 +634,25 @@ class _AgentContext:
             # redundant session.id.
             self._span.set_attribute("gen_ai.conversation.id", self._session_id)
             # Link to the outer agent's session, if we're nested under one.
-            if parent_session_id and parent_session_id != self._session_id:
-                self._span.set_attribute("struct.agent.parent_session_id", parent_session_id)
+            # For break-out agents: the parent is the enclosing agent.
+            # For inline nested agents: parent is the same session (same id).
+            # ``struct.agent.parent_session_id`` is a SPAWNED-BY marker — set it
+            # ONLY when this agent broke out into its own root session. For an
+            # inline subagent (same session as the enclosing agent) the parent
+            # relationship is already encoded by the OTel span tree
+            # (ParentSpanId), so stamping parent_session_id = own-session-id would
+            # be self-referential noise. Structure comes from the tree/Link, not
+            # this attr (Link-canonical decision).
+            if break_out:
+                # parent_session_id is the spawner's session (enclosing_session_id).
+                # break_out=True implies enclosing_session_id is not None (see condition above).
+                assert enclosing_session_id is not None
+                self._span.set_attribute("struct.agent.parent_session_id", enclosing_session_id)
+            elif enclosing_session_id is not None and enclosing_session_id != self._session_id:
+                # Legacy path: enclosing session exists with a DIFFERENT id but no
+                # enclosing span (break_out was False). Records the cross-session
+                # parent. Same-session inline subagents fall through with nothing.
+                self._span.set_attribute("struct.agent.parent_session_id", enclosing_session_id)
             # Custom metadata
             if self._metadata:
                 for key, value in self._metadata.items():
@@ -529,6 +672,11 @@ class _AgentContext:
             # Fresh pending-tool-calls dict scoped to this agent run, so tool_use
             # ids from an outer agent cannot leak in or out.
             self._pending_tool_token = _pending_tool_calls.set({})
+            # Signal to the LangChain handler that a manual struct.agent() owns
+            # this scope. The handler will suppress its own invoke_agent span for
+            # the same top-level chain (parent_run_id is None) and parent its
+            # children under this span instead.
+            self._manual_token = _manual_agent_active.set(self._span)
             started = True
 
         _safe(body, site="agent.start_span")
@@ -537,6 +685,11 @@ class _AgentContext:
             # _end_span see a clean "no telemetry" view: tokens are reset
             # best-effort, the OTel context stack is popped if it was pushed,
             # the span is ended if it was started, and references are dropped.
+            manual_tok = self._manual_token
+            if manual_tok is not None:
+                _safe(lambda: _manual_agent_active.reset(manual_tok),
+                      site="agent.start_span.reset_manual")
+                self._manual_token = None
             pending_tok = self._pending_tool_token
             if pending_tok is not None:
                 _safe(lambda: _pending_tool_calls.reset(pending_tok),
@@ -573,6 +726,10 @@ class _AgentContext:
     def _end_span(self, exc_val: Any = None) -> None:
         # Contextvar resets must always run — they're cheap, can't fault on the
         # span, and leaving them set leaks session context into the caller.
+        manual_tok = self._manual_token
+        if manual_tok is not None:
+            _safe(lambda: _manual_agent_active.reset(manual_tok),
+                  site="agent.exit.manual_reset")
         pending_tok = self._pending_tool_token
         if pending_tok is not None:
             _safe(lambda: _pending_tool_calls.reset(pending_tok),

{struct_sdk-0.2.5 → struct_sdk-0.2.8}/src/struct_sdk/langchain.py

@@ -107,6 +107,7 @@ def patch(sdk: StructSDK) -> None:
                 inheritable_callbacks = _inject_handler(
                     inheritable_callbacks, _active_handler
                 )
+                local_callbacks = _strip_struct(local_callbacks)
                 return orig_func(
                     cls,
                     inheritable_callbacks,
@@ -153,6 +154,19 @@ def _build_handler(sdk: StructSDK) -> "StructCallbackHandler":
     )
 
 
+def _strip_struct(cbs: Any) -> Any:
+    """Remove any handler named 'struct' from a local callbacks list.
+
+    Called by the configure wrapper after injecting our handler as inheritable,
+    so a user-supplied ``config={"callbacks": [get_langchain_handler()]}`` does
+    not end up with the handler in BOTH the inheritable and local lists — which
+    would cause every ``on_*`` callback to fire twice.
+    """
+    if isinstance(cbs, list):
+        return [h for h in cbs if getattr(h, "name", None) != "struct"]
+    return cbs
+
+
 def _inject_handler(existing: Any, handler: Optional["StructCallbackHandler"]) -> Any:
     """Merge our handler into the inheritable_handlers argument, with de-dup."""
     if handler is None:
@@ -308,6 +322,24 @@ _INTERNAL_RUN_NAME_PREFIXES = (
 _THREAD_KEYS: tuple[str, ...] = ("thread_id", "session_id", "conversation_id")
 
 
+def _checkpoint_ns(metadata: Optional[dict[str, Any]]) -> Optional[str]:
+    """LangGraph stamps a unique ``langgraph_checkpoint_ns`` (``tools:<uuid>``)
+    on each tool-call branch, and the SAME value on the sub-agent graph that the
+    tool triggers — even across parallel same-named tool calls. We use it to
+    re-parent a sub-agent's ``invoke_agent`` span under its triggering
+    ``execute_tool`` span. Returns the namespace, or ``None`` if absent.
+    """
+    # Guard on ``isinstance`` (not just truthiness): LangChain normally passes a
+    # dict, but a truthy non-dict would make ``.get`` raise. This runs inside the
+    # callback handler in the customer's process, so it must never throw.
+    if not isinstance(metadata, dict):
+        return None
+    ns = metadata.get("langgraph_checkpoint_ns")
+    if isinstance(ns, str) and ns:
+        return ns
+    return None
+
+
 def _metadata_thread_id(metadata: Optional[dict[str, Any]]) -> Optional[str]:
     """Pull the conversation/thread id from a LangChain ``metadata`` dict.
 
@@ -536,25 +568,17 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
     in favour of the GenAI-spec name.
 
     For SUBAGENTS (an agent invoked from inside another's tool body) we
-    deliberately assign a DIFFERENT ``conversation.id`` — either the
-    subagent's own ``thread_id`` if supplied, or a fresh UUID. The resulting
-    subagent span is linked to the outer agent via our
-    ``struct.agent.parent_session_id`` attribute (what powers "Spawned by"
-    navigation in the UI). Without this split, subagent spans would collapse
-    into the outer session and hide delegation.
-
-    LangChain quirk (handled automatically): when ``agent.invoke(...)`` runs
-    nested inside a parent call, LangChain's config-merge inherits the
-    parent's ``metadata.thread_id`` onto the child — even if the child
-    config supplied its own. We detect that by comparing against the
-    nearest agent ancestor's session; if they match, treat as "inherited,
-    not user-intended" and assign a fresh UUID.
+    INHERIT the parent's ``gen_ai.conversation.id`` so that the entire run
+    shares one id. If a subagent supplies its own ``thread_id`` in metadata,
+    that value is recorded as the non-grouping ``struct.agent.thread_id``
+    attribute — it is NOT used as the conversation grouping key. The
+    structural parent→child relationship is recorded via
+    ``struct.agent.parent_session_id``.
 
     End-user guidance:
       * Use thread_id per conversation; multi-turn chats reuse it.
-      * For a subagent call, pass a DIFFERENT thread_id (or omit it and let
-        LangGraph generate one). Subagents then surface as their own
-        sessions in the UI, linked back via parent_session_id.
+      * A subagent's thread_id (if any) is preserved as ``struct.agent.thread_id``
+        and does not split the run into a new session.
     """
 
     name = "struct"
@@ -573,6 +597,13 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         self._tracer = tracer
         self._logger = otel_logger
         self._runs: dict[str, _RunState] = {}
+        # LangChain agent-as-tool correlation: index live ``execute_tool`` spans
+        # by their ``langgraph_checkpoint_ns`` so a sub-agent graph triggered
+        # inside a tool (a SIBLING in the run tree, sharing that exact ns) can
+        # re-parent its ``invoke_agent`` span under the tool. ``_tool_ns_by_run``
+        # lets on_tool_end / on_tool_error remove the index entry.
+        self._tool_spans_by_ns: dict[str, trace.Span] = {}
+        self._tool_ns_by_run: dict[str, str] = {}
 
     # ── Chain / Agent ───────────────────────────────────────────────────────
 
@@ -616,9 +647,38 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         session_id = self._resolve_agent_session_id(metadata, parent_agent_session_id)
         parent = self._resolve_parent(parent_key)
 
+        # Suppress twin invoke_agent: when struct.agent() already owns this top-level
+        # run (parent_key is None, manual ownership contextvar is set), record the
+        # run pointing at the manual span so descendants parent under it — but emit
+        # NO new invoke_agent span.
+        if parent_key is None:
+            from struct_sdk.core import _manual_agent_active, _current_session_id
+            manual_span = _manual_agent_active.get(None)
+            if manual_span is not None:
+                manual_session = _current_session_id.get(None) or session_id
+                self._runs[key] = _RunState(
+                    span=manual_span,
+                    effective_parent_span=manual_span,
+                    session_id=manual_session,
+                    nearest_agent_session_id=manual_session,
+                    nearest_agent_span=manual_span,
+                    kind="suppressed-twin",
+                )
+                return
+
         agent_name: str = "agent"
         span: Optional[trace.Span] = None
 
+        # LangChain agent-as-tool: a sub-agent graph runs as a SIBLING of its
+        # triggering execute_tool (parent_run_id points at the ToolNode, not the
+        # tool), so normal resolution would emit this invoke_agent as a sibling.
+        # But LangGraph stamps the tool branch and its sub-agent with the same
+        # ``langgraph_checkpoint_ns`` — unique even across parallel same-named
+        # calls — so re-parent under the matching live execute_tool span to nest
+        # natively (the UI's direct-tool-child path). Falls back to the resolved
+        # parent when there is no tool match (native struct-sdk / non-tool chains).
+        delegating_tool_span = self._tool_spans_by_ns.get(_checkpoint_ns(metadata) or "")
+
         def create_span() -> None:
             nonlocal span, agent_name
             agent_name = (
@@ -627,7 +687,8 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
                 or (inputs.get("name") if isinstance(inputs, dict) else None)
                 or "agent"
             )
-            parent_ctx = trace.set_span_in_context(parent.span) if parent.span else None
+            ctx_span = delegating_tool_span or parent.span
+            parent_ctx = trace.set_span_in_context(ctx_span) if ctx_span else None
             span = self._tracer.start_span(
                 f"invoke_agent {agent_name}",
                 kind=trace.SpanKind.INTERNAL,
@@ -672,6 +733,13 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             # existing "View sub-agent →" drill-in flow kicks in.
             if parent_agent_session_id:
                 span.set_attribute("struct.agent.parent_session_id", parent_agent_session_id)
+            # If the caller supplied a local thread_id that differs from the
+            # inherited conversation id, preserve it as a non-grouping attribute.
+            # This lets downstream consumers see the subagent's own thread
+            # identity without splitting the run into separate sessions.
+            local_thread = _metadata_thread_id(metadata)
+            if local_thread and local_thread != session_id:
+                span.set_attribute("struct.agent.thread_id", local_thread)
 
         _safe(set_attrs, site="langchain.on_chain_start.start_attrs")
 
@@ -697,6 +765,10 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         r = self._runs.pop(str(run_id), None)
         if not r or not r.span:
             return
+        if r.kind == "suppressed-twin":
+            # The span is the manual struct.agent() span owned by core.py's
+            # _AgentContext.__aexit__. Do not end it here.
+            return
         span = r.span
         _safe(lambda: span.set_status(StatusCode.OK),
               site="langchain.on_chain_end.set_status")
@@ -715,6 +787,10 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         r = self._runs.pop(str(run_id), None)
         if not r or not r.span:
             return
+        if r.kind == "suppressed-twin":
+            # The span is the manual struct.agent() span owned by core.py's
+            # _AgentContext.__aexit__. Do not end or record error here.
+            return
         span = r.span
         _safe(lambda: _record_error(span, error),
               site="langchain.on_chain_error.record_error")
@@ -799,14 +875,15 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
 
         _safe(set_attrs, site="langchain.on_chat_model_start.start_attrs")
 
-        # Announce this langchain chat span to any provider-SDK instrumentation
-        # (anthropic, etc.) that runs UNDER LangChain — they'll enrich this
-        # span with HTTP-layer attrs instead of creating their own duplicate.
-        # The token is saved on the RunState so on_llm_end can reset it.
-        from struct_sdk.core import _current_langchain_chat_span
+        # Attach the OTel suppression key so any provider-SDK instrumentation
+        # (anthropic, etc.) running under LangChain skips creating a duplicate
+        # span — the handler already owns the ``chat <model>`` span.
+        # The token is saved on the RunState so on_llm_end / on_llm_error can
+        # detach it via reset_genai().
+        from struct_sdk.core import suppress_genai_token
         enrich_token = None
         try:
-            enrich_token = _current_langchain_chat_span.set(span)
+            enrich_token = suppress_genai_token()
         except Exception:  # noqa: BLE001 — never fail the host call on instrumentation
             enrich_token = None
 
@@ -850,29 +927,27 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         parent_run_id: Optional[UUID] = None,
         **kwargs: Any,
     ) -> None:
-        from struct_sdk.core import _safe, _current_langchain_chat_span
+        from struct_sdk.core import _safe, reset_genai
 
         r = self._runs.pop(str(run_id), None)
         if not r or not r.span:
             # Even if the span was never created (telemetry-disabled fallback),
-            # we still need to reset the enrich-contextvar token so it doesn't
+            # we still need to detach the suppression token so it doesn't
             # leak into the next operation in this task.
             if r is not None and r.enrich_token is not None:
                 _safe(
-                    lambda: _current_langchain_chat_span.reset(r.enrich_token),
-                    site="langchain.on_llm_end.reset_enrich_token",
+                    lambda: reset_genai(r.enrich_token),
+                    site="langchain.on_llm_end.reset_suppress",
                 )
             return
         span = r.span
 
-        # Reset the enrich-token contextvar BEFORE ending the span. Any
-        # post-end attribute set by provider-SDK instrumentation would race
-        # against ``span.end()`` and likely no-op anyway, so we close the
-        # door before we close the span.
+        # Detach the OTel suppression key BEFORE ending the span so the
+        # provider-SDK window is cleanly closed before we finalize the span.
         if r.enrich_token is not None:
             _safe(
-                lambda: _current_langchain_chat_span.reset(r.enrich_token),
-                site="langchain.on_llm_end.reset_enrich_token",
+                lambda: reset_genai(r.enrich_token),
+                site="langchain.on_llm_end.reset_suppress",
             )
 
         def set_response_attrs() -> None:
@@ -918,18 +993,18 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         parent_run_id: Optional[UUID] = None,
         **kwargs: Any,
     ) -> None:
-        from struct_sdk.core import _safe, _current_langchain_chat_span
+        from struct_sdk.core import _safe, reset_genai
 
         r = self._runs.pop(str(run_id), None)
         if not r:
             return
-        # Always reset the enrich-token contextvar, even when there's no
-        # span — leaving it set would leak the (now-defunct) span into the
-        # next operation in this task.
+        # Always detach the suppression token, even when there's no span —
+        # leaving it attached would suppress the provider's span for the next
+        # operation in this task.
         if r.enrich_token is not None:
             _safe(
-                lambda: _current_langchain_chat_span.reset(r.enrich_token),
-                site="langchain.on_llm_error.reset_enrich_token",
+                lambda: reset_genai(r.enrich_token),
+                site="langchain.on_llm_error.reset_suppress",
             )
         if not r.span:
             return
@@ -997,7 +1072,11 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             span.set_attribute("gen_ai.provider.name", "langchain")
             span.set_attribute("gen_ai.tool.name", str(tool_name))
 
-            tool_call_id = _extract_tool_call_id_from_inputs(inputs) or _pop_pending_tool_call_id(str(tool_name))
+            tool_call_id = (
+                kwargs.get("tool_call_id")
+                or _extract_tool_call_id_from_inputs(inputs)
+                or _pop_pending_tool_call_id(str(tool_name))
+            )
             if tool_call_id:
                 span.set_attribute("gen_ai.tool.call.id", tool_call_id)
 
@@ -1020,6 +1099,13 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             kind="tool",
         )
 
+        # Index by checkpoint ns so a sub-agent graph triggered inside this tool
+        # (sharing this exact ns) re-parents its invoke_agent span under us.
+        tool_ns = _checkpoint_ns(metadata)
+        if tool_ns is not None:
+            self._tool_spans_by_ns[tool_ns] = span
+            self._tool_ns_by_run[key] = tool_ns
+
     def on_tool_end(
         self,
         output: Any,
@@ -1030,6 +1116,9 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
     ) -> None:
         from struct_sdk.core import _safe
 
+        ns = self._tool_ns_by_run.pop(str(run_id), None)
+        if ns is not None:
+            self._tool_spans_by_ns.pop(ns, None)
         r = self._runs.pop(str(run_id), None)
         if not r or not r.span:
             return
@@ -1057,6 +1146,9 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
     ) -> None:
         from struct_sdk.core import _safe
 
+        ns = self._tool_ns_by_run.pop(str(run_id), None)
+        if ns is not None:
+            self._tool_spans_by_ns.pop(ns, None)
         r = self._runs.pop(str(run_id), None)
         if not r or not r.span:
             return
@@ -1265,22 +1357,14 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         metadata: Optional[dict[str, Any]],
         parent_agent_session_id: Optional[str] = None,
     ) -> str:
-        """For AGENT spans — each invocation gets its own conversation id.
-
-        Prefer config-supplied thread_id for multi-turn continuity, fall
-        back to a fresh UUID. Never inherit from the parent run —
-        subagents should surface as separate sessions in the UI.
-
-        LangChain quirk: when a nested invoke runs inside a parent call,
-        LangChain inherits the parent's metadata.thread_id onto the child
-        even if the child supplied its own. Detect that by comparing
-        against the nearest-agent-ancestor's session and assign a fresh
-        UUID if they match.
+        """Agent spans INHERIT the nearest-agent ancestor's conversation id so a
+        whole run shares one id. A locally-supplied thread_id is preserved by the
+        caller as ``struct.agent.thread_id`` (non-grouping) — it never splits the run.
         """
+        if parent_agent_session_id:
+            return parent_agent_session_id
         thread_id = _metadata_thread_id(metadata)
         if thread_id:
-            if parent_agent_session_id and thread_id == parent_agent_session_id:
-                return str(uuid.uuid4())
             return thread_id
         from struct_sdk.core import _current_session_id
         ambient = _current_session_id.get(None)
@@ -1304,12 +1388,11 @@ class _RunState:
         "nearest_agent_session_id",
         "nearest_agent_span",
         "kind",
-        # Only set on LLM / chat runs. Holds the ``contextvars.Token`` returned
-        # by ``_current_langchain_chat_span.set(span)`` so on_llm_end /
-        # on_llm_error can reset the contextvar. The contextvar's purpose:
-        # tell provider-SDK instrumentations (anthropic, openai, etc.)
-        # "you're running underneath this LangChain chat span — enrich it
-        # with your HTTP-layer attrs, don't create a duplicate span."
+        # Only set on LLM / chat runs. Holds the OTel context token returned
+        # by ``suppress_genai_token()`` so on_llm_end / on_llm_error can
+        # detach it via ``reset_genai()``. The suppression key tells
+        # provider-SDK instrumentations (anthropic, openai, etc.)
+        # "a framework layer owns the chat span — skip creating a duplicate."
         "enrich_token",
     )
 
@@ -1407,25 +1490,24 @@ def _set_llm_response_attrs(
         mapped = _LANGCHAIN_FINISH_REASON_MAP.get(finish, finish)
         span.set_attribute("gen_ai.response.finish_reasons", [mapped])
 
-    resp_id = getattr(message, "id", None) or resp_meta.get("id")
+    # Prefer the provider message id (``msg_…`` / ``chatcmpl-…``) from
+    # response_metadata over LangChain's generated run id (``run-…`` /
+    # ``lc_run--…``).  ChatAnthropic (and most LangChain chat model adapters)
+    # place the real API-level id in ``response_metadata["id"]`` while
+    # ``message.id`` carries a LangChain-internal run UUID.  We use
+    # gen_ai.response.id as the duplicate-detection fingerprint, so the
+    # provider id must take priority.  The LangChain run id is preserved
+    # under ``langchain.run.id`` for joining back to LangSmith / LangChain
+    # run data.
+    provider_id = resp_meta.get("id")
+    lc_run_id = getattr(message, "id", None)
+    resp_id = provider_id or lc_run_id
     if isinstance(resp_id, str):
-        # If a provider-SDK instrumentation (e.g. struct-sdk-anthropic via
-        # the enrich path) has already set gen_ai.response.id to the
-        # real provider message id (e.g. ``msg_…``), don't clobber it
-        # with LangChain's run UUID (``lc_run--…``). The provider id is
-        # more useful for API-level debugging. LangChain's run UUID is
-        # preserved under ``langchain.run.id`` for joining back to
-        # LangSmith / LangChain run data.
-        try:
-            existing = (span.attributes or {}).get("gen_ai.response.id") \
-                if hasattr(span, "attributes") else None
-        except Exception:  # noqa: BLE001
-            existing = None
-        if not existing:
-            span.set_attribute("gen_ai.response.id", resp_id)
-        elif resp_id != existing:
-            # LangChain's id is distinct from the provider's — keep both.
-            span.set_attribute("langchain.run.id", resp_id)
+        span.set_attribute("gen_ai.response.id", resp_id)
+        # When the LangChain run id differs from the provider id, record
+        # it separately so consumers can still join on the run UUID.
+        if isinstance(lc_run_id, str) and lc_run_id != resp_id:
+            span.set_attribute("langchain.run.id", lc_run_id)
 
     if sdk.emit_events and otel_logger:
         _emit_choice_event(otel_logger, message, provider or "langchain", session_id, span)
@@ -1535,7 +1617,7 @@ def _emit_message_events(
             attrs: dict[str, Any] = {
                 "event.name": event_name,
                 "body": payload,
-                "gen_ai.system": provider,
+                "gen_ai.provider.name": provider,
                 "gen_ai.message.index": idx,
                 "gen_ai.conversation.id": session_id,
             }
@@ -1577,7 +1659,7 @@ def _emit_choice_event(
         attrs: dict[str, Any] = {
             "event.name": event_name,
             "body": payload,
-            "gen_ai.system": provider,
+            "gen_ai.provider.name": provider,
             "gen_ai.conversation.id": session_id,
         }
         otel_logger.emit(LogRecord(