Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add usage columns to steps table (#9270)
Sarah Wooderse0a23f7039ec
diff --git a/alembic/versions/3e54e2fa2f7e_add_usage_columns_to_steps.py b/alembic/versions/3e54e2fa2f7e_add_usage_columns_to_steps.pynew file mode 100644index 000000000..997d0d800--- /dev/null+++ b/alembic/versions/3e54e2fa2f7e_add_usage_columns_to_steps.py@@ -0,0 +1,33 @@+"""add_usage_columns_to_steps++Revision ID: 3e54e2fa2f7e+Revises: a1b2c3d4e5f8+Create Date: 2026-02-03 16:35:51.327031++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op++# revision identifiers, used by Alembic.+revision: str = "3e54e2fa2f7e"+down_revision: Union[str, None] = "a1b2c3d4e5f8"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ op.add_column("steps", sa.Column("model_handle", sa.String(), nullable=True))+ op.add_column("steps", sa.Column("cached_input_tokens", sa.Integer(), nullable=True))+ op.add_column("steps", sa.Column("cache_write_tokens", sa.Integer(), nullable=True))+ op.add_column("steps", sa.Column("reasoning_tokens", sa.Integer(), nullable=True))+++def downgrade() -> None:+ op.drop_column("steps", "reasoning_tokens")+ op.drop_column("steps", "cache_write_tokens")+ op.drop_column("steps", "cached_input_tokens")+ op.drop_column("steps", "model_handle")diff --git a/fern/openapi.json b/fern/openapi.jsonindex 18c2b474a..3230ece0c 100644--- a/fern/openapi.json+++ b/fern/openapi.json@@ -42460,6 +42460,18 @@"title": "Model","description": "The name of the model used for this step."},+ "model_handle": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Model Handle",+ "description": "The model handle (e.g., 'openai/gpt-4o-mini') used for this step."+ },"model_endpoint": {"anyOf": [{@@ -42520,6 +42532,42 @@"title": "Total Tokens","description": "The total number of tokens processed by the agent during this step."},+ "cached_input_tokens": {+ "anyOf": [+ {+ "type": "integer"+ },+ {+ "type": "null"+ }+ ],+ "title": "Cached Input Tokens",+ "description": "The number of input tokens served from cache. None if not reported by provider."+ },+ "cache_write_tokens": {+ "anyOf": [+ {+ "type": "integer"+ },+ {+ "type": "null"+ }+ ],+ "title": "Cache Write Tokens",+ "description": "The number of input tokens written to cache (Anthropic only). None if not reported by provider."+ },+ "reasoning_tokens": {+ "anyOf": [+ {+ "type": "integer"+ },+ {+ "type": "null"+ }+ ],+ "title": "Reasoning Tokens",+ "description": "The number of reasoning/thinking tokens generated. None if not reported by provider."+ },"completion_tokens_details": {"anyOf": [{diff --git a/letta/agents/letta_agent.py b/letta/agents/letta_agent.pyindex 8460a46a1..246f6d3f1 100644--- a/letta/agents/letta_agent.py+++ b/letta/agents/letta_agent.py@@ -311,6 +311,7 @@ class LettaAgent(BaseAgent):step_id=step_id,project_id=agent_state.project_id,status=StepStatus.PENDING,+ model_handle=agent_state.llm_config.handle,)# Only use step_id in messages if step was actually createdeffective_step_id = step_id if logged_step else None@@ -645,6 +646,7 @@ class LettaAgent(BaseAgent):step_id=step_id,project_id=agent_state.project_id,status=StepStatus.PENDING,+ model_handle=agent_state.llm_config.handle,)# Only use step_id in messages if step was actually createdeffective_step_id = step_id if logged_step else None@@ -981,6 +983,7 @@ class LettaAgent(BaseAgent):step_id=step_id,project_id=agent_state.project_id,status=StepStatus.PENDING,+ model_handle=agent_state.llm_config.handle,)# Only use step_id in messages if step was actually createdeffective_step_id = step_id if logged_step else Nonediff --git a/letta/agents/letta_agent_v2.py b/letta/agents/letta_agent_v2.pyindex 85e6b86c3..657ac79d3 100644--- a/letta/agents/letta_agent_v2.py+++ b/letta/agents/letta_agent_v2.py@@ -873,6 +873,7 @@ class LettaAgentV2(BaseAgentV2):step_id=step_id,project_id=self.agent_state.project_id,status=StepStatus.PENDING,+ model_handle=self.agent_state.llm_config.handle,)# Also create step metrics early and update at the end of the stepdiff --git a/letta/orm/step.py b/letta/orm/step.pyindex 13d6d5525..64f0353a3 100644--- a/letta/orm/step.py+++ b/letta/orm/step.py@@ -43,6 +43,9 @@ class Step(SqlalchemyBase, ProjectMixin):provider_name: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="The name of the provider used for this step.")provider_category: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="The category of the provider used for this step.")model: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="The name of the model used for this step.")+ model_handle: Mapped[Optional[str]] = mapped_column(+ None, nullable=True, doc="The model handle (e.g., 'openai/gpt-4o-mini') used for this step."+ )model_endpoint: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="The model endpoint url used for this step.")context_window_limit: Mapped[Optional[int]] = mapped_column(None, nullable=True, doc="The context window limit configured for this step."@@ -50,6 +53,15 @@ class Step(SqlalchemyBase, ProjectMixin):completion_tokens: Mapped[int] = mapped_column(default=0, doc="Number of tokens generated by the agent")prompt_tokens: Mapped[int] = mapped_column(default=0, doc="Number of tokens in the prompt")total_tokens: Mapped[int] = mapped_column(default=0, doc="Total number of tokens processed by the agent")+ cached_input_tokens: Mapped[Optional[int]] = mapped_column(+ None, nullable=True, doc="Number of input tokens served from cache. None if not reported by provider."+ )+ cache_write_tokens: Mapped[Optional[int]] = mapped_column(+ None, nullable=True, doc="Number of input tokens written to cache (Anthropic only). None if not reported by provider."+ )+ reasoning_tokens: Mapped[Optional[int]] = mapped_column(+ None, nullable=True, doc="Number of reasoning/thinking tokens generated. None if not reported by provider."+ )completion_tokens_details: Mapped[Optional[Dict]] = mapped_column(JSON, nullable=True, doc="Detailed completion token breakdown (e.g., reasoning_tokens).")diff --git a/letta/schemas/step.py b/letta/schemas/step.pyindex 83126a96a..0c5255479 100644--- a/letta/schemas/step.py+++ b/letta/schemas/step.py@@ -25,11 +25,21 @@ class Step(StepBase):provider_name: Optional[str] = Field(None, description="The name of the provider used for this step.")provider_category: Optional[str] = Field(None, description="The category of the provider used for this step.")model: Optional[str] = Field(None, description="The name of the model used for this step.")+ model_handle: Optional[str] = Field(None, description="The model handle (e.g., 'openai/gpt-4o-mini') used for this step.")model_endpoint: Optional[str] = Field(None, description="The model endpoint url used for this step.")context_window_limit: Optional[int] = Field(None, description="The context window limit configured for this step.")completion_tokens: Optional[int] = Field(None, description="The number of tokens generated by the agent during this step.")prompt_tokens: Optional[int] = Field(None, description="The number of tokens in the prompt during this step.")total_tokens: Optional[int] = Field(None, description="The total number of tokens processed by the agent during this step.")+ cached_input_tokens: Optional[int] = Field(+ None, description="The number of input tokens served from cache. None if not reported by provider."+ )+ cache_write_tokens: Optional[int] = Field(+ None, description="The number of input tokens written to cache (Anthropic only). None if not reported by provider."+ )+ reasoning_tokens: Optional[int] = Field(+ None, description="The number of reasoning/thinking tokens generated. None if not reported by provider."+ )completion_tokens_details: Optional[Dict] = Field(None, description="Detailed completion token breakdown (e.g., reasoning_tokens).")prompt_tokens_details: Optional[Dict] = Field(None, description="Detailed prompt token breakdown (e.g., cached_tokens, cache_read_tokens, cache_creation_tokens)."diff --git a/letta/services/step_manager.py b/letta/services/step_manager.pyindex 92733e751..80db383c1 100644--- a/letta/services/step_manager.py+++ b/letta/services/step_manager.py@@ -19,6 +19,7 @@ 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+from letta.schemas.usage import normalize_cache_tokens, normalize_reasoning_tokensfrom letta.schemas.user import User as PydanticUserfrom letta.server.db import db_registryfrom letta.server.rest_api.middleware.request_id import get_request_id@@ -107,6 +108,26 @@ class StepManager:error_type: Optional[str] = None,error_data: Optional[Dict] = None,) -> PydanticStep:+ # Extract normalized usage fields+ cached_input_tokens = None+ cache_write_tokens = None+ reasoning_tokens = None+ prompt_tokens_details = None+ completion_tokens_details = None++ if usage.prompt_tokens_details:+ prompt_tokens_details = usage.prompt_tokens_details.model_dump()+ cached_input, cache_write = normalize_cache_tokens(usage.prompt_tokens_details)+ if cached_input > 0:+ cached_input_tokens = cached_input+ if cache_write > 0:+ cache_write_tokens = cache_write+ if usage.completion_tokens_details:+ completion_tokens_details = usage.completion_tokens_details.model_dump()+ reasoning = normalize_reasoning_tokens(usage.completion_tokens_details)+ if reasoning > 0:+ reasoning_tokens = reasoning+step_data = {"origin": None,"organization_id": actor.organization_id,@@ -115,11 +136,17 @@ class StepManager:"provider_name": provider_name,"provider_category": provider_category,"model": model,+ "model_handle": model_handle,"model_endpoint": model_endpoint,"context_window_limit": context_window_limit,"completion_tokens": usage.completion_tokens,"prompt_tokens": usage.prompt_tokens,"total_tokens": usage.total_tokens,+ "cached_input_tokens": cached_input_tokens,+ "cache_write_tokens": cache_write_tokens,+ "reasoning_tokens": reasoning_tokens,+ "prompt_tokens_details": prompt_tokens_details,+ "completion_tokens_details": completion_tokens_details,"run_id": run_id,"tags": [],"tid": None,@@ -166,6 +193,7 @@ class StepManager:error_type: Optional[str] = None,error_data: Optional[Dict] = None,allow_partial: Optional[bool] = False,+ model_handle: Optional[str] = None,) -> PydanticStep:step_data = {"origin": None,@@ -416,8 +444,18 @@ class StepManager:# Persist detailed token breakdowns if availableif usage.prompt_tokens_details:step.prompt_tokens_details = usage.prompt_tokens_details.model_dump()+ # Extract normalized cache tokens+ cached_input, cache_write = normalize_cache_tokens(usage.prompt_tokens_details)+ if cached_input > 0:+ step.cached_input_tokens = cached_input+ if cache_write > 0:+ step.cache_write_tokens = cache_writeif usage.completion_tokens_details:step.completion_tokens_details = usage.completion_tokens_details.model_dump()+ # Extract normalized reasoning tokens+ reasoning = normalize_reasoning_tokens(usage.completion_tokens_details)+ if reasoning > 0:+ step.reasoning_tokens = reasoning# context manager now handles commits# await session.commit()