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 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_.py
new file mode 100644
index 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.py
index beed72d2c..eaccf6e91 100644
--- a/letta/agents/letta_agent.py
+++ b/letta/agents/letta_agent.py
@@ -1,6 +1,7 @@
import asyncio
import json
import uuid
+from datetime import datetime
from typing import AsyncGenerator, Dict, List, Optional, Tuple, Union
from openai import AsyncStream
@@ -13,7 +14,7 @@ from letta.agents.helpers import _create_letta_response, _prepare_in_context_mes
from letta.constants import DEFAULT_MAX_STEPS
from letta.errors import ContextWindowExceededError
from 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_ms
from letta.helpers.tool_execution_helper import enable_strict_mode
from letta.interfaces.anthropic_streaming_interface import AnthropicStreamingInterface
from letta.interfaces.openai_streaming_interface import OpenAIStreamingInterface
@@ -25,7 +26,7 @@ from letta.orm.enums import ToolType
from letta.otel.context import get_ctx_attributes
from letta.otel.metric_registry import MetricRegistry
from letta.otel.tracing import log_event, trace_method, tracer
-from letta.schemas.agent import AgentState
+from letta.schemas.agent import AgentState, UpdateAgent
from letta.schemas.enums import MessageRole
from letta.schemas.letta_message import MessageType
from letta.schemas.letta_message_content import OmittedReasoningContent, ReasoningContent, RedactedReasoningContent, TextContent
@@ -283,8 +284,13 @@ class LettaAgent(BaseAgent):
# log request time
if 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 time
if 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_method
async def step_stream(
self,
@@ -631,8 +652,13 @@ class LettaAgent(BaseAgent):
# log time of entire request
if 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.py
index 2080f9132..a1ab53679 100644
--- a/letta/orm/agent.py
+++ b/letta/orm/agent.py
@@ -1,8 +1,9 @@
import asyncio
import uuid
+from datetime import datetime
from typing import TYPE_CHECKING, List, Optional, Set
-from sqlalchemy import JSON, Boolean, Index, String
+from sqlalchemy import JSON, Boolean, DateTime, Index, Integer, String
from sqlalchemy.ext.asyncio import AsyncAttrs
from 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."
+ )
+
# relationships
organization: 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.py
index 32e9cf331..0220e10d4 100644
--- a/letta/schemas/agent.py
+++ b/letta/schemas/agent.py
@@ -1,3 +1,4 @@
+from datetime import datetime
from enum import Enum
from 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 specifically
per_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 fields
diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.py
index 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.py
index 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.py
index 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 ordering
order_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 ordering
order_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