langgraph-api 0.5.4__py3-none-any.whl → 0.7.3__py3-none-any.whl

langgraph_api/metadata.py

@@ -14,6 +14,7 @@ from langgraph_api.config import (
     LANGGRAPH_CLOUD_LICENSE_KEY,
     LANGSMITH_AUTH_ENDPOINT,
     LANGSMITH_CONTROL_PLANE_API_KEY,
+    LANGSMITH_LICENSE_REQUIRED_CLAIMS,
     USES_CUSTOM_APP,
     USES_CUSTOM_AUTH,
     USES_INDEXING,
@@ -123,6 +124,9 @@ async def metadata_loop() -> None:
     except ImportError:
         __version__ = None
     if not LANGGRAPH_CLOUD_LICENSE_KEY and not LANGSMITH_CONTROL_PLANE_API_KEY:
+        logger.info(
+            "No license key or control plane API key set, skipping metadata loop"
+        )
         return
     lg_version = langgraph.version.__version__
 
@@ -134,7 +138,21 @@ async def metadata_loop() -> None:
         logger.info("Running in air-gapped mode, skipping metadata loop")
         return
 
-    logger.info("Starting metadata loop")
+    # TODO: This is a temporary "hack". A user could inadvertently include
+    # 'agent_builder_enabled' in LANGSMITH_LICENSE_REQUIRED_CLAIMS for a
+    # non-Agent Builder self-hosted deployment. If the 'agent_builder_enabled'
+    # entitlement is enabled, then this would bypass the metadata loop.
+    #
+    # If the 'agent_builder_enabled' entitlement is disabled, then this is ok
+    # because the license key validation would fail and the app would not start.
+    if (
+        LANGGRAPH_CLOUD_LICENSE_KEY
+        and "agent_builder_enabled" in LANGSMITH_LICENSE_REQUIRED_CLAIMS
+    ):
+        logger.info("Skipping metadata loop for self-hosted Agent Builder")
+        return
+
+    logger.info("Starting metadata loop", endpoint=LANGCHAIN_METADATA_ENDPOINT)
 
     global RUN_COUNTER, NODE_COUNTER, FROM_TIMESTAMP
     base_tags = _ensure_strings(
@@ -200,7 +218,11 @@ async def metadata_loop() -> None:
                     body=orjson.dumps(beacon_payload),
                     headers={"Content-Type": "application/json"},
                 )
-                await logger.ainfo("Successfully submitted metadata to beacon endpoint")
+                await logger.ainfo(
+                    "Successfully submitted metadata to beacon endpoint",
+                    n_runs=runs,
+                    n_nodes=nodes,
+                )
             except Exception as e:
                 submissions_failed.append("beacon")
                 await logger.awarning(
@@ -221,7 +243,11 @@ async def metadata_loop() -> None:
                     body=orjson.dumps(langchain_payload),
                     headers={"Content-Type": "application/json"},
                 )
-                logger.info("Successfully submitted metadata to LangSmith instance")
+                logger.info(
+                    "Successfully submitted metadata to LangSmith instance",
+                    n_runs=runs,
+                    n_nodes=nodes,
+                )
             except Exception as e:
                 submissions_failed.append("langchain")
                 await logger.awarning(

langgraph_api/middleware/http_logger.py

@@ -97,7 +97,7 @@ class AccessLoggerMiddleware:
                 path=path,
                 status=status,
                 latency_ms=latency,
-                route=route,
+                route=str(route),
                 path_params=scope.get("path_params"),
                 query_string=qs.decode() if qs else "",
                 proto=scope.get("http_version"),

langgraph_api/middleware/private_network.py

@@ -25,19 +25,19 @@ class PrivateNetworkMiddleware(BaseHTTPMiddleware):
     A web browser determines whether a network is private based on IP address ranges
     and local networking conditions. Typically, it checks:
 
-    IP Address Range – If the website is hosted on an IP within private address
+    IP Address Range - If the website is hosted on an IP within private address
     ranges (RFC 1918):
 
-    10.0.0.0 – 10.255.255.255
-    172.16.0.0 – 172.31.255.255
-    192.168.0.0 – 192.168.255.255
+    10.0.0.0 - 10.255.255.255
+    172.16.0.0 - 172.31.255.255
+    192.168.0.0 - 192.168.255.255
     127.0.0.1 (loopback)
-    Localhost and Hostname – Domains like localhost or .local are assumed to be private.
+    Localhost and Hostname - Domains like localhost or .local are assumed to be private.
 
-    Network Context – The browser may check if the device is connected
+    Network Context - The browser may check if the device is connected
     to a local network (e.g., corporate or home Wi-Fi) rather than the public internet.
 
-    CORS and Private Network Access (PNA) – Modern browsers implement restrictions
+    CORS and Private Network Access (PNA) - Modern browsers implement restrictions
     where resources on private networks require explicit permission (via CORS headers)
     when accessed from a public site.
     """

langgraph_api/models/run.py

@@ -3,15 +3,18 @@ import contextlib
 import time
 import uuid
 from collections.abc import Mapping, Sequence
-from typing import Any, NamedTuple, cast
+from typing import TYPE_CHECKING, Any, NamedTuple, cast
 from uuid import UUID
 
 import structlog
-from starlette.authentication import BaseUser
 from starlette.exceptions import HTTPException
 from typing_extensions import TypedDict
 
+from langgraph_api.encryption.middleware import encrypt_request
+from langgraph_api.feature_flags import FF_USE_CORE_API
 from langgraph_api.graph import GRAPHS, get_assistant_id
+from langgraph_api.grpc.ops import Runs as GrpcRuns
+from langgraph_api.otel_context import inject_current_trace_context
 from langgraph_api.schema import (
     All,
     Config,
@@ -24,11 +27,17 @@ from langgraph_api.schema import (
     RunCommand,
     StreamMode,
 )
-from langgraph_api.utils import AsyncConnectionProto, get_auth_ctx
+from langgraph_api.utils import AsyncConnectionProto, get_auth_ctx, get_user_id
 from langgraph_api.utils.headers import get_configurable_headers
 from langgraph_api.utils.uuids import uuid7
+from langgraph_api.webhook import validate_webhook_url_or_raise
 from langgraph_runtime.ops import Runs
 
+CrudRuns = GrpcRuns if FF_USE_CORE_API else Runs
+
+if TYPE_CHECKING:
+    from starlette.authentication import BaseUser
+
 logger = structlog.stdlib.get_logger(__name__)
 
 
@@ -82,13 +91,13 @@ class RunCreateDict(TypedDict):
     stream_mode: list[StreamMode] | StreamMode
     """One or more of "values", "messages", "updates" or "events".
     - "values": Stream the thread state any time it changes.
-    - "messages": Stream chat messages from thread state and calls to chat models, 
+    - "messages": Stream chat messages from thread state and calls to chat models,
       token-by-token where possible.
     - "updates": Stream the state updates returned by each node.
     - "events": Stream all events produced by sub-runs (eg. nodes, LLMs, etc.).
     - "custom": Stream custom events produced by your nodes.
-    
-    Note: __interrupt__ events are always included in the updates stream, even when "updates" 
+
+    Note: __interrupt__ events are always included in the updates stream, even when "updates"
     is not explicitly requested, to ensure interrupt events are always visible.
     """
     stream_subgraphs: bool | None
@@ -166,18 +175,6 @@ def assign_defaults(
     return stream_mode, multitask_strategy, prevent_insert_if_inflight
 
 
-def get_user_id(user: BaseUser | None) -> str | None:
-    if user is None:
-        return None
-    try:
-        return user.identity
-    except NotImplementedError:
-        try:
-            return user.display_name
-        except NotImplementedError:
-            pass
-
-
 async def create_valid_run(
     conn: AsyncConnectionProto,
     thread_id: str | None,
@@ -238,10 +235,12 @@ async def create_valid_run(
     if checkpoint := payload.get("checkpoint"):
         configurable.update(checkpoint)
     configurable.update(get_configurable_headers(headers))
+    inject_current_trace_context(configurable)
     ctx = get_auth_ctx()
     if ctx:
-        user = cast(BaseUser | None, ctx.user)
+        user = cast("BaseUser | None", ctx.user)
         user_id = get_user_id(user)
+        # Store user as-is; encryption middleware will serialize if needed
         configurable["langgraph_auth_user"] = user
         configurable["langgraph_auth_user_id"] = user_id
         configurable["langgraph_auth_permissions"] = ctx.permissions
@@ -254,8 +253,10 @@ async def create_valid_run(
         configurable["__langsmith_example_id__"] = ls_tracing.get("example_id")
     if request_start_time:
         configurable["__request_start_time_ms__"] = request_start_time
-    after_seconds = cast(int, payload.get("after_seconds", 0))
+    after_seconds = cast("int", payload.get("after_seconds", 0))
     configurable["__after_seconds__"] = after_seconds
+    # Note: encryption context is injected by encrypt_request → encrypt_json_if_needed
+    # as the __encryption_context__ marker. Worker reads it before decryption.
     put_time_start = time.time()
     if_not_exists = payload.get("if_not_exists", "reject")
 
@@ -264,14 +265,31 @@ async def create_valid_run(
         checkpoint_during = payload.get("checkpoint_during")
         durability = "async" if checkpoint_during in (None, True) else "exit"
 
-    run_coro = Runs.put(
-        conn,
-        assistant_id,
+    if webhook := payload.get("webhook"):
+        await validate_webhook_url_or_raise(str(webhook))
+
+    # We can't pass payload directly because config and context have
+    # been modified above (with auth context, checkpoint info, etc.)
+    encrypted = await encrypt_request(
         {
+            "metadata": payload.get("metadata"),
             "input": payload.get("input"),
-            "command": payload.get("command"),
             "config": config,
             "context": context,
+            "command": payload.get("command"),
+        },
+        "run",
+        ["metadata", "input", "config", "context", "command"],
+    )
+
+    run_coro = CrudRuns.put(
+        conn,
+        assistant_id,
+        {
+            "input": encrypted.get("input"),
+            "command": encrypted.get("command"),
+            "config": encrypted.get("config"),
+            "context": encrypted.get("context"),
             "stream_mode": stream_mode,
             "interrupt_before": payload.get("interrupt_before"),
             "interrupt_after": payload.get("interrupt_after"),
@@ -283,7 +301,7 @@ async def create_valid_run(
             "checkpoint_during": payload.get("checkpoint_during", True),
             "durability": durability,
         },
-        metadata=payload.get("metadata"),
+        metadata=encrypted.get("metadata"),
         status="pending",
         user_id=user_id,
         thread_id=thread_id_,
@@ -332,7 +350,7 @@ async def create_valid_run(
         if multitask_strategy in ("interrupt", "rollback") and inflight_runs:
             with contextlib.suppress(HTTPException):
                 # if we can't find the inflight runs again, we can proceeed
-                await Runs.cancel(
+                await CrudRuns.cancel(
                     conn,
                     [run["run_id"] for run in inflight_runs],
                     thread_id=thread_id_,

langgraph_api/otel_context.py

@@ -0,0 +1,205 @@
+"""OTEL trace context propagation utilities.
+
+Provides helpers for extracting, storing, and restoring W3C Trace Context
+across the API-to-worker boundary in distributed LangGraph deployments.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from langgraph_api import __version__, config
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Mapping
+
+    from opentelemetry.trace import Tracer
+
+logger = structlog.stdlib.get_logger(__name__)
+
+# Constants for storing trace context in configurable
+OTEL_TRACEPARENT_KEY = "__otel_traceparent__"
+OTEL_TRACESTATE_KEY = "__otel_tracestate__"
+OTEL_TRACER_NAME = "langsmith_agent_server"
+OTEL_RUN_ID_ATTR_NAME = "langsmith.run_id"
+OTEL_THREAD_ID_ATTR_NAME = "langsmith.thread_id"
+
+# Cached instances (initialized lazily, once)
+_propagator: Any = None
+_tracer: Any = None
+_otel_available: bool | None = None
+
+
+def _check_otel_available() -> bool:
+    """Check if OpenTelemetry is available. Cached after first call."""
+    global _otel_available
+    if _otel_available is None:
+        try:
+            from opentelemetry import trace  # noqa: F401
+            from opentelemetry.trace.propagation.tracecontext import (
+                TraceContextTextMapPropagator,  # noqa: F401
+            )
+
+            _otel_available = True
+        except ImportError:
+            _otel_available = False
+    return _otel_available
+
+
+def _get_propagator() -> Any:
+    """Get cached W3C TraceContext propagator."""
+    global _propagator
+    if _propagator is None:
+        from opentelemetry.trace.propagation.tracecontext import (
+            TraceContextTextMapPropagator,
+        )
+
+        _propagator = TraceContextTextMapPropagator()
+    return _propagator
+
+
+def _get_tracer() -> Tracer:
+    """Get cached tracer for worker spans."""
+    global _tracer
+    if _tracer is None:
+        from opentelemetry import trace
+
+        _tracer = trace.get_tracer(
+            OTEL_TRACER_NAME, instrumenting_library_version=__version__
+        )
+    return _tracer
+
+
+def extract_otel_headers_to_configurable(
+    headers: Mapping[str, str],
+    configurable: dict[str, Any],
+) -> None:
+    """Extract traceparent/tracestate from HTTP headers into configurable dict.
+
+    Only extracts if OTEL is enabled. No-op otherwise.
+
+    Args:
+        headers: HTTP headers from the incoming request
+        configurable: The configurable dict to store trace context in
+    """
+    if not config.OTEL_ENABLED:
+        return
+
+    if traceparent := headers.get("traceparent"):
+        configurable[OTEL_TRACEPARENT_KEY] = traceparent
+    if tracestate := headers.get("tracestate"):
+        configurable[OTEL_TRACESTATE_KEY] = tracestate
+
+
+def inject_current_trace_context(configurable: dict[str, Any]) -> None:
+    """Inject current OTEL trace context into configurable for worker propagation.
+
+    This captures the active span context (e.g., from Starlette auto-instrumentation)
+    and stores it in the configurable dict so workers can restore it and create
+    child spans under the API request span.
+
+    Args:
+        configurable: The configurable dict to store trace context in
+    """
+    if not config.OTEL_ENABLED or not _check_otel_available():
+        return
+
+    try:
+        from opentelemetry import trace
+
+        span = trace.get_current_span()
+        if not span.is_recording():
+            return
+
+        carrier: dict[str, str] = {}
+        _get_propagator().inject(carrier)
+
+        if traceparent := carrier.get("traceparent"):
+            configurable[OTEL_TRACEPARENT_KEY] = traceparent
+        if tracestate := carrier.get("tracestate"):
+            configurable[OTEL_TRACESTATE_KEY] = tracestate
+    except Exception:
+        # Never fail - tracing issues shouldn't break functionality
+        pass
+
+
+@contextmanager
+def restore_otel_trace_context(
+    configurable: dict[str, Any],
+    run_id: str | None = None,
+    thread_id: str | None = None,
+) -> Generator[None, None, None]:
+    """Restore OTEL trace context and create child span for worker execution.
+
+    Creates a child span under the original API request span, ensuring
+    distributed traces are connected across the API-to-worker boundary.
+
+    Yields:
+        None - execution continues within the restored trace context
+
+    Note:
+        - No-ops if OTEL is disabled or unavailable
+        - Never raises - tracing failures won't break run execution
+    """
+    if not config.OTEL_ENABLED or not _check_otel_available():
+        yield
+        return
+
+    traceparent = configurable.get(OTEL_TRACEPARENT_KEY)
+    if not traceparent:
+        yield
+        return
+
+    try:
+        from opentelemetry import trace
+
+        # Build carrier dict for W3C propagator
+        carrier: dict[str, str] = {"traceparent": traceparent}
+        if tracestate := configurable.get(OTEL_TRACESTATE_KEY):
+            carrier["tracestate"] = tracestate
+
+        # Extract context from carrier
+        ctx = _get_propagator().extract(carrier=carrier)
+
+        with _get_tracer().start_as_current_span(
+            "worker.stream_run",
+            context=ctx,
+            kind=trace.SpanKind.CONSUMER,
+        ) as span:
+            if run_id:
+                span.set_attribute(OTEL_RUN_ID_ATTR_NAME, run_id)
+            if thread_id:
+                span.set_attribute(OTEL_THREAD_ID_ATTR_NAME, thread_id)
+
+            yield
+    except Exception:
+        logger.debug("Failed to restore OTEL trace context", exc_info=True)
+        yield
+
+
+def inject_otel_headers() -> dict[str, str]:
+    """Inject current trace context into headers for outgoing HTTP requests.
+
+    Used to propagate trace context to webhooks.
+
+    Returns:
+        Dict with traceparent/tracestate headers if in active trace, else empty.
+    """
+    if not config.OTEL_ENABLED or not _check_otel_available():
+        return {}
+
+    try:
+        from opentelemetry import trace
+
+        span = trace.get_current_span()
+        if not span.is_recording():
+            return {}
+
+        carrier: dict[str, str] = {}
+        _get_propagator().inject(carrier)
+        return carrier
+    except Exception:
+        return {}

langgraph_api/patch.py

@@ -14,7 +14,7 @@ to recognize bytearrays and memoryviews as bytes-like objects.
 def Response_render(self, content: Any) -> bytes:
     if content is None:
         return b""
-    if isinstance(content, (bytes, bytearray, memoryview)):  # noqa: UP038
+    if isinstance(content, (bytes, bytearray, memoryview)):
         return content
     return content.encode(self.charset)  # type: ignore
 
@@ -34,7 +34,7 @@ async def StreamingResponse_stream_response(self, send: Send) -> None:
             chunk = chunk.buf
         if isinstance(chunk, dict):
             chunk = json_dumpb(chunk)
-        if not isinstance(chunk, (bytes, bytearray, memoryview)):  # noqa: UP038
+        if not isinstance(chunk, (bytes, bytearray, memoryview)):
             chunk = chunk.encode(self.charset)
         await send({"type": "http.response.body", "body": chunk, "more_body": True})
 

langgraph_api/queue_entrypoint.py

@@ -1,29 +1,26 @@
-# ruff: noqa: E402
 import os
 
-from langgraph_api.api.meta import METRICS_FORMATS
-
 if not (
     (disable_truststore := os.getenv("DISABLE_TRUSTSTORE"))
     and disable_truststore.lower() == "true"
 ):
-    import truststore  # noqa: F401
+    import truststore
 
-    truststore.inject_into_ssl()  # noqa: F401
+    truststore.inject_into_ssl()
 
 import asyncio
+import functools
 import json
 import logging.config
 import pathlib
 import signal
 import socket
-from contextlib import asynccontextmanager
 
 import structlog
 
 from langgraph_api.utils.errors import GraphLoadError, HealthServerStartupError
 from langgraph_runtime import lifespan
-from langgraph_runtime.database import pool_stats
+from langgraph_runtime.database import healthcheck, pool_stats
 from langgraph_runtime.metrics import get_metrics
 
 logger = structlog.stdlib.get_logger(__name__)
@@ -43,12 +40,17 @@ async def health_and_metrics_server():
     from starlette.applications import Starlette
     from starlette.requests import Request
     from starlette.responses import JSONResponse, PlainTextResponse
-    from starlette.routing import Route
+    from starlette.routing import Mount, Route
+
+    from langgraph_api import config as lc_config
+    from langgraph_api.api.meta import METRICS_FORMATS
 
     port = int(os.getenv("PORT", "8080"))
     host = os.getenv("LANGGRAPH_SERVER_HOST", "0.0.0.0")
 
     async def health_endpoint(request):
+        # if db or redis is not healthy, this will raise an exception
+        await healthcheck()
         return JSONResponse({"status": "ok"})
 
     async def metrics_endpoint(request: Request):
@@ -100,12 +102,17 @@ async def health_and_metrics_server():
                 media_type="text/plain; version=0.0.4; charset=utf-8",
             )
 
-    app = Starlette(
-        routes=[
-            Route("/ok", health_endpoint),
-            Route("/metrics", metrics_endpoint),
-        ]
-    )
+    routes = [
+        Route("/ok", health_endpoint),
+        Route("/metrics", metrics_endpoint),
+    ]
+    app = Starlette(routes=routes)
+    if lc_config.MOUNT_PREFIX:
+        app = Starlette(
+            routes=[*routes, Mount(lc_config.MOUNT_PREFIX, app=app)],
+            lifespan=app.router.lifespan_context,
+            exception_handlers=app.exception_handlers,
+        )
 
     try:
         _ensure_port_available(host, port)
@@ -163,33 +170,25 @@ async def entrypoint(
     cancel_event: asyncio.Event | None = None,
 ):
     from langgraph_api import logging as lg_logging
+    from langgraph_api import timing
     from langgraph_api.api import user_router
+    from langgraph_api.server import app
 
     lg_logging.set_logging_context({"entrypoint": entrypoint_name})
     tasks: set[asyncio.Task] = set()
-
-    original_lifespan = user_router.router.lifespan_context if user_router else None
-
-    @asynccontextmanager
-    async def combined_lifespan(
-        app, with_cron_scheduler=False, grpc_port=None, taskset=None
-    ):
-        async with lifespan.lifespan(
-            app,
-            with_cron_scheduler=with_cron_scheduler,
+    user_lifespan = None if user_router is None else user_router.router.lifespan_context
+    wrapped_lifespan = timing.combine_lifespans(
+        functools.partial(
+            lifespan.lifespan,
+            with_cron_scheduler=False,
             grpc_port=grpc_port,
-            taskset=taskset,
+            taskset=tasks,
             cancel_event=cancel_event,
-        ):
-            if original_lifespan:
-                async with original_lifespan(app):
-                    yield
-            else:
-                yield
-
-    async with combined_lifespan(
-        None, with_cron_scheduler=False, grpc_port=grpc_port, taskset=tasks
-    ):
+        ),
+        user_lifespan,
+    )
+
+    async with wrapped_lifespan(app):
         tasks.add(asyncio.create_task(health_and_metrics_server()))
         await asyncio.gather(*tasks)
 

langgraph_api/route.py

@@ -4,6 +4,7 @@ import typing
 
 import jsonschema_rs
 import orjson
+import structlog
 from starlette._exception_handler import wrap_app_handling_exceptions
 from starlette._utils import is_async_callable
 from starlette.concurrency import run_in_threadpool
@@ -18,6 +19,7 @@ from langgraph_api import config
 from langgraph_api.serde import json_dumpb
 from langgraph_api.utils import get_auth_ctx, with_user
 
+logger = structlog.getLogger(__name__)
 SchemaType = (
     jsonschema_rs.Draft4Validator
     | jsonschema_rs.Draft6Validator
@@ -44,7 +46,7 @@ def api_request_response(
                 response: ASGIApp = await func(request)
             else:
                 response = await run_in_threadpool(
-                    typing.cast(typing.Callable[[Request], ASGIApp], func), request
+                    typing.cast("typing.Callable[[Request], ASGIApp]", func), request
                 )
             await response(scope, receive, send)
 
@@ -145,6 +147,8 @@ class ApiRoute(Route):
 
         scope["route"] = self.path
         set_logging_context({"path": self.path, "method": scope.get("method")})
+        route_pattern = f"{scope.get('root_path', '')}{self.path}"
+        _name_otel_span(scope, route_pattern)
         ctx = get_auth_ctx()
         if ctx:
             user, auth = ctx.user, ctx.permissions
@@ -152,3 +156,31 @@ class ApiRoute(Route):
             user, auth = scope.get("user"), scope.get("auth")
         async with with_user(user, auth):
             return await super().handle(scope, receive, send)
+
+
+def _name_otel_span(scope: Scope, route_pattern: str):
+    """Best-effort rename of the active OTEL server span to include the route.
+
+    - No-ops if OTEL is disabled or OTEL libs are unavailable.
+    - Sets span name to "METHOD /templated/path" and attaches http.route.
+    - Never raises; safe for hot path usage.
+    """
+    if not config.OTEL_ENABLED:
+        return
+    try:
+        from opentelemetry.trace import get_current_span
+
+        span = get_current_span()
+        if span.is_recording():
+            method = scope.get("method", "") or ""
+            try:
+                span.update_name(f"{method} {route_pattern}")
+            except Exception:
+                logger.error("Failed to update OTEL span name", exc_info=True)
+                pass
+            try:
+                span.set_attribute("http.route", route_pattern)
+            except Exception:
+                logger.error("Failed to update OTEL span attributes", exc_info=True)
+    except Exception:
+        logger.error("Failed to update OTEL span", exc_info=True)