Skip to content

armgit / letta

Public Imported from GitHub
0

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.yml
index a4d483401..1ddccf02e 100644
--- a/fern/openapi-overrides.yml
+++ b/fern/openapi-overrides.yml
@@ -923,6 +923,12 @@ paths:
- steps
- trace
x-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.json
index 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.py
index 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.py
index 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, Query
from pydantic import BaseModel, Field
from letta.orm.errors import NoResultFound
+from letta.schemas.letta_message import LettaMessageUnion
+from letta.schemas.message import Message
from letta.schemas.provider_trace import ProviderTrace
from letta.schemas.step import Step
from 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.py
index 9dd107ce7..ea5656983 100644
--- a/letta/services/step_manager.py
+++ b/letta/services/step_manager.py
@@ -9,12 +9,14 @@ from sqlalchemy.orm import Session
from letta.helpers.singleton import singleton
from letta.orm.errors import NoResultFound
from letta.orm.job import Job as JobModel
+from letta.orm.message import Message as MessageModel
from letta.orm.sqlalchemy_base import AccessType
from letta.orm.step import Step as StepModel
from letta.orm.step_metrics import StepMetrics as StepMetricsModel
from letta.otel.tracing import get_trace_id, trace_method
from letta.schemas.enums import StepStatus
from letta.schemas.letta_stop_reason import LettaStopReason, StopReasonType
+from letta.schemas.message import Message as PydanticMessage
from letta.schemas.openai.chat_completion_response import UsageStatistics
from letta.schemas.step import Step as PydanticStep
from 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_method
async def update_step_stop_reason(self, actor: PydanticUser, step_id: str, stop_reason: StopReasonType) -> PydanticStep: