Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: Add upload/download endpoints for agents (#1200)
Matthew Zhou63dba5b0ab15
diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.pyindex 7afcc22b1..3814aaa20 100644--- a/letta/server/rest_api/routers/v1/agents.py+++ b/letta/server/rest_api/routers/v1/agents.py@@ -1,10 +1,13 @@+import jsonimport tracebackfrom datetime import datetimefrom typing import Annotated, List, Optional-from fastapi import APIRouter, BackgroundTasks, Body, Depends, Header, HTTPException, Query, status+from fastapi import APIRouter, BackgroundTasks, Body, Depends, File, Header, HTTPException, Query, UploadFile, statusfrom fastapi.responses import JSONResponse+from marshmallow import ValidationErrorfrom pydantic import Field+from sqlalchemy.exc import IntegrityError, OperationalErrorfrom letta.constants import DEFAULT_MESSAGE_TOOL, DEFAULT_MESSAGE_TOOL_KWARGfrom letta.log import get_logger@@ -88,6 +91,59 @@ def list_agents(return agents[email protected]("/{agent_id}/download", response_model=None, operation_id="download_agent_serialized")+def download_agent_serialized(+ agent_id: str,+ server: "SyncServer" = Depends(get_letta_server),+ actor_id: Optional[str] = Header(None, alias="user_id"),+):+ """+ Download the serialized JSON representation of an agent.+ """+ actor = server.user_manager.get_user_or_default(user_id=actor_id)++ try:+ serialized_agent = server.agent_manager.serialize(agent_id=agent_id, actor=actor)+ return JSONResponse(content=serialized_agent, media_type="application/json")+ except NoResultFound:+ raise HTTPException(status_code=404, detail=f"Agent with id={agent_id} not found for user_id={actor.id}.")++[email protected]("/upload", response_model=AgentState, operation_id="upload_agent_serialized")+async def upload_agent_serialized(+ file: UploadFile = File(...),+ server: "SyncServer" = Depends(get_letta_server),+ actor_id: Optional[str] = Header(None, alias="user_id"),+ mark_as_copy: bool = Query(True, description="Whether to mark the uploaded agent as a copy"),+):+ """+ Upload a serialized agent JSON file and recreate the agent in the system.+ """+ actor = server.user_manager.get_user_or_default(user_id=actor_id)++ try:+ serialized_data = await file.read()+ agent_json = json.loads(serialized_data)+ new_agent = server.agent_manager.deserialize(serialized_agent=agent_json, actor=actor, mark_as_copy=mark_as_copy)+ return new_agent++ except json.JSONDecodeError:+ raise HTTPException(status_code=400, detail="Corrupted agent file format.")++ except ValidationError as e:+ raise HTTPException(status_code=422, detail=f"Invalid agent schema: {str(e)}")++ except IntegrityError as e:+ raise HTTPException(status_code=409, detail=f"Database integrity error: {str(e)}")++ except OperationalError as e:+ raise HTTPException(status_code=503, detail=f"Database connection error. Please try again later: {str(e)}")++ except Exception:+ traceback.print_exc()+ raise HTTPException(status_code=500, detail="An unexpected error occurred while uploading the agent.")++@router.get("/{agent_id}/context", response_model=ContextWindowOverview, operation_id="retrieve_agent_context_window")def retrieve_agent_context_window(agent_id: str,diff --git a/tests/test_agent_serialization.py b/tests/test_agent_serialization.pyindex 5efba24b1..1a533d43c 100644--- a/tests/test_agent_serialization.py+++ b/tests/test_agent_serialization.py@@ -1,9 +1,11 @@import difflibimport jsonfrom datetime import datetime, timezone+from io import BytesIOfrom typing import Any, Dict, List, Mappingimport pytest+from fastapi.testclient import TestClientfrom rich.console import Consolefrom rich.syntax import Syntax@@ -18,6 +20,7 @@ from letta.schemas.llm_config import LLMConfigfrom letta.schemas.message import MessageCreatefrom letta.schemas.organization import Organizationfrom letta.schemas.user import User+from letta.server.rest_api.app import appfrom letta.server.server import SyncServerconsole = Console()@@ -32,6 +35,12 @@ def _clear_tables():session.commit()+def fastapi_client():+ """Fixture to create a FastAPI test client."""+ return TestClient(app)++@pytest.fixture(autouse=True)def clear_tables():_clear_tables()@@ -419,3 +428,50 @@ def test_agent_serialize_tool_calls(mock_e2b_api_key_none, local_client, server,assert original_agent_response.completion_tokens > 0 and original_agent_response.step_count > 0assert copy_agent_response.completion_tokens > 0 and copy_agent_response.step_count > 0+++# FastAPI endpoint tests++[email protected]("mark_as_copy", [True])+def test_agent_download_upload_flow(fastapi_client, server, serialize_test_agent, default_user, other_user, mark_as_copy):+ """+ Test the full E2E serialization and deserialization flow using FastAPI endpoints.+ """+ agent_id = serialize_test_agent.id++ # Step 1: Download the serialized agent+ response = fastapi_client.get(f"/v1/agents/{agent_id}/download", headers={"user_id": default_user.id})+ assert response.status_code == 200, f"Download failed: {response.text}"++ agent_json = response.json()++ # Step 2: Upload the serialized agent as a copy+ agent_bytes = BytesIO(json.dumps(agent_json).encode("utf-8"))+ files = {"file": ("agent.json", agent_bytes, "application/json")}+ upload_response = fastapi_client.post(+ "/v1/agents/upload",+ headers={"user_id": other_user.id},+ params={"mark_as_copy": mark_as_copy},+ files=files,+ )+ assert upload_response.status_code == 200, f"Upload failed: {upload_response.text}"++ # Sanity checks+ copied_agent = upload_response.json()+ copied_agent_id = copied_agent["id"]+ assert copied_agent_id != agent_id, "Copied agent should have a different ID"+ assert copied_agent["name"] == serialize_test_agent.name + "_copy", "Copied agent name should have '_copy' suffix"++ # Step 3: Retrieve the copied agent+ serialize_test_agent = server.agent_manager.get_agent_by_id(agent_id=serialize_test_agent.id, actor=default_user)+ agent_copy = server.agent_manager.get_agent_by_id(agent_id=copied_agent_id, actor=other_user)+ print_dict_diff(json.loads(serialize_test_agent.model_dump_json()), json.loads(agent_copy.model_dump_json()))+ assert compare_agent_state(agent_copy, serialize_test_agent, mark_as_copy=mark_as_copy)++ # Step 4: Ensure copied agent receives messages correctly+ server.send_messages(+ actor=other_user,+ agent_id=copied_agent_id,+ messages=[MessageCreate(role=MessageRole.user, content="Hello copied agent!")],+ )