Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add last run completion and duration db columns to agents (#2903)
jnjpng951ea59b3093
diff --git a/alembic/versions/9758adf8fdd3_add_run_completion_and_duration_to_.py b/alembic/versions/9758adf8fdd3_add_run_completion_and_duration_to_.pynew file mode 100644index 000000000..5702c542c--- /dev/null+++ b/alembic/versions/9758adf8fdd3_add_run_completion_and_duration_to_.py@@ -0,0 +1,33 @@+"""add_run_completion_and_duration_to_agents_table++Revision ID: 9758adf8fdd3+Revises: 9556081ce65b+Create Date: 2025-06-18 18:22:31.135685++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op++# revision identifiers, used by Alembic.+revision: str = "9758adf8fdd3"+down_revision: Union[str, None] = "9556081ce65b"+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("agents", sa.Column("last_run_completion", sa.DateTime(timezone=True), nullable=True))+ op.add_column("agents", sa.Column("last_run_duration_ms", sa.Integer(), nullable=True))+ # ### end Alembic commands ###+++def downgrade() -> None:+ # ### commands auto generated by Alembic - please adjust! ###+ op.drop_column("agents", "last_run_duration_ms")+ op.drop_column("agents", "last_run_completion")+ # ### end Alembic commands ###diff --git a/letta/agents/letta_agent.py b/letta/agents/letta_agent.pyindex beed72d2c..eaccf6e91 100644--- a/letta/agents/letta_agent.py+++ b/letta/agents/letta_agent.py@@ -1,6 +1,7 @@import asyncioimport jsonimport uuid+from datetime import datetimefrom typing import AsyncGenerator, Dict, List, Optional, Tuple, Unionfrom openai import AsyncStream@@ -13,7 +14,7 @@ from letta.agents.helpers import _create_letta_response, _prepare_in_context_mesfrom letta.constants import DEFAULT_MAX_STEPSfrom letta.errors import ContextWindowExceededErrorfrom letta.helpers import ToolRulesSolver-from letta.helpers.datetime_helpers import AsyncTimer, get_utc_timestamp_ns, ns_to_ms+from letta.helpers.datetime_helpers import AsyncTimer, get_utc_time, get_utc_timestamp_ns, ns_to_msfrom letta.helpers.tool_execution_helper import enable_strict_modefrom letta.interfaces.anthropic_streaming_interface import AnthropicStreamingInterfacefrom letta.interfaces.openai_streaming_interface import OpenAIStreamingInterface@@ -25,7 +26,7 @@ from letta.orm.enums import ToolTypefrom letta.otel.context import get_ctx_attributesfrom letta.otel.metric_registry import MetricRegistryfrom letta.otel.tracing import log_event, trace_method, tracer-from letta.schemas.agent import AgentState+from letta.schemas.agent import AgentState, UpdateAgentfrom letta.schemas.enums import MessageRolefrom letta.schemas.letta_message import MessageTypefrom letta.schemas.letta_message_content import OmittedReasoningContent, ReasoningContent, RedactedReasoningContent, TextContent@@ -283,8 +284,13 @@ class LettaAgent(BaseAgent):# log request timeif request_start_timestamp_ns:now = get_utc_timestamp_ns()- request_ns = now - request_start_timestamp_ns- request_span.add_event(name="letta_request_ms", attributes={"duration_ms": ns_to_ms(request_ns)})+ duration_ms = ns_to_ms(now - request_start_timestamp_ns)+ request_span.add_event(name="letta_request_ms", attributes={"duration_ms": duration_ms})++ # update agent's last run metrics+ now_datetime = get_utc_time()+ await self._update_agent_last_run_metrics(now_datetime, duration_ms)+request_span.end()# Return back usage@@ -410,8 +416,13 @@ class LettaAgent(BaseAgent):# log request timeif request_start_timestamp_ns:now = get_utc_timestamp_ns()- request_ns = now - request_start_timestamp_ns- request_span.add_event(name="request_ms", attributes={"duration_ms": ns_to_ms(request_ns)})+ duration_ms = ns_to_ms(now - request_start_timestamp_ns)+ request_span.add_event(name="request_ms", attributes={"duration_ms": duration_ms})++ # update agent's last run metrics+ now_datetime = get_utc_time()+ await self._update_agent_last_run_metrics(now_datetime, duration_ms)+request_span.end()# Extend the in context message ids@@ -426,6 +437,16 @@ class LettaAgent(BaseAgent):return current_in_context_messages, new_in_context_messages, usage, stop_reason+ async def _update_agent_last_run_metrics(self, completion_time: datetime, duration_ms: float) -> None:+ try:+ await self.agent_manager.update_agent_async(+ agent_id=self.agent_id,+ agent_update=UpdateAgent(last_run_completion=completion_time, last_run_duration_ms=duration_ms),+ actor=self.actor,+ )+ except Exception as e:+ logger.error(f"Failed to update agent's last run metrics: {e}")+@trace_methodasync def step_stream(self,@@ -631,8 +652,13 @@ class LettaAgent(BaseAgent):# log time of entire requestif request_start_timestamp_ns:now = get_utc_timestamp_ns()- request_ns = now - request_start_timestamp_ns- request_span.add_event(name="letta_request_ms", attributes={"duration_ms": ns_to_ms(request_ns)})+ duration_ms = ns_to_ms(now - request_start_timestamp_ns)+ request_span.add_event(name="letta_request_ms", attributes={"duration_ms": duration_ms})++ # update agent's last run metrics+ completion_time = get_utc_time()+ await self._update_agent_last_run_metrics(completion_time, duration_ms)+request_span.end()for finish_chunk in self.get_finish_chunks_for_stream(usage, stop_reason):diff --git a/letta/orm/agent.py b/letta/orm/agent.pyindex 2080f9132..a1ab53679 100644--- a/letta/orm/agent.py+++ b/letta/orm/agent.py@@ -1,8 +1,9 @@import asyncioimport uuid+from datetime import datetimefrom typing import TYPE_CHECKING, List, Optional, Set-from sqlalchemy import JSON, Boolean, Index, String+from sqlalchemy import JSON, Boolean, DateTime, Index, Integer, Stringfrom sqlalchemy.ext.asyncio import AsyncAttrsfrom sqlalchemy.orm import Mapped, mapped_column, relationship@@ -80,6 +81,14 @@ class Agent(SqlalchemyBase, OrganizationMixin, AsyncAttrs):Boolean, doc="If set to True, memory management will move to a background agent thread.")+ # Run metrics+ last_run_completion: Mapped[Optional[datetime]] = mapped_column(+ DateTime(timezone=True), nullable=True, doc="The timestamp when the agent last completed a run."+ )+ last_run_duration_ms: Mapped[Optional[int]] = mapped_column(+ Integer, nullable=True, doc="The duration in milliseconds of the agent's last run."+ )+# relationshipsorganization: Mapped["Organization"] = relationship("Organization", back_populates="agents")tool_exec_environment_variables: Mapped[List["AgentEnvironmentVariable"]] = relationship(@@ -176,6 +185,8 @@ class Agent(SqlalchemyBase, OrganizationMixin, AsyncAttrs):"updated_at": self.updated_at,"enable_sleeptime": self.enable_sleeptime,"response_format": self.response_format,+ "last_run_completion": self.last_run_completion,+ "last_run_duration_ms": self.last_run_duration_ms,# optional field defaults"tags": [],"tools": [],@@ -252,6 +263,8 @@ class Agent(SqlalchemyBase, OrganizationMixin, AsyncAttrs):"updated_at": self.updated_at,"enable_sleeptime": self.enable_sleeptime,"response_format": self.response_format,+ "last_run_completion": self.last_run_completion,+ "last_run_duration_ms": self.last_run_duration_ms,}optional_fields = {"tags": [],diff --git a/letta/schemas/agent.py b/letta/schemas/agent.pyindex 32e9cf331..0220e10d4 100644--- a/letta/schemas/agent.py+++ b/letta/schemas/agent.py@@ -1,3 +1,4 @@+from datetime import datetimefrom enum import Enumfrom typing import Dict, List, Optional@@ -105,6 +106,10 @@ class AgentState(OrmMetadataBase, validate_assignment=True):multi_agent_group: Optional[Group] = Field(None, description="The multi-agent group that this agent manages")+ # Run metrics+ last_run_completion: Optional[datetime] = Field(None, description="The timestamp when the agent last completed a run.")+ last_run_duration_ms: Optional[int] = Field(None, description="The duration in milliseconds of the agent's last run.")+def get_agent_env_vars_as_dict(self) -> Dict[str, str]:# Get environment variables for this agent specificallyper_agent_env_vars = {}@@ -279,6 +284,8 @@ class UpdateAgent(BaseModel):)enable_sleeptime: Optional[bool] = Field(None, description="If set to True, memory management will move to a background agent thread.")response_format: Optional[ResponseFormatUnion] = Field(None, description="The response format for the agent.")+ last_run_completion: Optional[datetime] = Field(None, description="The timestamp when the agent last completed a run.")+ last_run_duration_ms: Optional[int] = Field(None, description="The duration in milliseconds of the agent's last run.")class Config:extra = "ignore" # Ignores extra fieldsdiff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.pyindex 7af2d304c..4ddbdb3a8 100644--- a/letta/server/rest_api/routers/v1/agents.py+++ b/letta/server/rest_api/routers/v1/agents.py@@ -80,6 +80,10 @@ async def list_agents(False,description="Whether to sort agents oldest to newest (True) or newest to oldest (False, default)",),+ sort_by: Optional[str] = Query(+ "created_at",+ description="Field to sort by. Options: 'created_at' (default), 'last_run_completion'",+ ),):"""List all agents associated with a given user.@@ -108,6 +112,7 @@ async def list_agents(identifier_keys=identifier_keys,include_relationships=include_relationships,ascending=ascending,+ sort_by=sort_by,)diff --git a/letta/services/agent_manager.py b/letta/services/agent_manager.pyindex 554ea0abf..eaa6851a5 100644--- a/letta/services/agent_manager.py+++ b/letta/services/agent_manager.py@@ -622,6 +622,8 @@ class AgentManager:"message_buffer_autoclear": agent_update.message_buffer_autoclear,"enable_sleeptime": agent_update.enable_sleeptime,"response_format": agent_update.response_format,+ "last_run_completion": agent_update.last_run_completion,+ "last_run_duration_ms": agent_update.last_run_duration_ms,}for col, val in scalar_updates.items():if val is not None:@@ -742,6 +744,8 @@ class AgentManager:"message_buffer_autoclear": agent_update.message_buffer_autoclear,"enable_sleeptime": agent_update.enable_sleeptime,"response_format": agent_update.response_format,+ "last_run_completion": agent_update.last_run_completion,+ "last_run_duration_ms": agent_update.last_run_duration_ms,}for col, val in scalar_updates.items():if val is not None:@@ -844,6 +848,7 @@ class AgentManager:identifier_keys: Optional[List[str]] = None,include_relationships: Optional[List[str]] = None,ascending: bool = True,+ sort_by: Optional[str] = "created_at",) -> List[PydanticAgentState]:"""Retrieves agents with optimized filtering and optional field selection.@@ -876,7 +881,7 @@ class AgentManager:query = _apply_filters(query, name, query_text, project_id, template_id, base_template_id)query = _apply_identity_filters(query, identity_id, identifier_keys)query = _apply_tag_filter(query, tags, match_all_tags)- query = _apply_pagination(query, before, after, session, ascending=ascending)+ query = _apply_pagination(query, before, after, session, ascending=ascending, sort_by=sort_by)if limit:query = query.limit(limit)@@ -903,6 +908,7 @@ class AgentManager:identifier_keys: Optional[List[str]] = None,include_relationships: Optional[List[str]] = None,ascending: bool = True,+ sort_by: Optional[str] = "created_at",) -> List[PydanticAgentState]:"""Retrieves agents with optimized filtering and optional field selection.@@ -935,7 +941,7 @@ class AgentManager:query = _apply_filters(query, name, query_text, project_id, template_id, base_template_id)query = _apply_identity_filters(query, identity_id, identifier_keys)query = _apply_tag_filter(query, tags, match_all_tags)- query = await _apply_pagination_async(query, before, after, session, ascending=ascending)+ query = await _apply_pagination_async(query, before, after, session, ascending=ascending, sort_by=sort_by)if limit:query = query.limit(limit)diff --git a/letta/services/helpers/agent_manager_helper.py b/letta/services/helpers/agent_manager_helper.pyindex 6839f8d86..ebe6dc7ba 100644--- a/letta/services/helpers/agent_manager_helper.py+++ b/letta/services/helpers/agent_manager_helper.py@@ -449,41 +449,69 @@ def _cursor_filter(created_at_col, id_col, ref_created_at, ref_id, forward: bool)-def _apply_pagination(query, before: Optional[str], after: Optional[str], session, ascending: bool = True) -> any:+def _apply_pagination(+ query, before: Optional[str], after: Optional[str], session, ascending: bool = True, sort_by: str = "created_at"+) -> any:+ # Determine the sort column+ if sort_by == "last_run_completion":+ sort_column = AgentModel.last_run_completion+ else:+ sort_column = AgentModel.created_at+if after:- result = session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == after)).first()+ if sort_by == "last_run_completion":+ result = session.execute(select(AgentModel.last_run_completion, AgentModel.id).where(AgentModel.id == after)).first()+ else:+ result = session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == after)).first()if result:- after_created_at, after_id = result- query = query.where(_cursor_filter(AgentModel.created_at, AgentModel.id, after_created_at, after_id, forward=ascending))+ after_sort_value, after_id = result+ query = query.where(_cursor_filter(sort_column, AgentModel.id, after_sort_value, after_id, forward=ascending))if before:- result = session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == before)).first()+ if sort_by == "last_run_completion":+ result = session.execute(select(AgentModel.last_run_completion, AgentModel.id).where(AgentModel.id == before)).first()+ else:+ result = session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == before)).first()if result:- before_created_at, before_id = result- query = query.where(_cursor_filter(AgentModel.created_at, AgentModel.id, before_created_at, before_id, forward=not ascending))+ before_sort_value, before_id = result+ query = query.where(_cursor_filter(sort_column, AgentModel.id, before_sort_value, before_id, forward=not ascending))# Apply orderingorder_fn = asc if ascending else desc- query = query.order_by(order_fn(AgentModel.created_at), order_fn(AgentModel.id))+ query = query.order_by(order_fn(sort_column), order_fn(AgentModel.id))return query-async def _apply_pagination_async(query, before: Optional[str], after: Optional[str], session, ascending: bool = True) -> any:+async def _apply_pagination_async(+ query, before: Optional[str], after: Optional[str], session, ascending: bool = True, sort_by: str = "created_at"+) -> any:+ # Determine the sort column+ if sort_by == "last_run_completion":+ sort_column = AgentModel.last_run_completion+ else:+ sort_column = AgentModel.created_at+if after:- result = (await session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == after))).first()+ if sort_by == "last_run_completion":+ result = (await session.execute(select(AgentModel.last_run_completion, AgentModel.id).where(AgentModel.id == after))).first()+ else:+ result = (await session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == after))).first()if result:- after_created_at, after_id = result- query = query.where(_cursor_filter(AgentModel.created_at, AgentModel.id, after_created_at, after_id, forward=ascending))+ after_sort_value, after_id = result+ query = query.where(_cursor_filter(sort_column, AgentModel.id, after_sort_value, after_id, forward=ascending))if before:- result = (await session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == before))).first()+ if sort_by == "last_run_completion":+ result = (await session.execute(select(AgentModel.last_run_completion, AgentModel.id).where(AgentModel.id == before))).first()+ else:+ result = (await session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == before))).first()if result:- before_created_at, before_id = result- query = query.where(_cursor_filter(AgentModel.created_at, AgentModel.id, before_created_at, before_id, forward=not ascending))+ before_sort_value, before_id = result+ query = query.where(_cursor_filter(sort_column, AgentModel.id, before_sort_value, before_id, forward=not ascending))# Apply orderingorder_fn = asc if ascending else desc- query = query.order_by(order_fn(AgentModel.created_at), order_fn(AgentModel.id))+ query = query.order_by(order_fn(sort_column), order_fn(AgentModel.id))return query