Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add new steps messages endpoint and deprecate steps.messages field (#2978)
cthomas46b19120d897
diff --git a/fern/openapi-overrides.yml b/fern/openapi-overrides.ymlindex a4d483401..1ddccf02e 100644--- a/fern/openapi-overrides.yml+++ b/fern/openapi-overrides.yml@@ -923,6 +923,12 @@ paths:- steps- tracex-fern-sdk-method-name: retrieve+ /v1/steps/{step_id}/messages:+ get:+ x-fern-sdk-group-name:+ - steps+ - messages+ x-fern-sdk-method-name: list/v1/identities/:get:x-fern-sdk-group-name:diff --git a/fern/openapi.json b/fern/openapi.jsonindex eb281136b..ec8f0c540 100644--- a/fern/openapi.json+++ b/fern/openapi.json@@ -10843,6 +10843,174 @@}}},+ "/v1/steps/{step_id}/messages": {+ "get": {+ "tags": ["steps"],+ "summary": "List Messages For Step",+ "description": "List messages for a given step.",+ "operationId": "list_messages_for_step",+ "parameters": [+ {+ "name": "step_id",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "title": "Step Id"+ }+ },+ {+ "name": "before",+ "in": "query",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "description": "Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order",+ "title": "Before"+ },+ "description": "Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order"+ },+ {+ "name": "after",+ "in": "query",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "description": "Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order",+ "title": "After"+ },+ "description": "Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order"+ },+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "integer"+ },+ {+ "type": "null"+ }+ ],+ "description": "Maximum number of messages to return",+ "default": 100,+ "title": "Limit"+ },+ "description": "Maximum number of messages to return"+ },+ {+ "name": "order",+ "in": "query",+ "required": false,+ "schema": {+ "enum": ["asc", "desc"],+ "type": "string",+ "description": "Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first",+ "default": "asc",+ "title": "Order"+ },+ "description": "Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first"+ },+ {+ "name": "order_by",+ "in": "query",+ "required": false,+ "schema": {+ "const": "created_at",+ "type": "string",+ "description": "Sort by field",+ "default": "created_at",+ "title": "Order By"+ },+ "description": "Sort by field"+ }+ ],+ "responses": {+ "200": {+ "description": "Successful Response",+ "content": {+ "application/json": {+ "schema": {+ "type": "array",+ "items": {+ "oneOf": [+ {+ "$ref": "#/components/schemas/SystemMessage"+ },+ {+ "$ref": "#/components/schemas/UserMessage"+ },+ {+ "$ref": "#/components/schemas/ReasoningMessage"+ },+ {+ "$ref": "#/components/schemas/HiddenReasoningMessage"+ },+ {+ "$ref": "#/components/schemas/ToolCallMessage"+ },+ {+ "$ref": "#/components/schemas/ToolReturnMessage"+ },+ {+ "$ref": "#/components/schemas/AssistantMessage"+ },+ {+ "$ref": "#/components/schemas/ApprovalRequestMessage"+ },+ {+ "$ref": "#/components/schemas/ApprovalResponseMessage"+ }+ ],+ "discriminator": {+ "propertyName": "message_type",+ "mapping": {+ "system_message": "#/components/schemas/SystemMessage",+ "user_message": "#/components/schemas/UserMessage",+ "reasoning_message": "#/components/schemas/ReasoningMessage",+ "hidden_reasoning_message": "#/components/schemas/HiddenReasoningMessage",+ "tool_call_message": "#/components/schemas/ToolCallMessage",+ "tool_return_message": "#/components/schemas/ToolReturnMessage",+ "assistant_message": "#/components/schemas/AssistantMessage",+ "approval_request_message": "#/components/schemas/ApprovalRequestMessage",+ "approval_response_message": "#/components/schemas/ApprovalResponseMessage"+ }+ }+ },+ "title": "Response List Messages For Step"+ }+ }+ }+ },+ "422": {+ "description": "Validation Error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ }+ }+ }+ }+ },"/v1/tags/": {"get": {"tags": ["tag", "admin", "admin"],@@ -17135,8 +17303,7 @@}],"title": "Prompt Template",- "description": "Optional Jinja2 template for generating agent prompt about this tool rule.",- "default": "<tool_rule>\nAfter using {{ tool_name }}, you must use one of these tools: {{ children | join(', ') }}\n</tool_rule>"+ "description": "Optional template string (ignored)."},"children": {"items": {@@ -18118,8 +18285,7 @@}],"title": "Prompt Template",- "description": "Optional Jinja2 template for generating agent prompt about this tool rule.",- "default": "<tool_rule>\n{{ tool_name }} will determine which tool to use next based on its output\n</tool_rule>"+ "description": "Optional template string (ignored)."},"default_child": {"anyOf": [@@ -18350,8 +18516,7 @@}],"title": "Prompt Template",- "description": "Optional Jinja2 template for generating agent prompt about this tool rule.",- "default": "<tool_rule>\n{{ tool_name }} requires continuing your response when called\n</tool_rule>"+ "description": "Optional template string (ignored)."}},"additionalProperties": false,@@ -21743,7 +21908,7 @@}],"title": "Prompt Template",- "description": "Optional Jinja2 template for generating agent prompt about this tool rule. Template can use variables like 'tool_name' and rule-specific attributes."+ "description": "Optional template string (ignored). Rendering uses fast built-in formatting for performance."}},"additionalProperties": false,@@ -23881,8 +24046,7 @@}],"title": "Prompt Template",- "description": "Optional Jinja2 template for generating agent prompt about this tool rule.",- "default": "<tool_rule>\n{{ tool_name }}: at most {{ max_count_limit }} use(s) per response\n</tool_rule>"+ "description": "Optional template string (ignored)."},"max_count_limit": {"type": "integer",@@ -23917,6 +24081,21 @@},"Memory": {"properties": {+ "agent_type": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/AgentType"+ },+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Agent Type",+ "description": "Agent type controlling prompt rendering."+ },"blocks": {"items": {"$ref": "#/components/schemas/Block"@@ -23936,8 +24115,8 @@"prompt_template": {"type": "string","title": "Prompt Template",- "description": "Jinja2 template for compiling memory blocks into a prompt string",- "default": "{% for block in blocks %}<{{ block.label }}>\n<metadata>read_only=\"{{ block.read_only}}\" chars_current=\"{{ block.value|length }}\" chars_limit=\"{{ block.limit }}\"</metadata><value>{{ block.value }}\n</value></{{ block.label }}>\n{% if not loop.last %}\n{% endif %}{% endfor %}"+ "description": "Deprecated. Ignored for performance.",+ "default": ""}},"type": "object",@@ -24878,8 +25057,7 @@}],"title": "Prompt Template",- "description": "Optional Jinja2 template for generating agent prompt about this tool rule.",- "default": "<tool_rule>\n{{ children | join(', ') }} can only be used after {{ tool_name }}\n</tool_rule>"+ "description": "Optional template string (ignored)."},"children": {"items": {@@ -25706,8 +25884,7 @@}],"title": "Prompt Template",- "description": "Optional Jinja2 template for generating agent prompt about this tool rule.",- "default": "<tool_rule>{{ tool_name }} must be called before ending the conversation</tool_rule>"+ "description": "Optional template string (ignored)."}},"additionalProperties": false,@@ -25739,7 +25916,7 @@}],"title": "Prompt Template",- "description": "Optional Jinja2 template for generating agent prompt about this tool rule. Template can use variables like 'tool_name' and rule-specific attributes."+ "description": "Optional template string (ignored). Rendering uses fast built-in formatting for performance."}},"additionalProperties": false,@@ -27154,8 +27331,9 @@},"type": "array","title": "Messages",- "description": "The messages generated during this step.",- "default": []+ "description": "The messages generated during this step. Deprecated: use `GET /v1/steps/{step_id}/messages` endpoint instead",+ "default": [],+ "deprecated": true},"feedback": {"anyOf": [@@ -27638,8 +27816,7 @@}],"title": "Prompt Template",- "description": "Optional Jinja2 template for generating agent prompt about this tool rule.",- "default": "<tool_rule>\n{{ tool_name }} ends your response (yields control) when called\n</tool_rule>"+ "description": "Optional template string (ignored)."}},"additionalProperties": false,diff --git a/letta/schemas/step.py b/letta/schemas/step.pyindex a29bfb8e0..dcd8b4b1a 100644--- a/letta/schemas/step.py+++ b/letta/schemas/step.py@@ -35,7 +35,11 @@ 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.")- messages: List[Message] = Field([], description="The messages generated during this step.")+ messages: List[Message] = Field(+ [],+ description="The messages generated during this step. Deprecated: use `GET /v1/steps/{step_id}/messages` endpoint instead",+ deprecated=True,+ )feedback: Optional[Literal["positive", "negative"]] = Field(None, description="The feedback for this step. Must be either 'positive' or 'negative'.")diff --git a/letta/server/rest_api/routers/v1/steps.py b/letta/server/rest_api/routers/v1/steps.pyindex 1066f5b8c..01cbd7238 100644--- a/letta/server/rest_api/routers/v1/steps.py+++ b/letta/server/rest_api/routers/v1/steps.py@@ -5,6 +5,8 @@ from fastapi import APIRouter, Body, Depends, Header, HTTPException, Queryfrom pydantic import BaseModel, Fieldfrom letta.orm.errors import NoResultFound+from letta.schemas.letta_message import LettaMessageUnion+from letta.schemas.message import Messagefrom letta.schemas.provider_trace import ProviderTracefrom letta.schemas.step import Stepfrom letta.schemas.step_metrics import StepMetrics@@ -138,6 +140,33 @@ async def modify_feedback_for_step(raise HTTPException(status_code=404, detail="Step not found")[email protected]("/{step_id}/messages", response_model=List[LettaMessageUnion], operation_id="list_messages_for_step")+async def list_messages_for_step(+ step_id: str,+ headers: HeaderParams = Depends(get_headers),+ server: SyncServer = Depends(get_letta_server),+ before: Optional[str] = Query(+ None, description="Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order"+ ),+ after: Optional[str] = Query(+ None, description="Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order"+ ),+ limit: Optional[int] = Query(100, description="Maximum number of messages to return"),+ order: Literal["asc", "desc"] = Query(+ "asc", description="Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first"+ ),+ order_by: Literal["created_at"] = Query("created_at", description="Sort by field"),+):+ """+ List messages for a given step.+ """+ actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)+ messages = await server.step_manager.list_step_messages_async(+ step_id=step_id, actor=actor, before=before, after=after, limit=limit, ascending=(order == "asc")+ )+ return Message.to_letta_messages_from_list(messages)++@router.patch("/{step_id}/transaction/{transaction_id}", response_model=Step, operation_id="update_step_transaction_id")async def update_step_transaction_id(step_id: str,diff --git a/letta/services/step_manager.py b/letta/services/step_manager.pyindex 9dd107ce7..ea5656983 100644--- a/letta/services/step_manager.py+++ b/letta/services/step_manager.py@@ -9,12 +9,14 @@ from sqlalchemy.orm import Sessionfrom letta.helpers.singleton import singletonfrom letta.orm.errors import NoResultFoundfrom letta.orm.job import Job as JobModel+from letta.orm.message import Message as MessageModelfrom letta.orm.sqlalchemy_base import AccessTypefrom letta.orm.step import Step as StepModelfrom letta.orm.step_metrics import StepMetrics as StepMetricsModelfrom letta.otel.tracing import get_trace_id, trace_methodfrom letta.schemas.enums import StepStatusfrom letta.schemas.letta_stop_reason import LettaStopReason, StopReasonType+from letta.schemas.message import Message as PydanticMessagefrom letta.schemas.openai.chat_completion_response import UsageStatisticsfrom letta.schemas.step import Step as PydanticStepfrom letta.schemas.step_metrics import StepMetrics as PydanticStepMetrics@@ -237,6 +239,30 @@ class StepManager:await session.commit()return step.to_pydantic()+ @enforce_types+ @trace_method+ async def list_step_messages_async(+ self,+ step_id: str,+ actor: PydanticUser,+ before: str | None = None,+ after: str | None = None,+ limit: int = 100,+ ascending: bool = False,+ ) -> List[PydanticMessage]:+ async with db_registry.async_session() as session:+ messages = MessageModel.list(+ db_session=session,+ before=before,+ after=after,+ ascending=ascending,+ limit=limit,+ actor=actor,+ join_model=StepModel,+ join_conditions=[MessageModel.step.id == step_id],+ )+ return [message.to_pydantic() for message in messages]+@enforce_types@trace_methodasync def update_step_stop_reason(self, actor: PydanticUser, step_id: str, stop_reason: StopReasonType) -> PydanticStep: