Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add last_stop_reason to AgentState [LET-5911] (#5772)
Christina Tongef3df907c532
diff --git a/alembic/versions/89fd4648866b_add_last_stop_reason_to_agent_state.py b/alembic/versions/89fd4648866b_add_last_stop_reason_to_agent_state.pynew file mode 100644index 000000000..c8de5e18c--- /dev/null+++ b/alembic/versions/89fd4648866b_add_last_stop_reason_to_agent_state.py@@ -0,0 +1,31 @@+"""add last_stop_reason to agent state++Revision ID: 89fd4648866b+Revises: f6cd5a1e519d+Create Date: 2025-10-27 16:55:54.383688++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op++# revision identifiers, used by Alembic.+revision: str = "89fd4648866b"+down_revision: Union[str, None] = "f6cd5a1e519d"+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_stop_reason", sa.String(), nullable=True))+ # ### end Alembic commands ###+++def downgrade() -> None:+ # ### commands auto generated by Alembic - please adjust! ###+ op.drop_column("agents", "last_stop_reason")+ # ### end Alembic commands ###diff --git a/fern/openapi.json b/fern/openapi.jsonindex 357376404..39682b978 100644--- a/fern/openapi.json+++ b/fern/openapi.json@@ -18981,6 +18981,17 @@"title": "Last Run Duration Ms","description": "The duration in milliseconds of the agent's last run."},+ "last_stop_reason": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/StopReasonType"+ },+ {+ "type": "null"+ }+ ],+ "description": "The stop reason from the agent's last run."+ },"timezone": {"anyOf": [{@@ -34653,6 +34664,17 @@"title": "Last Run Duration Ms","description": "The duration in milliseconds of the agent's last run."},+ "last_stop_reason": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/StopReasonType"+ },+ {+ "type": "null"+ }+ ],+ "description": "The stop reason from the agent's last run."+ },"timezone": {"anyOf": [{diff --git a/letta/orm/agent.py b/letta/orm/agent.pyindex fc1f17a88..31f3ef300 100644--- a/letta/orm/agent.py+++ b/letta/orm/agent.py@@ -16,6 +16,7 @@ from letta.orm.sqlalchemy_base import SqlalchemyBasefrom letta.schemas.agent import AgentState as PydanticAgentStatefrom letta.schemas.embedding_config import EmbeddingConfigfrom letta.schemas.enums import AgentType+from letta.schemas.letta_stop_reason import StopReasonTypefrom letta.schemas.llm_config import LLMConfigfrom letta.schemas.memory import Memoryfrom letta.schemas.response_format import ResponseFormatUnion@@ -93,6 +94,9 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixinlast_run_duration_ms: Mapped[Optional[int]] = mapped_column(Integer, nullable=True, doc="The duration in milliseconds of the agent's last run.")+ last_stop_reason: Mapped[Optional[StopReasonType]] = mapped_column(+ String, nullable=True, doc="The stop reason from the agent's last run."+ )# timezonetimezone: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="The timezone of the agent (for the context window).")@@ -232,6 +236,7 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin"response_format": self.response_format,"last_run_completion": self.last_run_completion,"last_run_duration_ms": self.last_run_duration_ms,+ "last_stop_reason": self.last_stop_reason,"timezone": self.timezone,"max_files_open": self.max_files_open,"per_file_view_window_char_limit": self.per_file_view_window_char_limit,@@ -334,6 +339,7 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin"response_format": self.response_format,"last_run_completion": self.last_run_completion,"last_run_duration_ms": self.last_run_duration_ms,+ "last_stop_reason": self.last_stop_reason,"max_files_open": self.max_files_open,"per_file_view_window_char_limit": self.per_file_view_window_char_limit,"hidden": self.hidden,diff --git a/letta/schemas/agent.py b/letta/schemas/agent.pyindex 48912f8f4..312b6f01b 100644--- a/letta/schemas/agent.py+++ b/letta/schemas/agent.py@@ -14,6 +14,7 @@ from letta.schemas.file import FileStatusfrom letta.schemas.group import Groupfrom letta.schemas.identity import Identityfrom letta.schemas.letta_base import OrmMetadataBase+from letta.schemas.letta_stop_reason import StopReasonTypefrom letta.schemas.llm_config import LLMConfigfrom letta.schemas.memory import Memoryfrom letta.schemas.message import Message, MessageCreate@@ -135,6 +136,7 @@ class AgentState(OrmMetadataBase, validate_assignment=True):# Run metricslast_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.")+ last_stop_reason: Optional[StopReasonType] = Field(None, description="The stop reason from the agent's last run.")# timezonetimezone: Optional[str] = Field(None, description="The timezone of the agent (IANA format).")@@ -388,6 +390,7 @@ class UpdateAgent(BaseModel):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.")+ last_stop_reason: Optional[StopReasonType] = Field(None, description="The stop reason from the agent's last run.")timezone: Optional[str] = Field(None, description="The timezone of the agent (IANA format).")max_files_open: Optional[int] = Field(None,diff --git a/letta/services/agent_manager.py b/letta/services/agent_manager.pyindex 29f689194..7f40a6284 100644--- a/letta/services/agent_manager.py+++ b/letta/services/agent_manager.py@@ -712,6 +712,7 @@ class AgentManager:"response_format": agent_update.response_format,"last_run_completion": agent_update.last_run_completion,"last_run_duration_ms": agent_update.last_run_duration_ms,+ "last_stop_reason": agent_update.last_stop_reason,"timezone": agent_update.timezone,"max_files_open": agent_update.max_files_open,"per_file_view_window_char_limit": agent_update.per_file_view_window_char_limit,diff --git a/letta/services/run_manager.py b/letta/services/run_manager.pyindex b96704d53..21a94070d 100644--- a/letta/services/run_manager.py+++ b/letta/services/run_manager.py@@ -341,6 +341,20 @@ class RunManager:await session.commit()+ # Update agent's last_stop_reason when run completes+ # Do this after run update is committed to database+ if is_terminal_update and update.stop_reason:+ try:+ from letta.schemas.agent import UpdateAgent++ await self.agent_manager.update_agent_async(+ agent_id=pydantic_run.agent_id,+ agent_update=UpdateAgent(last_stop_reason=update.stop_reason),+ actor=actor,+ )+ except Exception as e:+ logger.error(f"Failed to update agent's last_stop_reason for run {run_id}: {e}")+# update run metrics tablenum_steps = len(await self.step_manager.list_steps_async(run_id=run_id, actor=actor))diff --git a/tests/integration_test_human_in_the_loop.py b/tests/integration_test_human_in_the_loop.pyindex 3fed4676c..b4d0b0678 100644--- a/tests/integration_test_human_in_the_loop.py+++ b/tests/integration_test_human_in_the_loop.py@@ -1277,3 +1277,51 @@ def test_parallel_tool_calling(assert messages[1].message_type == "assistant_message"assert messages[2].message_type == "stop_reason"assert messages[3].message_type == "usage_statistics"+++def test_agent_records_last_stop_reason_after_approval_flow(+ client: Letta,+ agent: AgentState,+) -> None:+ """+ Test that the agent's last_stop_reason is properly updated after a human-in-the-loop flow.+ This verifies the integration between run completion and agent state updates.+ """+ # Get initial agent state+ initial_agent = client.agents.retrieve(agent_id=agent.id)+ initial_stop_reason = initial_agent.last_stop_reason++ # Trigger approval request+ response = client.agents.messages.create(+ agent_id=agent.id,+ messages=USER_MESSAGE_TEST_APPROVAL,+ )++ # Verify we got an approval request+ messages = response.messages+ assert messages is not None+ assert len(messages) == 3+ assert messages[2].message_type == "approval_request_message"++ # Check agent after approval request (run should be paused with requires_approval)+ agent_after_request = client.agents.retrieve(agent_id=agent.id)+ assert agent_after_request.last_stop_reason == "requires_approval"++ # Approve the tool call+ approve_tool_call(client, agent.id, response.messages[2].tool_call.tool_call_id)++ # Check agent after approval (run should complete with end_turn or similar)+ agent_after_approval = client.agents.retrieve(agent_id=agent.id)+ # After approval and run completion, stop reason should be updated (could be end_turn or other terminal reason)+ assert agent_after_approval.last_stop_reason is not None+ assert agent_after_approval.last_stop_reason != initial_stop_reason # Should be different from initial++ # Send follow-up message to complete the flow+ response2 = client.agents.messages.create(+ agent_id=agent.id,+ messages=USER_MESSAGE_FOLLOW_UP,+ )++ # Verify final agent state has the most recent stop reason+ final_agent = client.agents.retrieve(agent_id=agent.id)+ assert final_agent.last_stop_reason is not Nonediff --git a/tests/managers/test_agent_manager.py b/tests/managers/test_agent_manager.pyindex 08433bc13..5493f6cf4 100644--- a/tests/managers/test_agent_manager.py+++ b/tests/managers/test_agent_manager.py@@ -625,6 +625,46 @@ async def test_update_agent_file_fields(server: SyncServer, comprehensive_test_aassert updated_agent.per_file_view_window_char_limit == 150_000+async def test_update_agent_last_stop_reason(server: SyncServer, comprehensive_test_agent_fixture, default_user):+ """Test updating last_stop_reason field on an existing agent"""++ agent, _ = comprehensive_test_agent_fixture++ assert agent.last_stop_reason is None++ # Update with end_turn stop reason+ update_request = UpdateAgent(+ last_stop_reason=StopReasonType.end_turn,+ last_run_completion=datetime.now(timezone.utc),+ last_run_duration_ms=1500,+ )+ updated_agent = await server.agent_manager.update_agent_async(agent.id, update_request, actor=default_user)++ assert updated_agent.last_stop_reason == StopReasonType.end_turn+ assert updated_agent.last_run_completion is not None+ assert updated_agent.last_run_duration_ms == 1500++ # Update with error stop reason+ update_request = UpdateAgent(+ last_stop_reason=StopReasonType.error,+ last_run_completion=datetime.now(timezone.utc),+ last_run_duration_ms=2500,+ )+ updated_agent = await server.agent_manager.update_agent_async(agent.id, update_request, actor=default_user)++ assert updated_agent.last_stop_reason == StopReasonType.error+ assert updated_agent.last_run_duration_ms == 2500++ # Update with requires_approval stop reason+ update_request = UpdateAgent(+ last_stop_reason=StopReasonType.requires_approval,+ )+ updated_agent = await server.agent_manager.update_agent_async(agent.id, update_request, actor=default_user)++ assert updated_agent.last_stop_reason == StopReasonType.requires_approval++# ======================================================================================================================# AgentManager Tests - Listing# ======================================================================================================================@@ -1086,6 +1126,7 @@ async def test_agent_state_schema_unchanged(server: SyncServer):# Run metrics"last_run_completion": (datetime, type(None)),"last_run_duration_ms": (int, type(None)),+ "last_stop_reason": (StopReasonType, type(None)),# Timezone"timezone": (str, type(None)),# File controlsdiff --git a/tests/managers/test_run_manager.py b/tests/managers/test_run_manager.pyindex 403af0de7..01c4b2361 100644--- a/tests/managers/test_run_manager.py+++ b/tests/managers/test_run_manager.py@@ -232,6 +232,41 @@ async def test_update_run_metadata_persistence(server: SyncServer, sarah_agent,assert fetched_run.metadata["error"]["type"] == "llm_timeout"+async def test_update_run_updates_agent_last_stop_reason(server: SyncServer, sarah_agent, default_user):+ """Test that completing a run updates the agent's last_stop_reason."""++ # Verify agent starts with no last_stop_reason+ agent = await server.agent_manager.get_agent_by_id_async(agent_id=sarah_agent.id, actor=default_user)+ initial_stop_reason = agent.last_stop_reason++ # Create a run+ run_data = PydanticRun(agent_id=sarah_agent.id)+ created_run = await server.run_manager.create_run(pydantic_run=run_data, actor=default_user)++ # Complete the run with end_turn stop reason+ await server.run_manager.update_run_by_id_async(+ created_run.id, RunUpdate(status=RunStatus.completed, stop_reason=StopReasonType.end_turn), actor=default_user+ )++ # Verify agent's last_stop_reason was updated to end_turn+ updated_agent = await server.agent_manager.get_agent_by_id_async(agent_id=sarah_agent.id, actor=default_user)+ assert updated_agent.last_stop_reason == StopReasonType.end_turn++ # Create another run and complete with different stop reason+ run_data2 = PydanticRun(agent_id=sarah_agent.id)+ created_run2 = await server.run_manager.create_run(pydantic_run=run_data2, actor=default_user)++ # Complete with error stop reason+ await server.run_manager.update_run_by_id_async(+ created_run2.id, RunUpdate(status=RunStatus.failed, stop_reason=StopReasonType.error), actor=default_user+ )++ # Verify agent's last_stop_reason was updated to error+ final_agent = await server.agent_manager.get_agent_by_id_async(agent_id=sarah_agent.id, actor=default_user)+ assert final_agent.last_stop_reason == StopReasonType.error++@pytest.mark.asyncioasync def test_delete_run_by_id(server: SyncServer, sarah_agent, default_user):"""Test deleting a run by its ID."""diff --git a/tests/sdk_v1/integration/integration_test_human_in_the_loop.py b/tests/sdk_v1/integration/integration_test_human_in_the_loop.pyindex 2b9455157..6b2c6a08c 100644--- a/tests/sdk_v1/integration/integration_test_human_in_the_loop.py+++ b/tests/sdk_v1/integration/integration_test_human_in_the_loop.py@@ -1179,3 +1179,50 @@ def test_parallel_tool_calling(assert messages[1].message_type == "assistant_message"assert messages[2].message_type == "stop_reason"assert messages[3].message_type == "usage_statistics"+++def test_agent_records_last_stop_reason_after_approval_flow(+ client: Letta,+ agent: AgentState,+) -> None:+ """+ Test that the agent's last_stop_reason is properly updated after a human-in-the-loop flow.+ This verifies the integration between run completion and agent state updates.+ """+ # Get initial agent state+ initial_agent = client.agents.retrieve(agent_id=agent.id)+ initial_stop_reason = initial_agent.last_stop_reason++ # Trigger approval request+ response = client.agents.messages.send(+ agent_id=agent.id,+ messages=USER_MESSAGE_TEST_APPROVAL,+ )++ # Verify we got an approval request+ messages = response.messages+ assert messages is not None+ assert len(messages) == 3+ assert messages[2].message_type == "approval_request_message"++ # Check agent after approval request (run should be paused with requires_approval)+ agent_after_request = client.agents.retrieve(agent_id=agent.id)+ assert agent_after_request.last_stop_reason == "requires_approval"++ # Approve the tool call+ approve_tool_call(client, agent.id, response.messages[2].tool_call.tool_call_id)++ # Check agent after approval (run should complete with end_turn or similar)+ agent_after_approval = client.agents.retrieve(agent_id=agent.id)+ assert agent_after_approval.last_stop_reason is not None+ assert agent_after_approval.last_stop_reason != initial_stop_reason++ # Send follow-up message to complete the flow+ response2 = client.agents.messages.send(+ agent_id=agent.id,+ messages=USER_MESSAGE_FOLLOW_UP,+ )++ # Verify final agent state has the most recent stop reason+ final_agent = client.agents.retrieve(agent_id=agent.id)+ assert final_agent.last_stop_reason is not None