Skip to content
This repository was archived by the owner on Nov 11, 2026. It is now read-only.

Commit 41d0594

Browse files
feat(integrations): attribute voice traces via ls_integration metadata (#3144)
#### PR Dependency Tree * **PR #3144** 👈 * **PR #3145** * **PR #3146** * **PR #3153** This tree was auto-generated by [Charcoal](https://github.com/danerwilliams/charcoal)
1 parent 1f72f18 commit 41d0594

18 files changed

Lines changed: 170 additions & 48 deletions

File tree

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
"""Shared helper for resolving an installed package's version.
2+
3+
Integrations stamp ``ls_integration_version`` with the version of the
4+
third-party framework they trace (e.g. ``pipecat-ai``, ``google-adk``,
5+
``openai-agents``) so LangSmith can attribute traces to the integration and
6+
framework version in use. This is the single implementation they all share.
7+
"""
8+
9+
from __future__ import annotations
10+
11+
from functools import cache
12+
from typing import Optional
13+
14+
15+
@cache
16+
def get_package_version(package_name: str) -> Optional[str]:
17+
"""Installed version of ``package_name``, or ``None`` if unresolvable.
18+
19+
Cached — an installed package's version doesn't change at runtime, and this
20+
is called once per trace root. Never raises: a missing package or metadata
21+
just yields ``None``.
22+
"""
23+
try:
24+
from importlib.metadata import version
25+
26+
return version(package_name)
27+
except Exception:
28+
return None

‎python/langsmith/_internal/voice/helpers.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
"""Shared helpers for the Track-B ``EventSession`` adapters.
1+
"""Shared helpers for the voice integration adapters.
22
33
* ``dump_event`` — best-effort conversion of an event object to a plain dict
44
(Pydantic ``model_dump`` → ``dict`` → ``repr`` fallback).
@@ -16,6 +16,8 @@
1616

1717
logger = logging.getLogger(__name__)
1818

19+
__all__ = ["dump_event", "scrub", "observe_safely"]
20+
1921
# Longest string kept on a span before truncating. Transcripts are short; this
2022
# only ever trims an unexpectedly large blob.
2123
MAX_STR = 2000

‎python/langsmith/_internal/voice/session.py‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -430,6 +430,8 @@ def start_session(
430430
max_audio_seconds: Optional[float] = None,
431431
client: Optional[Client] = None,
432432
replicas: Optional[Sequence[WriteReplica]] = None,
433+
integration: str,
434+
integration_version: Optional[str] = None,
433435
) -> EventSession:
434436
"""Create and post the conversation root span, returning an ``EventSession``.
435437
@@ -447,9 +449,24 @@ def start_session(
447449
``max_audio_seconds`` caps how much audio per channel is retained for the
448450
stereo WAV, guarding memory on long-running sessions; ``None`` keeps all
449451
audio. It is converted to a per-channel byte budget at PCM16 (2 bytes/sample).
452+
453+
``integration`` / ``integration_version`` stamp ``ls_integration`` and
454+
``ls_integration_version`` on the root (the convention the batch integrations
455+
use) so LangSmith can attribute the trace to a specific integration and the
456+
framework version in use. Set authoritatively — a caller cannot shadow them
457+
via ``metadata``. ``integration_version`` may be ``None`` when the framework
458+
version can't be resolved.
450459
"""
451460
# Mark the root as an audio-modality run (these are voice conversations).
452-
md = {"ls_modality": "audio", "thread_id": thread_id, **(metadata or {})}
461+
# Integration attribution comes after ``**metadata`` so it wins — a caller
462+
# can't shadow ls_integration via their own metadata.
463+
md = {
464+
"ls_modality": "audio",
465+
"thread_id": thread_id,
466+
**(metadata or {}),
467+
"ls_integration": integration,
468+
"ls_integration_version": integration_version,
469+
}
453470
# ``RunTree.session_name`` (aliased ``project_name``) is a ``str`` with a
454471
# default factory; passing ``None`` explicitly fails validation, so only
455472
# forward it when set and let the SDK resolve ``LANGSMITH_PROJECT`` otherwise.

‎python/langsmith/integrations/claude_agent_sdk/_client.py‎

Lines changed: 2 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@
55
import weakref
66
from collections.abc import AsyncGenerator, AsyncIterable
77
from datetime import datetime, timezone
8-
from functools import cache
98
from typing import Any, Optional
109

1110
from langsmith._internal import _context
11+
from langsmith._internal._package_version import get_package_version
1212
from langsmith.run_helpers import get_current_run_tree, trace
1313

1414
from ._config import get_tracing_config
@@ -44,16 +44,6 @@
4444
TRACE_CHAIN_NAME = "claude.conversation"
4545

4646

47-
@cache
48-
def _get_package_version(package_name: str) -> str | None:
49-
try:
50-
from importlib.metadata import version
51-
52-
return version(package_name)
53-
except Exception:
54-
return None
55-
56-
5747
class TurnLifecycle:
5848
"""Track ongoing model runs so consecutive messages are recorded correctly.
5949
@@ -495,7 +485,7 @@ async def _traced_receive_response(self: Any) -> AsyncGenerator[Any, None]:
495485
trace_inputs: dict[str, Any] = {}
496486
trace_metadata: dict[str, Any] = {
497487
"ls_integration": "claude-agent-sdk",
498-
"ls_integration_version": _get_package_version("claude_agent_sdk"),
488+
"ls_integration_version": get_package_version("claude_agent_sdk"),
499489
}
500490

501491
awaiting_streamed_input = self._ls_streamed_input is not None

‎python/langsmith/integrations/google_adk/_client.py‎

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@
88
from collections.abc import AsyncGenerator
99
from contextlib import aclosing
1010
from datetime import datetime, timezone
11-
from functools import cache
1211
from typing import Any, Optional
1312

13+
from langsmith._internal._package_version import get_package_version
1414
from langsmith.run_helpers import get_current_run_tree, set_tracing_parent, trace
1515

1616
from ._config import get_tracing_config
@@ -65,16 +65,6 @@ def _get_ls_provider() -> str:
6565
TRACE_CHAIN_NAME = "google_adk.session"
6666

6767

68-
@cache
69-
def _get_package_version(package_name: str) -> str | None:
70-
try:
71-
from importlib.metadata import version
72-
73-
return version(package_name)
74-
except Exception:
75-
return None
76-
77-
7868
# Attribute name used to bridge the root run from Runner.run (sync) into the
7969
# background thread where Runner.run_async executes. Runner.run spins up a
8070
# new thread for its internal asyncio event loop, so context vars don't
@@ -135,7 +125,7 @@ def wrap_runner_run(wrapped: Any, instance: Any, args: Any, kwargs: Any) -> Any:
135125
trace_metadata: dict[str, Any] = {
136126
"ls_provider": _get_ls_provider(),
137127
"ls_integration": "google-adk",
138-
"ls_integration_version": _get_package_version("google-adk"),
128+
"ls_integration_version": get_package_version("google-adk"),
139129
**(config.get("metadata") or {}),
140130
}
141131
if app_name := getattr(instance, "app_name", None):
@@ -204,7 +194,7 @@ async def wrap_runner_run_async(
204194
trace_metadata: dict[str, Any] = {
205195
"ls_provider": _get_ls_provider(),
206196
"ls_integration": "google-adk",
207-
"ls_integration_version": _get_package_version("google-adk"),
197+
"ls_integration_version": get_package_version("google-adk"),
208198
**(config.get("metadata") or {}),
209199
}
210200
if app_name := getattr(instance, "app_name", None):

‎python/langsmith/integrations/google_adk_live/_plugin.py‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,12 @@
4848

4949
from langsmith import RunTree
5050
from langsmith._internal._beta_decorator import warn_beta
51-
from langsmith._internal.voice.helpers import dump_event, observe_safely, scrub
51+
from langsmith._internal._package_version import get_package_version
52+
from langsmith._internal.voice.helpers import (
53+
dump_event,
54+
observe_safely,
55+
scrub,
56+
)
5257
from langsmith._internal.voice.session import EventSession, start_session
5358

5459
if TYPE_CHECKING:
@@ -452,6 +457,8 @@ async def before_run_callback(self, *, invocation_context: Any) -> None:
452457
max_audio_seconds=self._max_audio_seconds,
453458
client=self._client,
454459
replicas=self._replicas,
460+
integration="google-adk-live",
461+
integration_version=get_package_version("google-adk"),
455462
)
456463
key = self._session_key(invocation_context)
457464
with self._lock:

‎python/langsmith/integrations/livekit/processor.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@
6565

6666
from cachetools import TTLCache
6767

68+
from langsmith._internal._package_version import get_package_version
6869
from langsmith._internal.voice.base_span_processor import (
6970
BaseLangSmithSpanProcessor,
7071
TranslatedSpan,
@@ -472,6 +473,12 @@ def _handle_root(self, tspan: TranslatedSpan, trace_id: str) -> None:
472473
self._set_kind(tspan, "chain")
473474
tspan.attributes["langsmith.root_span"] = True
474475
tspan.attributes["langsmith.metadata.ls_modality"] = "audio"
476+
tspan.attributes["langsmith.metadata.ls_integration"] = "livekit"
477+
# "" not None: OTel span attributes reject a null value (unlike the
478+
# RunTree metadata path); livekit-agents is a hard dep, so ~always set.
479+
tspan.attributes["langsmith.metadata.ls_integration_version"] = (
480+
get_package_version("livekit-agents") or ""
481+
)
475482

476483
thread = tspan.attributes.get("langsmith.metadata.thread_id")
477484
if thread is not None:

‎python/langsmith/integrations/openai_agents_sdk/_openai_agents.py‎

Lines changed: 2 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
import logging
22
import weakref
33
from datetime import datetime
4-
from functools import cache
54
from typing import Optional
65

76
from langsmith import run_trees as rt
87
from langsmith._internal import _context
8+
from langsmith._internal._package_version import get_package_version
99
from langsmith.run_helpers import get_current_run_tree
1010

1111
try:
@@ -93,16 +93,6 @@ def __init__(self, *args, **kwargs):
9393
logger = logging.getLogger(__name__)
9494

9595

96-
@cache
97-
def _get_package_version(package_name: str) -> str | None:
98-
try:
99-
from importlib.metadata import version
100-
101-
return version(package_name)
102-
except Exception:
103-
return None
104-
105-
10696
if HAVE_AGENTS:
10797

10898
class OpenAIAgentsTracingProcessor(tracing.TracingProcessor): # type: ignore[no-redef]
@@ -202,7 +192,7 @@ def on_trace_start(self, trace: tracing.Trace) -> None:
202192
"metadata": {
203193
**(self._metadata or {}),
204194
"ls_integration": "openai-agents-sdk",
205-
"ls_integration_version": _get_package_version("openai-agents"),
195+
"ls_integration_version": get_package_version("openai-agents"),
206196
"ls_agent_type": "root",
207197
}
208198
}

‎python/langsmith/integrations/openai_realtime/_connection.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
import uuid
3131
from typing import TYPE_CHECKING, Any, Callable, Optional
3232

33+
from langsmith._internal._package_version import get_package_version
3334
from langsmith._internal._usage import _create_usage_metadata
3435
from langsmith._internal.voice.helpers import observe_safely
3536
from langsmith._internal.voice.session import EventSession, start_session
@@ -409,6 +410,8 @@ async def __aenter__(self) -> _TracedRealtimeConnection:
409410
max_audio_seconds=self._max_audio_seconds,
410411
client=self._client,
411412
replicas=self._replicas,
413+
integration="openai-realtime",
414+
integration_version=get_package_version("openai"),
412415
)
413416
self._ctx = tracing_context(
414417
metadata={"thread_id": self._thread_id},

‎python/langsmith/integrations/openai_realtime/_session.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
import uuid
3737
from typing import TYPE_CHECKING, Any, Callable, Optional
3838

39+
from langsmith._internal._package_version import get_package_version
3940
from langsmith._internal.voice.helpers import observe_safely
4041
from langsmith._internal.voice.session import EventSession, start_session
4142
from langsmith.run_helpers import tracing_context
@@ -501,6 +502,8 @@ async def __aenter__(self) -> _TracedRealtimeSession:
501502
max_audio_seconds=self._max_audio_seconds,
502503
client=self._client,
503504
replicas=self._replicas,
505+
integration="openai-agents-realtime",
506+
integration_version=get_package_version("openai-agents"),
504507
)
505508
self._trace = trace
506509
ctx = tracing_context(

0 commit comments

Comments
 (0)