struct-sdk 0.1.0__tar.gz → 0.2.1__tar.gz

{struct_sdk-0.1.0 → struct_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -30,8 +30,9 @@ Provides-Extra: claude-agent-sdk
 Requires-Dist: claude-agent-sdk>=0.1.59; extra == 'claude-agent-sdk'
 Provides-Extra: demo
 Requires-Dist: langchain-anthropic>=0.3.0; extra == 'demo'
-Requires-Dist: langchain-core>=0.3.0; extra == 'demo'
+Requires-Dist: langchain-core>=1.3.3; extra == 'demo'
 Requires-Dist: langchain-openai>=0.2.0; extra == 'demo'
+Requires-Dist: langchain>=1.3.0; extra == 'demo'
 Requires-Dist: langgraph>=0.2.0; extra == 'demo'
 Requires-Dist: python-dotenv>=1.0.0; extra == 'demo'
 Provides-Extra: dev
@@ -40,7 +41,7 @@ Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Provides-Extra: langchain
-Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Requires-Dist: langchain-core>=1.3.3; extra == 'langchain'
 Description-Content-Type: text/markdown
 
 # struct-sdk
@@ -107,7 +108,7 @@ async with struct.agent(name="checkout"):
 | `langchain_core` `BaseChatModel` | `chat {model}` | Skipped when an underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic` → a single span). |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |
 | `langchain_core` `BaseRetriever` | `retrieval {name}` | |
-| `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent` and custom graphs. `thread_id` → `gen_ai.conversation.id`. |
+| `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent`, `langchain.agents.create_agent`, and custom graphs. Reads conversation id from any of: `configurable.thread_id` (LangGraph canonical), or `metadata.{thread_id, session_id, conversation_id}` (LangSmith conventions). For multi-turn HTTP-style threading, wrap your entry point in [`struct.agent(session_id=conv_id)`](#recommended-pattern-wrap-langchain-entry-points-in-structagent) — that's the struct-native replacement for `ls.tracing_context(parent=run_tree)`. |
 
 ## Framework integration
 
@@ -155,6 +156,40 @@ from langgraph.prebuilt import create_react_agent
 # execute_tool spans. BaseRetriever.invoke gets retrieval spans.
 ```
 
+##### Recommended pattern: wrap LangChain entry points in `struct.agent`
+
+For multi-turn HTTP-style usage (every request continues the same
+conversation), wrap your request handler in
+`struct.agent(session_id=conversation_id)`. This is the struct-native
+replacement for `with ls.tracing_context(parent=run_tree):` and gives
+you two things you can't get from `configurable.thread_id` alone:
+
+1. **Threading without per-call config plumbing.** Every nested
+   LangChain call inherits the conversation id via the SDK's ambient
+   contextvar — you don't have to ensure each `compiled_graph.ainvoke`
+   gets `thread_id` on its config.
+2. **One trace per request.** `struct.agent` creates a parent OTel span
+   so all the LangChain work for the request nests under one trace
+   (clean tree, "Subagents" / "Spawned by" UI links work). Without it,
+   each `.invoke()` becomes its own root trace, and the UI's session
+   list shows a non-deterministic agent name (`omni_agent`,
+   `LangGraph`, the first sub-agent it sees…).
+
+Migrating from LangSmith:
+
+```python
+# Before — LangSmith convention, fragments under struct-sdk
+with ls.tracing_context(parent=run_tree):
+    await orchestrator.ainvoke(inputs, config=config)
+
+# After — struct-native, threads correctly, no langsmith dep
+async with struct.agent(session_id=conversation_id):
+    await orchestrator.ainvoke(inputs, config=config)
+```
+
+Also works as a sync context manager (`with struct.agent(...)`) for
+non-async handlers.
+
 ### LLM SDKs used directly — manual agent + tool scopes required
 
 When you call an LLM SDK directly (no agent framework wrapping it), only
@@ -268,8 +303,19 @@ async def run_checkout(order_id: str):
     return await charge()
 ```
 
-Nested agents are linked to their parent via the
-`struct.agent.parent_session_id` attribute on the inner span.
+Sub-agents (e.g. a `create_agent` graph invoked from inside another
+agent's tool body) record their parent via the
+`struct.agent.parent_session_id` attribute on the inner `invoke_agent`
+span. This powers the UI's "Spawned by" backlink, which works for any
+nested invocation.
+
+The parent's "Subagents" forward list — the inverse direction —
+additionally requires that the nested invoke shares the outer agent's
+trace. This works automatically when the outer tool is built with the
+`@tool` decorator (or any callback-aware wrapping) since the nested
+invoke inherits the parent's run state. Bare `Tool(...)` constructors
+that bypass the callback chain can break the forward link; the
+backlink still renders.
 
 ## Semantic conventions
 

{struct_sdk-0.1.0 → struct_sdk-0.2.1}/README.md

@@ -62,7 +62,7 @@ async with struct.agent(name="checkout"):
 | `langchain_core` `BaseChatModel` | `chat {model}` | Skipped when an underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic` → a single span). |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |
 | `langchain_core` `BaseRetriever` | `retrieval {name}` | |
-| `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent` and custom graphs. `thread_id` → `gen_ai.conversation.id`. |
+| `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent`, `langchain.agents.create_agent`, and custom graphs. Reads conversation id from any of: `configurable.thread_id` (LangGraph canonical), or `metadata.{thread_id, session_id, conversation_id}` (LangSmith conventions). For multi-turn HTTP-style threading, wrap your entry point in [`struct.agent(session_id=conv_id)`](#recommended-pattern-wrap-langchain-entry-points-in-structagent) — that's the struct-native replacement for `ls.tracing_context(parent=run_tree)`. |
 
 ## Framework integration
 
@@ -110,6 +110,40 @@ from langgraph.prebuilt import create_react_agent
 # execute_tool spans. BaseRetriever.invoke gets retrieval spans.
 ```
 
+##### Recommended pattern: wrap LangChain entry points in `struct.agent`
+
+For multi-turn HTTP-style usage (every request continues the same
+conversation), wrap your request handler in
+`struct.agent(session_id=conversation_id)`. This is the struct-native
+replacement for `with ls.tracing_context(parent=run_tree):` and gives
+you two things you can't get from `configurable.thread_id` alone:
+
+1. **Threading without per-call config plumbing.** Every nested
+   LangChain call inherits the conversation id via the SDK's ambient
+   contextvar — you don't have to ensure each `compiled_graph.ainvoke`
+   gets `thread_id` on its config.
+2. **One trace per request.** `struct.agent` creates a parent OTel span
+   so all the LangChain work for the request nests under one trace
+   (clean tree, "Subagents" / "Spawned by" UI links work). Without it,
+   each `.invoke()` becomes its own root trace, and the UI's session
+   list shows a non-deterministic agent name (`omni_agent`,
+   `LangGraph`, the first sub-agent it sees…).
+
+Migrating from LangSmith:
+
+```python
+# Before — LangSmith convention, fragments under struct-sdk
+with ls.tracing_context(parent=run_tree):
+    await orchestrator.ainvoke(inputs, config=config)
+
+# After — struct-native, threads correctly, no langsmith dep
+async with struct.agent(session_id=conversation_id):
+    await orchestrator.ainvoke(inputs, config=config)
+```
+
+Also works as a sync context manager (`with struct.agent(...)`) for
+non-async handlers.
+
 ### LLM SDKs used directly — manual agent + tool scopes required
 
 When you call an LLM SDK directly (no agent framework wrapping it), only
@@ -223,8 +257,19 @@ async def run_checkout(order_id: str):
     return await charge()
 ```
 
-Nested agents are linked to their parent via the
-`struct.agent.parent_session_id` attribute on the inner span.
+Sub-agents (e.g. a `create_agent` graph invoked from inside another
+agent's tool body) record their parent via the
+`struct.agent.parent_session_id` attribute on the inner `invoke_agent`
+span. This powers the UI's "Spawned by" backlink, which works for any
+nested invocation.
+
+The parent's "Subagents" forward list — the inverse direction —
+additionally requires that the nested invoke shares the outer agent's
+trace. This works automatically when the outer tool is built with the
+`@tool` decorator (or any callback-aware wrapping) since the nested
+invoke inherits the parent's run state. Bare `Tool(...)` constructors
+that bypass the callback chain can break the forward link; the
+backlink still renders.
 
 ## Semantic conventions
 

{struct_sdk-0.1.0 → struct_sdk-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.1.0"
+version = "0.2.1"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -38,9 +38,10 @@ Issues = "https://struct.ai/support"
 [project.optional-dependencies]
 anthropic = ["anthropic>=0.30.0"]
 claude-agent-sdk = ["claude-agent-sdk>=0.1.59"]
-langchain = ["langchain-core>=0.2.0"]
+langchain = ["langchain-core>=1.3.3"]
 demo = [
-    "langchain-core>=0.3.0",
+    "langchain>=1.3.0",
+    "langchain-core>=1.3.3",
     "langchain-openai>=0.2.0",
     "langchain-anthropic>=0.3.0",
     "langgraph>=0.2.0",
@@ -64,10 +65,10 @@ dev = [
 [tool.uv]
 override-dependencies = [
     "cryptography>=46.0.7",
-    "langgraph>=1.0.10,!=1.1.7",
-    "langgraph-checkpoint>=4.0.0",
+    "langgraph>=1.2.0,<1.3.0",
+    "langgraph-checkpoint>=4.1.0,<5.0.0",
     "langchain-text-splitters>=1.1.2",
-    "python-multipart>=0.0.26",
+    "python-multipart>=0.0.27",
 ]
 
 [tool.mypy]

{struct_sdk-0.1.0 → struct_sdk-0.2.1}/src/struct_sdk/anthropic.py

@@ -116,11 +116,49 @@ def _create_common(
     extraction, error-path attribute writes) are wrapped in ``_safe`` so a
     failure inside instrumentation can never replace the user's response or
     mask the user's API exception.
+
+    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.
     """
-    from struct_sdk.core import _safe
+    from struct_sdk.core import _safe, _current_langchain_chat_span
 
     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",
+        )
+        return result  # noqa: B901
+
     with tracer.start_as_current_span(
         f"chat {model}", kind=trace.SpanKind.CLIENT
     ) as span:
@@ -171,12 +209,27 @@ def _create_common(
         try:
             result = yield f, args, kwargs
         except Exception as e:
-            _safe(lambda: span.set_attribute("error.type", type(e).__name__),
-                  site="anthropic.create.error_type")
-            _safe(lambda: span.set_status(StatusCode.ERROR, str(e)),
-                  site="anthropic.create.error_status")
-            _safe(lambda: span.record_exception(e),
-                  site="anthropic.create.record_exception")
+            # Snapshot ``e`` outside the lambdas — ``except X as e`` unbinds
+            # ``e`` at end-of-block, and ruff (correctly) flags closures that
+            # reference it. The lambdas run synchronously inside the except
+            # via ``_safe``, so this is mechanically equivalent — just legible
+            # to static analysis. ``type(exc).__name__`` is cheap and won't
+            # raise; ``str(exc)`` runs inside ``_safe`` so a broken
+            # ``__str__`` can't mask the original exception we're re-raising.
+            exc = e
+            err_type = type(exc).__name__
+            _safe(
+                lambda: span.set_attribute("error.type", err_type),
+                site="anthropic.create.error_type",
+            )
+            _safe(
+                lambda: span.set_status(StatusCode.ERROR, str(exc)),
+                site="anthropic.create.error_status",
+            )
+            _safe(
+                lambda: span.record_exception(exc),
+                site="anthropic.create.record_exception",
+            )
             raise
         _safe(lambda: _set_response_attrs(span, sdk, model, result, otel_logger),
               site="anthropic.create.set_response_attrs")
@@ -273,9 +326,16 @@ 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
+            from struct_sdk.core import _safe, _current_session_id, _current_langchain_chat_span
             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:
+                return await original(*args, **kwargs) if _is_coroutine(original) else original(*args, **kwargs)
+
             span: Optional[trace.Span] = None
 
             def start() -> None:
@@ -318,9 +378,14 @@ 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
+            from struct_sdk.core import _safe, _current_session_id, _current_langchain_chat_span
             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:
+                return original(*args, **kwargs)
+
             span: Optional[trace.Span] = None
 
             def start() -> None:

{struct_sdk-0.1.0 → struct_sdk-0.2.1}/src/struct_sdk/core.py

@@ -47,6 +47,27 @@ _current_session_id: contextvars.ContextVar[Optional[str]] = contextvars.Context
 _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
+)
+
 # Pending tool_use ids keyed by tool name (FIFO per name).
 # Populated by the Anthropic monkey-patch when a chat response arrives with
 # tool_use blocks, consumed by @struct.tool() / struct.tool(...) when the

{struct_sdk-0.1.0 → struct_sdk-0.2.1}/src/struct_sdk/langchain.py

@@ -251,6 +251,7 @@ _AGENT_CLASSES = {
 # ``serialized`` is usually ``None`` for these, so we filter on run_name via a
 # denylist. Matches LangSmith's promotion heuristic.
 _INTERNAL_RUN_NAMES = {
+    # Runnable wiring/plumbing
     "RunnableSequence",
     "RunnableLambda",
     "RunnablePassthrough",
@@ -263,15 +264,31 @@ _INTERNAL_RUN_NAMES = {
     "RunnableEach",
     "RunnablePick",
     "RunnableGenerator",
+    # Prompt templates
     "Prompt",
     "ChatPromptTemplate",
     "PromptTemplate",
+    # langchain.agents (1.x) / legacy create_react_agent internal node names
     "agent",
     "tools",
     "call_model",
     "should_continue",
     "__start__",
     "__end__",
+    # Output parsers — invoked as Runnables but not agents. LangChain's
+    # ``langchain.agents.create_agent`` with ``ToolStrategy`` (or fallback
+    # from ``ProviderStrategy`` on models without native structured output)
+    # invokes these as a separate step and they fire on_chain_start.
+    "PydanticToolsParser",
+    "PydanticOutputParser",
+    "JsonOutputParser",
+    "JsonOutputToolsParser",
+    "JsonOutputKeyToolsParser",
+    "StrOutputParser",
+    "OutputParser",
+    "BaseOutputParser",
+    "OpenAIToolsAgentOutputParser",
+    "OpenAIFunctionsAgentOutputParser",
 }
 
 _INTERNAL_RUN_NAME_PREFIXES = (
@@ -281,17 +298,68 @@ _INTERNAL_RUN_NAME_PREFIXES = (
 )
 
 
+# Threading-id metadata keys, in resolution order.
+#
+# ``thread_id`` is LangGraph's canonical name (checkpointer key); ``session_id``
+# and ``conversation_id`` are the LangSmith conventions documented at
+# https://docs.langchain.com/langsmith/threads — when users tag a run with any
+# of these, we treat it as the conversation grouping key. This makes
+# struct-sdk drop-in compatible for users following either naming.
+_THREAD_KEYS: tuple[str, ...] = ("thread_id", "session_id", "conversation_id")
+
+
+def _metadata_thread_id(metadata: Optional[dict[str, Any]]) -> Optional[str]:
+    """Pull the conversation/thread id from a LangChain ``metadata`` dict.
+
+    Reads ``thread_id`` first (LangGraph canonical), then falls back to
+    ``session_id`` and ``conversation_id`` (LangSmith conventions). Returns
+    ``None`` if none are present as non-empty strings, so callers can chain
+    to their own fallbacks (ambient ``_current_session_id``, fresh UUID).
+    """
+    if not metadata:
+        return None
+    for key in _THREAD_KEYS:
+        v = metadata.get(key)
+        if isinstance(v, str) and v:
+            return v
+    return None
+
+
 def _is_agent_chain(
     serialized: Optional[dict[str, Any]],
     run_type: Optional[str],
     run_name: Optional[str],
+    metadata: Optional[dict[str, Any]] = None,
 ) -> bool:
-    """Only promote user-meaningful chains to ``invoke_agent`` spans."""
+    """Only promote user-meaningful chains to ``invoke_agent`` spans.
+
+    Decision order:
+
+    1. Explicit ``run_type='agent'`` (legacy AgentExecutor) → agent.
+    2. ``serialized`` class identifies a Pregel/CompiledStateGraph → agent.
+    3. ``metadata['langgraph_node'] == run_name`` → INTERNAL Pregel node
+       (every internal step of a ``create_agent`` Pregel fires on_chain_start
+       with metadata.langgraph_node set to its node name; for real top-level
+       agents or sub-agents the names differ or langgraph_node is absent).
+    4. Known LangChain plumbing run names (denylist) → not agent.
+    5. Otherwise, if there's a run_name → agent (user-named chain).
+    """
     if run_type == "agent":
         return True
     cls = _extract_class_name(serialized)
     if cls in _AGENT_CLASSES:
         return True
+    # Internal Pregel node detection: LangGraph populates metadata with
+    # ``langgraph_node`` (and ``langgraph_step``) on every internal node
+    # callback. The run_name of an internal node matches its langgraph_node;
+    # for the top-level Pregel invocation, langgraph_node is absent; for a
+    # sub-agent invoked from a tool body, langgraph_node may be set BUT
+    # contains the *parent's* node name (e.g. "tools"), which differs from
+    # the sub-agent's own run_name. So equality is the discriminator.
+    if metadata and run_name:
+        lg_node = metadata.get("langgraph_node")
+        if isinstance(lg_node, str) and lg_node and lg_node == run_name:
+            return False
     if run_name:
         if run_name in _INTERNAL_RUN_NAMES:
             return False
@@ -526,7 +594,7 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         key = str(run_id)
         parent_key = str(parent_run_id) if parent_run_id else None
 
-        if not _is_agent_chain(serialized or {}, run_type, run_name):
+        if not _is_agent_chain(serialized or {}, run_type, run_name, metadata):
             # Skipped chain — record entry so descendants can walk the parent
             # chain and find the nearest agent ancestor's session id.
             effective_parent = self._resolve_parent(parent_key).span
@@ -590,10 +658,19 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             # Don't set gen_ai.agent.id from session_id — the spec uses agent.id
             # for a stable agent-definition identifier, not per-invocation.
             span.set_attribute("gen_ai.conversation.id", session_id)
-            if (
-                parent_agent_session_id
-                and parent_agent_session_id != session_id
-            ):
+            # Always set parent_session_id when there's a parent agent — even
+            # if it matches our own session_id (which happens when the SDK's
+            # ambient ``_current_session_id`` propagates through nested
+            # invoke_agent spans, e.g. ``struct.agent(session_id=conv_id)``
+            # wrapping multiple inner agents).
+            #
+            # The attribute encodes "this span has a parent agent" as
+            # structural information — the UI uses it to decide whether to
+            # inline a subagent under its triggering tool call vs render it
+            # as a top-level turn. When the values match, this signals an
+            # *intentionally inlined* subagent; when they differ, the UI's
+            # 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)
 
         _safe(set_attrs, site="langchain.on_chain_start.start_attrs")
@@ -722,6 +799,17 @@ 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
+        enrich_token = None
+        try:
+            enrich_token = _current_langchain_chat_span.set(span)
+        except Exception:  # noqa: BLE001 — never fail the host call on instrumentation
+            enrich_token = None
+
         self._runs[key] = _RunState(
             span=span,
             effective_parent_span=span,
@@ -729,6 +817,7 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             nearest_agent_session_id=self._inherited_agent_session_id(parent_key),
             nearest_agent_span=self._inherited_agent_span(parent_key),
             kind="llm",
+            enrich_token=enrich_token,
         )
 
     def on_llm_start(
@@ -761,13 +850,31 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         parent_run_id: Optional[UUID] = None,
         **kwargs: Any,
     ) -> None:
-        from struct_sdk.core import _safe
+        from struct_sdk.core import _safe, _current_langchain_chat_span
 
         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
+            # 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",
+                )
             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.
+        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",
+            )
+
         def set_response_attrs() -> None:
             generations = getattr(response, "generations", None) or []
             first = generations[0][0] if generations and generations[0] else None
@@ -811,10 +918,20 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         parent_run_id: Optional[UUID] = None,
         **kwargs: Any,
     ) -> None:
-        from struct_sdk.core import _safe
+        from struct_sdk.core import _safe, _current_langchain_chat_span
 
         r = self._runs.pop(str(run_id), None)
-        if not r or not r.span:
+        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.
+        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",
+            )
+        if not r.span:
             return
         span = r.span
         _safe(lambda: _record_error(span, error),
@@ -1134,8 +1251,9 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             p = self._runs.get(parent_run_id)
             if p and p.session_id:
                 return p.session_id
-        if metadata and isinstance(metadata.get("thread_id"), str) and metadata["thread_id"]:
-            return metadata["thread_id"]
+        thread_id = _metadata_thread_id(metadata)
+        if thread_id:
+            return thread_id
         from struct_sdk.core import _current_session_id
         ambient = _current_session_id.get(None)
         if ambient:
@@ -1159,8 +1277,8 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         against the nearest-agent-ancestor's session and assign a fresh
         UUID if they match.
         """
-        thread_id = metadata.get("thread_id") if metadata else None
-        if isinstance(thread_id, str) and thread_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
@@ -1186,6 +1304,13 @@ 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."
+        "enrich_token",
     )
 
     def __init__(
@@ -1197,6 +1322,7 @@ class _RunState:
         nearest_agent_session_id: Optional[str],
         nearest_agent_span: Optional[trace.Span],
         kind: str,
+        enrich_token: Any = None,
     ) -> None:
         self.span = span
         self.effective_parent_span = effective_parent_span
@@ -1204,6 +1330,7 @@ class _RunState:
         self.nearest_agent_session_id = nearest_agent_session_id
         self.nearest_agent_span = nearest_agent_span
         self.kind = kind
+        self.enrich_token = enrich_token
 
 
 class _ParentInfo:
@@ -1282,7 +1409,23 @@ def _set_llm_response_attrs(
 
     resp_id = getattr(message, "id", None) or resp_meta.get("id")
     if isinstance(resp_id, str):
-        span.set_attribute("gen_ai.response.id", resp_id)
+        # 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)
 
     if sdk.emit_events and otel_logger:
         _emit_choice_event(otel_logger, message, provider or "langchain", session_id, span)