Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add request-id for steps [LET-6587] (#7349)
Ari Webb4d8d9757aac7
diff --git a/alembic/versions/ee2b43eea55e_add_request_id_to_steps_table.py b/alembic/versions/ee2b43eea55e_add_request_id_to_steps_table.pynew file mode 100644index 000000000..5bf92401c--- /dev/null+++ b/alembic/versions/ee2b43eea55e_add_request_id_to_steps_table.py@@ -0,0 +1,31 @@+"""add request_id to steps table++Revision ID: ee2b43eea55e+Revises: 39577145c45d+Create Date: 2025-12-17 13:48:08.642245++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op++# revision identifiers, used by Alembic.+revision: str = "ee2b43eea55e"+down_revision: Union[str, None] = "39577145c45d"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ # ### commands auto generated by Alembic - please adjust! ###+ op.add_column("steps", sa.Column("request_id", sa.String(), nullable=True))+ # ### end Alembic commands ###+++def downgrade() -> None:+ # ### commands auto generated by Alembic - please adjust! ###+ op.drop_column("steps", "request_id")+ # ### end Alembic commands ###diff --git a/fern/openapi.json b/fern/openapi.jsonindex ad21b85df..762bf34a4 100644--- a/fern/openapi.json+++ b/fern/openapi.json@@ -36560,6 +36560,18 @@"title": "Trace Id","description": "The trace id of the agent step."},+ "request_id": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Request Id",+ "description": "The API request log ID from cloud-api for correlating steps with API requests."+ },"messages": {"items": {"$ref": "#/components/schemas/Message"diff --git a/letta/orm/step.py b/letta/orm/step.pyindex eca32ed56..00f7a37b2 100644--- a/letta/orm/step.py+++ b/letta/orm/step.py@@ -60,6 +60,9 @@ class Step(SqlalchemyBase, ProjectMixin):tags: Mapped[Optional[List]] = mapped_column(JSON, doc="Metadata tags.")tid: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="Transaction ID that processed the step.")trace_id: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="The trace id of the agent step.")+ request_id: Mapped[Optional[str]] = mapped_column(+ None, nullable=True, doc="The API request log ID from cloud-api for correlating steps with API requests."+ )feedback: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="The feedback for this step. Must be either 'positive' or 'negative'.")diff --git a/letta/schemas/step.py b/letta/schemas/step.pyindex a1609b5ec..83126a96a 100644--- a/letta/schemas/step.py+++ b/letta/schemas/step.py@@ -38,6 +38,7 @@ class Step(StepBase):tags: List[str] = Field([], description="Metadata tags.")tid: Optional[str] = Field(None, description="The unique identifier of the transaction that processed this step.")trace_id: Optional[str] = Field(None, description="The trace id of the agent step.")+ request_id: Optional[str] = Field(None, description="The API request log ID from cloud-api for correlating steps with API requests.")messages: List[Message] = Field([],description="The messages generated during this step. Deprecated: use `GET /v1/steps/{step_id}/messages` endpoint instead",diff --git a/letta/server/rest_api/app.py b/letta/server/rest_api/app.pyindex be4b821d2..b40e9c523 100644--- a/letta/server/rest_api/app.py+++ b/letta/server/rest_api/app.py@@ -69,7 +69,7 @@ from letta.server.global_exception_handler import setup_global_exception_handler# NOTE(charles): these are extra routes that are not part of v1 but we still need to mount to pass testsfrom letta.server.rest_api.auth.index import setup_auth_router # TODO: probably remove right?from letta.server.rest_api.interface import StreamingServerInterface-from letta.server.rest_api.middleware import CheckPasswordMiddleware, LoggingMiddleware+from letta.server.rest_api.middleware import CheckPasswordMiddleware, LoggingMiddleware, RequestIdMiddlewarefrom letta.server.rest_api.routers.v1 import ROUTERS as v1_routesfrom letta.server.rest_api.routers.v1.organizations import router as organizations_routerfrom letta.server.rest_api.routers.v1.users import router as users_router # TODO: decide on admin@@ -591,6 +591,10 @@ def create_application() -> "FastAPI":# Add unified logging middleware - enriches log context and logs exceptionsapp.add_middleware(LoggingMiddleware)+ # Add request ID middleware - extracts x-api-request-log-id header and sets it in contextvar+ # This is a pure ASGI middleware to properly propagate contextvars to streaming responses+ app.add_middleware(RequestIdMiddleware)+app.add_middleware(CORSMiddleware,allow_origins=settings.cors_origins,diff --git a/letta/server/rest_api/middleware/__init__.py b/letta/server/rest_api/middleware/__init__.pyindex 50560577b..aa3b20ff1 100644--- a/letta/server/rest_api/middleware/__init__.py+++ b/letta/server/rest_api/middleware/__init__.py@@ -1,4 +1,5 @@from letta.server.rest_api.middleware.check_password import CheckPasswordMiddlewarefrom letta.server.rest_api.middleware.logging import LoggingMiddleware+from letta.server.rest_api.middleware.request_id import RequestIdMiddleware-__all__ = ["CheckPasswordMiddleware", "LoggingMiddleware"]+__all__ = ["CheckPasswordMiddleware", "LoggingMiddleware", "RequestIdMiddleware"]diff --git a/letta/server/rest_api/middleware/request_id.py b/letta/server/rest_api/middleware/request_id.pynew file mode 100644index 000000000..b147ee61c--- /dev/null+++ b/letta/server/rest_api/middleware/request_id.py@@ -0,0 +1,63 @@+"""+Middleware for extracting and propagating API request IDs from cloud-api.++Uses a pure ASGI middleware pattern to properly propagate the request_id+to streaming responses. BaseHTTPMiddleware has a known limitation where+contextvars are not propagated to streaming response generators.+See: https://github.com/encode/starlette/discussions/1729++This middleware:+1. Extracts the x-api-request-log-id header from cloud-api+2. Sets it in the contextvar (for non-streaming code)+3. Stores it in request.state (for streaming responses where contextvars don't propagate)+"""++from contextvars import ContextVar+from typing import Optional++from starlette.requests import Request+from starlette.types import ASGIApp, Receive, Scope, Send++# Contextvar for storing the request ID across async boundaries+request_id_var: ContextVar[Optional[str]] = ContextVar("request_id", default=None)+++def get_request_id() -> Optional[str]:+ """Get the request ID from the current context."""+ return request_id_var.get()+++class RequestIdMiddleware:+ """+ Pure ASGI middleware that extracts and propagates the API request ID.++ The request ID comes from cloud-api via the x-api-request-log-id header+ and is used to correlate steps with API request logs.++ This middleware stores the request_id in:+ - The request_id_var contextvar (works for non-streaming responses)+ - request.state.request_id (works for streaming responses where contextvars may not propagate)+ """++ def __init__(self, app: ASGIApp) -> None:+ self.app = app++ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:+ if scope["type"] != "http":+ await self.app(scope, receive, send)+ return++ # Create a Request object for easier header access+ request = Request(scope)++ # Extract request_id from header+ request_id = request.headers.get("x-api-request-log-id")++ # Set in contextvar (for non-streaming code paths)+ request_id_var.set(request_id)++ # Also store in request.state for streaming responses where contextvars don't propagate+ # This is accessible via request.state.request_id throughout the request lifecycle+ request.state.request_id = request_id++ await self.app(scope, receive, send)diff --git a/letta/services/step_manager.py b/letta/services/step_manager.pyindex cd57bf5f9..64a1e4d38 100644--- a/letta/services/step_manager.py+++ b/letta/services/step_manager.py@@ -21,6 +21,7 @@ from letta.schemas.step import Step as PydanticStepfrom letta.schemas.step_metrics import StepMetrics as PydanticStepMetricsfrom letta.schemas.user import User as PydanticUserfrom letta.server.db import db_registry+from letta.server.rest_api.middleware.request_id import get_request_idfrom letta.services.webhook_service import WebhookServicefrom letta.utils import enforce_typesfrom letta.validators import raise_on_invalid_id@@ -123,6 +124,7 @@ class StepManager:"tags": [],"tid": None,"trace_id": get_trace_id(), # Get the current trace ID+ "request_id": get_request_id(), # Get the API request log ID from cloud-api"project_id": project_id,"status": status if status else StepStatus.PENDING,"error_type": error_type,@@ -182,6 +184,7 @@ class StepManager:"tags": [],"tid": None,"trace_id": get_trace_id(), # Get the current trace ID+ "request_id": get_request_id(), # Get the API request log ID from cloud-api"project_id": project_id,"status": status if status else StepStatus.PENDING,"error_type": error_type,