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 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.py
index 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 json
import traceback
from datetime import datetime
from 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, status
from fastapi.responses import JSONResponse
+from marshmallow import ValidationError
from pydantic import Field
+from sqlalchemy.exc import IntegrityError, OperationalError
from letta.constants import DEFAULT_MESSAGE_TOOL, DEFAULT_MESSAGE_TOOL_KWARG
from 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.py
index 5efba24b1..1a533d43c 100644
--- a/tests/test_agent_serialization.py
+++ b/tests/test_agent_serialization.py
@@ -1,9 +1,11 @@
import difflib
import json
from datetime import datetime, timezone
+from io import BytesIO
from typing import Any, Dict, List, Mapping
import pytest
+from fastapi.testclient import TestClient
from rich.console import Console
from rich.syntax import Syntax
@@ -18,6 +20,7 @@ from letta.schemas.llm_config import LLMConfig
from letta.schemas.message import MessageCreate
from letta.schemas.organization import Organization
from letta.schemas.user import User
+from letta.server.rest_api.app import app
from letta.server.server import SyncServer
console = 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 > 0
assert 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!")],
+ )