Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add status to runs api [PRO-1529] (#5214)
Shelley Pham346db5ce604f
diff --git a/fern/openapi.json b/fern/openapi.jsonindex 5a86162e0..d04395fbd 100644--- a/fern/openapi.json+++ b/fern/openapi.json@@ -10185,6 +10185,27 @@"description": "The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field.","deprecated": true},+ {+ "name": "statuses",+ "in": "query",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ {+ "type": "null"+ }+ ],+ "description": "Filter runs by status. Can specify multiple statuses.",+ "title": "Statuses"+ },+ "description": "Filter runs by status. Can specify multiple statuses."+ },{"name": "background","in": "query",diff --git a/letta/server/rest_api/routers/v1/runs.py b/letta/server/rest_api/routers/v1/runs.pyindex 913a2a891..083b09dbb 100644--- a/letta/server/rest_api/routers/v1/runs.py+++ b/letta/server/rest_api/routers/v1/runs.py@@ -29,6 +29,20 @@ from letta.settings import settingsrouter = APIRouter(prefix="/runs", tags=["runs"])+def convert_statuses_to_enum(statuses: Optional[List[str]]) -> Optional[List[RunStatus]]:+ """Convert a list of status strings to RunStatus enum values.++ Args:+ statuses: List of status strings or None++ Returns:+ List of RunStatus enum values or None if input is None+ """+ if statuses is None:+ return None+ return [RunStatus(status) for status in statuses]++@router.get("/", response_model=List[Run], operation_id="list_runs")async def list_runs(server: "SyncServer" = Depends(get_letta_server),@@ -38,6 +52,7 @@ async def list_runs(description="The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field.",deprecated=True,),+ statuses: Optional[List[str]] = Query(None, description="Filter runs by status. Can specify multiple statuses."),background: Optional[bool] = Query(None, description="If True, filters for runs that were created in background mode."),stop_reason: Optional[StopReasonType] = Query(None, description="Filter runs by stop reason."),before: Optional[str] = Query(@@ -65,9 +80,10 @@ async def list_runs(actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)runs_manager = RunManager()- statuses = None- if active:+ # Handle backwards compatibility: if statuses not provided but active=True, filter by active statuses+ if statuses is None and active:statuses = [RunStatus.created, RunStatus.running]+if agent_id:# NOTE: we are deprecating agent_ids so this will the primary path soonagent_ids = [agent_id]@@ -80,10 +96,13 @@ async def list_runs(# Use the new order parametersort_ascending = order == "asc"+ # Convert string statuses to RunStatus enum+ parsed_statuses = convert_statuses_to_enum(statuses)+runs = await runs_manager.list_runs(actor=actor,agent_ids=agent_ids,- statuses=statuses,+ statuses=parsed_statuses,limit=limit,before=before,after=after,diff --git a/tests/managers/test_run_manager.py b/tests/managers/test_run_manager.pyindex ffefd733b..3994735c6 100644--- a/tests/managers/test_run_manager.py+++ b/tests/managers/test_run_manager.py@@ -1146,3 +1146,137 @@ async def test_get_run_request_config_nonexistent_run(server: SyncServer, defaul# # Try to record response duration for non-existent job - should not raise exception but log warning# await server.job_manager.record_response_duration("nonexistent_job_id", 2_000_000_000, default_user)#+++# ======================================================================================================================+# convert_statuses_to_enum Tests+# ======================================================================================================================+++def test_convert_statuses_to_enum_with_none():+ """Test that convert_statuses_to_enum returns None when input is None."""+ from letta.server.rest_api.routers.v1.runs import convert_statuses_to_enum++ result = convert_statuses_to_enum(None)+ assert result is None+++def test_convert_statuses_to_enum_with_single_status():+ """Test converting a single status string to RunStatus enum."""+ from letta.server.rest_api.routers.v1.runs import convert_statuses_to_enum++ result = convert_statuses_to_enum(["completed"])+ assert result == [RunStatus.completed]+ assert len(result) == 1+++def test_convert_statuses_to_enum_with_multiple_statuses():+ """Test converting multiple status strings to RunStatus enums."""+ from letta.server.rest_api.routers.v1.runs import convert_statuses_to_enum++ result = convert_statuses_to_enum(["created", "running", "completed"])+ assert result == [RunStatus.created, RunStatus.running, RunStatus.completed]+ assert len(result) == 3+++def test_convert_statuses_to_enum_with_all_statuses():+ """Test converting all possible status strings."""+ from letta.server.rest_api.routers.v1.runs import convert_statuses_to_enum++ all_statuses = ["created", "running", "completed", "failed", "cancelled"]+ result = convert_statuses_to_enum(all_statuses)+ assert result == [RunStatus.created, RunStatus.running, RunStatus.completed, RunStatus.failed, RunStatus.cancelled]+ assert len(result) == 5+++def test_convert_statuses_to_enum_with_empty_list():+ """Test converting an empty list."""+ from letta.server.rest_api.routers.v1.runs import convert_statuses_to_enum++ result = convert_statuses_to_enum([])+ assert result == []+++def test_convert_statuses_to_enum_with_invalid_status():+ """Test that invalid status strings raise ValueError."""+ from letta.server.rest_api.routers.v1.runs import convert_statuses_to_enum++ with pytest.raises(ValueError):+ convert_statuses_to_enum(["invalid_status"])+++async def test_list_runs_with_multiple_statuses(server: SyncServer, sarah_agent, default_user):+ """Test listing runs with multiple status filters."""+ # Create runs with different statuses+ run_created = await server.run_manager.create_run(+ pydantic_run=PydanticRun(+ status=RunStatus.created,+ agent_id=sarah_agent.id,+ metadata={"type": "created"},+ ),+ actor=default_user,+ )+ run_running = await server.run_manager.create_run(+ pydantic_run=PydanticRun(+ status=RunStatus.running,+ agent_id=sarah_agent.id,+ metadata={"type": "running"},+ ),+ actor=default_user,+ )+ run_completed = await server.run_manager.create_run(+ pydantic_run=PydanticRun(+ status=RunStatus.completed,+ agent_id=sarah_agent.id,+ metadata={"type": "completed"},+ ),+ actor=default_user,+ )+ run_failed = await server.run_manager.create_run(+ pydantic_run=PydanticRun(+ status=RunStatus.failed,+ agent_id=sarah_agent.id,+ metadata={"type": "failed"},+ ),+ actor=default_user,+ )++ # Test filtering by multiple statuses+ active_runs = await server.run_manager.list_runs(+ actor=default_user, statuses=[RunStatus.created, RunStatus.running], agent_id=sarah_agent.id+ )+ assert len(active_runs) == 2+ assert all(run.status in [RunStatus.created, RunStatus.running] for run in active_runs)++ # Test filtering by terminal statuses+ terminal_runs = await server.run_manager.list_runs(+ actor=default_user, statuses=[RunStatus.completed, RunStatus.failed], agent_id=sarah_agent.id+ )+ assert len(terminal_runs) == 2+ assert all(run.status in [RunStatus.completed, RunStatus.failed] for run in terminal_runs)+++async def test_list_runs_with_no_status_filter_returns_all(server: SyncServer, sarah_agent, default_user):+ """Test that not providing statuses parameter returns all runs."""+ # Create runs with different statuses+ await server.run_manager.create_run(pydantic_run=PydanticRun(status=RunStatus.created, agent_id=sarah_agent.id), actor=default_user)+ await server.run_manager.create_run(pydantic_run=PydanticRun(status=RunStatus.running, agent_id=sarah_agent.id), actor=default_user)+ await server.run_manager.create_run(pydantic_run=PydanticRun(status=RunStatus.completed, agent_id=sarah_agent.id), actor=default_user)+ await server.run_manager.create_run(pydantic_run=PydanticRun(status=RunStatus.failed, agent_id=sarah_agent.id), actor=default_user)+ await server.run_manager.create_run(pydantic_run=PydanticRun(status=RunStatus.cancelled, agent_id=sarah_agent.id), actor=default_user)++ # List all runs without status filter+ all_runs = await server.run_manager.list_runs(actor=default_user, agent_id=sarah_agent.id)++ # Should return all 5 runs+ assert len(all_runs) >= 5++ # Verify we have all statuses represented+ statuses_found = {run.status for run in all_runs}+ assert RunStatus.created in statuses_found+ assert RunStatus.running in statuses_found+ assert RunStatus.completed in statuses_found+ assert RunStatus.failed in statuses_found+ assert RunStatus.cancelled in statuses_founddiff --git a/tests/test_run_status_conversion.py b/tests/test_run_status_conversion.pynew file mode 100644index 000000000..cace820d4--- /dev/null+++ b/tests/test_run_status_conversion.py@@ -0,0 +1,80 @@+"""+Unit tests for the convert_statuses_to_enum function in the runs API router.++These tests verify that status string conversion to RunStatus enums works correctly.+"""++import pytest++from letta.schemas.enums import RunStatus+from letta.server.rest_api.routers.v1.runs import convert_statuses_to_enum+++def test_convert_statuses_to_enum_with_none():+ """Test that convert_statuses_to_enum returns None when input is None."""+ result = convert_statuses_to_enum(None)+ assert result is None+++def test_convert_statuses_to_enum_with_single_status():+ """Test converting a single status string to RunStatus enum."""+ result = convert_statuses_to_enum(["completed"])+ assert result == [RunStatus.completed]+ assert len(result) == 1+++def test_convert_statuses_to_enum_with_multiple_statuses():+ """Test converting multiple status strings to RunStatus enums."""+ result = convert_statuses_to_enum(["created", "running", "completed"])+ assert result == [RunStatus.created, RunStatus.running, RunStatus.completed]+ assert len(result) == 3+++def test_convert_statuses_to_enum_with_all_statuses():+ """Test converting all possible status strings."""+ all_statuses = ["created", "running", "completed", "failed", "cancelled"]+ result = convert_statuses_to_enum(all_statuses)+ assert result == [RunStatus.created, RunStatus.running, RunStatus.completed, RunStatus.failed, RunStatus.cancelled]+ assert len(result) == 5+++def test_convert_statuses_to_enum_with_empty_list():+ """Test converting an empty list."""+ result = convert_statuses_to_enum([])+ assert result == []+++def test_convert_statuses_to_enum_with_invalid_status():+ """Test that invalid status strings raise ValueError."""+ with pytest.raises(ValueError):+ convert_statuses_to_enum(["invalid_status"])+++def test_convert_statuses_to_enum_preserves_order():+ """Test that the order of statuses is preserved."""+ input_statuses = ["failed", "created", "completed", "running"]+ result = convert_statuses_to_enum(input_statuses)+ assert result == [RunStatus.failed, RunStatus.created, RunStatus.completed, RunStatus.running]+++def test_convert_statuses_to_enum_with_duplicate_statuses():+ """Test that duplicate statuses are preserved."""+ input_statuses = ["completed", "completed", "running"]+ result = convert_statuses_to_enum(input_statuses)+ assert result == [RunStatus.completed, RunStatus.completed, RunStatus.running]+ assert len(result) == 3+++def test_convert_statuses_to_enum_case_sensitivity():+ """Test that the function is case-sensitive and requires exact matches."""+ with pytest.raises(ValueError):+ convert_statuses_to_enum(["COMPLETED"])++ with pytest.raises(ValueError):+ convert_statuses_to_enum(["Completed"])+++def test_convert_statuses_to_enum_with_mixed_valid_invalid():+ """Test that if any status is invalid, the entire conversion fails."""+ with pytest.raises(ValueError):+ convert_statuses_to_enum(["completed", "invalid", "running"])