Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: error handling for rest api for agents + blocks [LET-4625] (#5142)
Sarah Wooders7aff9aa659d0
diff --git a/letta/errors.py b/letta/errors.pyindex 1d154d318..1d753d35d 100644--- a/letta/errors.py+++ b/letta/errors.py@@ -97,6 +97,34 @@ class LettaUserNotFoundError(LettaError):"""Error raised when a user is not found."""+class LettaInvalidArgumentError(LettaError):+ """Error raised when an invalid argument is provided."""++ def __init__(self, message: str, argument_name: Optional[str] = None):+ details = {"argument_name": argument_name} if argument_name else {}+ super().__init__(message=message, code=ErrorCode.INVALID_ARGUMENT, details=details)+++class LettaMCPError(LettaError):+ """Base error for MCP-related issues."""+++class LettaMCPConnectionError(LettaMCPError):+ """Error raised when unable to connect to MCP server."""++ def __init__(self, message: str, server_name: Optional[str] = None):+ details = {"server_name": server_name} if server_name else {}+ super().__init__(message=message, code=ErrorCode.INTERNAL_SERVER_ERROR, details=details)+++class LettaMCPTimeoutError(LettaMCPError):+ """Error raised when MCP server operation times out."""++ def __init__(self, message: str, server_name: Optional[str] = None):+ details = {"server_name": server_name} if server_name else {}+ super().__init__(message=message, code=ErrorCode.TIMEOUT, details=details)++class LettaUnexpectedStreamCancellationError(LettaError):"""Error raised when a streaming request is terminated unexpectedly."""diff --git a/letta/server/rest_api/app.py b/letta/server/rest_api/app.pyindex 6123c1930..3cda0a64e 100644--- a/letta/server/rest_api/app.py+++ b/letta/server/rest_api/app.py@@ -12,14 +12,23 @@ from typing import Optionalimport uvicornfrom fastapi import FastAPI, Requestfrom fastapi.responses import JSONResponse+from marshmallow import ValidationError+from sqlalchemy.exc import IntegrityError, OperationalErrorfrom starlette.middleware.cors import CORSMiddlewarefrom letta.__init__ import __version__ as letta_versionfrom letta.agents.exceptions import IncompatibleAgentTypefrom letta.constants import ADMIN_PREFIX, API_PREFIX, OPENAI_API_PREFIXfrom letta.errors import (+ AgentExportIdMappingError,+ AgentExportProcessingError,+ AgentFileImportError,+ AgentNotFoundForExportError,BedrockPermissionError,LettaAgentNotFoundError,+ LettaInvalidArgumentError,+ LettaMCPConnectionError,+ LettaMCPTimeoutError,LettaToolCreateError,LettaToolNameConflictError,LettaUserNotFoundError,@@ -234,16 +243,41 @@ def create_application() -> "FastAPI":_error_handler_404 = partial(error_handler_with_code, code=404)_error_handler_404_agent = partial(_error_handler_404, detail="Agent not found")_error_handler_404_user = partial(_error_handler_404, detail="User not found")+ _error_handler_408 = partial(error_handler_with_code, code=408)_error_handler_409 = partial(error_handler_with_code, code=409)+ _error_handler_422 = partial(error_handler_with_code, code=422)+ _error_handler_500 = partial(error_handler_with_code, code=500)+ _error_handler_503 = partial(error_handler_with_code, code=503)- app.add_exception_handler(ValueError, _error_handler_400)+ # 400 Bad Request errors+ app.add_exception_handler(LettaInvalidArgumentError, _error_handler_400)+ app.add_exception_handler(LettaToolCreateError, _error_handler_400)+ app.add_exception_handler(LettaToolNameConflictError, _error_handler_400)+ app.add_exception_handler(AgentFileImportError, _error_handler_400)++ # 404 Not Found errorsapp.add_exception_handler(NoResultFound, _error_handler_404)app.add_exception_handler(LettaAgentNotFoundError, _error_handler_404_agent)app.add_exception_handler(LettaUserNotFoundError, _error_handler_404_user)+ app.add_exception_handler(AgentNotFoundForExportError, _error_handler_404)++ # 408 Timeout errors+ app.add_exception_handler(LettaMCPTimeoutError, _error_handler_408)++ # 409 Conflict errorsapp.add_exception_handler(ForeignKeyConstraintViolationError, _error_handler_409)app.add_exception_handler(UniqueConstraintViolationError, _error_handler_409)- app.add_exception_handler(LettaToolCreateError, _error_handler_400)- app.add_exception_handler(LettaToolNameConflictError, _error_handler_400)+ app.add_exception_handler(IntegrityError, _error_handler_409)++ # 422 Validation errors+ app.add_exception_handler(ValidationError, _error_handler_422)++ # 500 Internal Server errors+ app.add_exception_handler(AgentExportIdMappingError, _error_handler_500)+ app.add_exception_handler(AgentExportProcessingError, _error_handler_500)++ # 503 Service Unavailable errors+ app.add_exception_handler(OperationalError, _error_handler_503)@app.exception_handler(IncompatibleAgentType)async def handle_incompatible_agent_type(request: Request, exc: IncompatibleAgentType):@@ -327,6 +361,19 @@ def create_application() -> "FastAPI":},)+ @app.exception_handler(LettaMCPConnectionError)+ async def mcp_connection_error_handler(request: Request, exc: LettaMCPConnectionError):+ return JSONResponse(+ status_code=502,+ content={+ "error": {+ "type": "mcp_connection_error",+ "message": "Failed to connect to MCP server.",+ "detail": str(exc),+ }+ },+ )+@app.exception_handler(LLMError)async def llm_error_handler(request: Request, exc: LLMError):return JSONResponse(diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.pyindex f7860ca4b..175da3b0e 100644--- a/letta/server/rest_api/routers/v1/agents.py+++ b/letta/server/rest_api/routers/v1/agents.py@@ -195,24 +195,12 @@ async def export_agent(if use_legacy_format:# Use the legacy serialization method- try:- agent = await server.agent_manager.serialize(agent_id=agent_id, actor=actor, max_steps=max_steps)- return agent.model_dump()- except NoResultFound:- raise HTTPException(status_code=404, detail=f"Agent with id={agent_id} not found for user_id={actor.id}.")+ agent = await server.agent_manager.serialize(agent_id=agent_id, actor=actor, max_steps=max_steps)+ return agent.model_dump()else:# Use the new multi-entity export format- try:- agent_file_schema = await server.agent_serialization_manager.export(agent_ids=[agent_id], actor=actor)- return agent_file_schema.model_dump()- except AgentNotFoundForExportError:- raise HTTPException(status_code=404, detail=f"Agent with id={agent_id} not found for user_id={actor.id}.")- except AgentExportIdMappingError as e:- raise HTTPException(- status_code=500, detail=f"Internal error during export: ID mapping failed for {e.entity_type} ID '{e.db_id}'"- )- except AgentExportProcessingError as e:- raise HTTPException(status_code=500, detail=f"Export processing failed: {str(e.original_error)}")+ agent_file_schema = await server.agent_serialization_manager.export(agent_ids=[agent_id], actor=actor)+ return agent_file_schema.model_dump()class ImportedAgentsResponse(BaseModel):@@ -234,33 +222,19 @@ def import_agent_legacy("""Import an agent using the legacy AgentSchema format."""- try:- # Validate the JSON against AgentSchema before passing it to deserialize- agent_schema = AgentSchema.model_validate(agent_json)+ # Validate the JSON against AgentSchema before passing it to deserialize+ agent_schema = AgentSchema.model_validate(agent_json)- new_agent = server.agent_manager.deserialize(- serialized_agent=agent_schema, # Ensure we're passing a validated AgentSchema- actor=actor,- append_copy_suffix=append_copy_suffix,- override_existing_tools=override_existing_tools,- project_id=project_id,- strip_messages=strip_messages,- env_vars=env_vars,- )- return [new_agent.id]-- except ValidationError as e:- raise HTTPException(status_code=422, detail=f"Invalid agent schema: {e!s}")-- except IntegrityError as e:- raise HTTPException(status_code=409, detail=f"Database integrity error: {e!s}")-- except OperationalError as e:- raise HTTPException(status_code=503, detail=f"Database connection error. Please try again later: {e!s}")-- except Exception as e:- traceback.print_exc()- raise HTTPException(status_code=500, detail=f"An unexpected error occurred while uploading the agent: {e!s}")+ new_agent = server.agent_manager.deserialize(+ serialized_agent=agent_schema, # Ensure we're passing a validated AgentSchema+ actor=actor,+ append_copy_suffix=append_copy_suffix,+ override_existing_tools=override_existing_tools,+ project_id=project_id,+ strip_messages=strip_messages,+ env_vars=env_vars,+ )+ return [new_agent.id]async def _import_agent(@@ -278,46 +252,29 @@ async def _import_agent("""Import an agent using the new AgentFileSchema format."""- try:- agent_schema = AgentFileSchema.model_validate(agent_file_json)- except ValidationError as e:- raise HTTPException(status_code=422, detail=f"Invalid agent file schema: {e!s}")-- try:- if override_embedding_handle:- embedding_config_override = await server.get_cached_embedding_config_async(actor=actor, handle=override_embedding_handle)- else:- embedding_config_override = None-- import_result = await server.agent_serialization_manager.import_file(- schema=agent_schema,- actor=actor,- append_copy_suffix=append_copy_suffix,- override_existing_tools=override_existing_tools,- env_vars=env_vars,- override_embedding_config=embedding_config_override,- project_id=project_id,- )-- if not import_result.success:- raise HTTPException(- status_code=500, detail=f"Import failed: {import_result.message}. Errors: {', '.join(import_result.errors)}"- )+ agent_schema = AgentFileSchema.model_validate(agent_file_json)- return import_result.imported_agent_ids+ if override_embedding_handle:+ embedding_config_override = await server.get_cached_embedding_config_async(actor=actor, handle=override_embedding_handle)+ else:+ embedding_config_override = None- except AgentFileImportError as e:- raise HTTPException(status_code=400, detail=f"Agent file import error: {str(e)}")+ import_result = await server.agent_serialization_manager.import_file(+ schema=agent_schema,+ actor=actor,+ append_copy_suffix=append_copy_suffix,+ override_existing_tools=override_existing_tools,+ env_vars=env_vars,+ override_embedding_config=embedding_config_override,+ project_id=project_id,+ )- except IntegrityError as e:- raise HTTPException(status_code=409, detail=f"Database integrity error: {e!s}")+ if not import_result.success:+ from letta.errors import AgentFileImportError- except OperationalError as e:- raise HTTPException(status_code=503, detail=f"Database connection error. Please try again later: {e!s}")+ raise AgentFileImportError(f"Import failed: {import_result.message}. Errors: {', '.join(import_result.errors)}")- except Exception as e:- traceback.print_exc()- raise HTTPException(status_code=500, detail=f"An unexpected error occurred while importing agents: {e!s}")+ return import_result.imported_agent_ids@router.post("/import", response_model=ImportedAgentsResponse, operation_id="import_agent")@@ -405,11 +362,7 @@ async def retrieve_agent_context_window(Retrieve the context window of a specific agent."""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- try:- return await server.agent_manager.get_context_window(agent_id=agent_id, actor=actor)- except Exception as e:- traceback.print_exc()- raise e+ return await server.agent_manager.get_context_window(agent_id=agent_id, actor=actor)class CreateAgentRequest(CreateAgent):@@ -433,14 +386,10 @@ async def create_agent("""Create an agent."""- try:- actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- if headers.experimental_params.letta_v1_agent and agent.agent_type == AgentType.memgpt_v2_agent:- agent.agent_type = AgentType.letta_v1_agent- return await server.create_agent_async(agent, actor=actor)- except Exception as e:- traceback.print_exc()- raise HTTPException(status_code=500, detail=str(e))+ actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)+ if headers.experimental_params.letta_v1_agent and agent.agent_type == AgentType.memgpt_v2_agent:+ agent.agent_type = AgentType.letta_v1_agent+ return await server.create_agent_async(agent, actor=actor)@router.patch("/{agent_id}", response_model=AgentState, operation_id="modify_agent")@@ -683,12 +632,9 @@ async def open_file(actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)# Get the agent to access files configuration- try:- per_file_view_window_char_limit, max_files_open = await server.agent_manager.get_agent_files_config_async(- agent_id=agent_id, actor=actor- )- except ValueError:- raise HTTPException(status_code=404, detail=f"Agent with id={agent_id} not found")+ per_file_view_window_char_limit, max_files_open = await server.agent_manager.get_agent_files_config_async(+ agent_id=agent_id, actor=actor+ )# Get file metadatafile_metadata = await server.file_manager.get_file_by_id(file_id=file_id, actor=actor, include_content=True)@@ -734,16 +680,13 @@ async def close_file(actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)# Use update_file_agent_by_id to close the file- try:- await server.file_agent_manager.update_file_agent_by_id(- agent_id=agent_id,- file_id=file_id,- actor=actor,- is_open=False,- )- return JSONResponse(status_code=status.HTTP_200_OK, content={"message": f"File id={file_id} successfully closed"})- except NoResultFound:- raise HTTPException(status_code=404, detail=f"File association for file_id={file_id} and agent_id={agent_id} not found")+ await server.file_agent_manager.update_file_agent_by_id(+ agent_id=agent_id,+ file_id=file_id,+ actor=actor,+ is_open=False,+ )+ return JSONResponse(status_code=status.HTTP_200_OK, content={"message": f"File id={file_id} successfully closed"})@router.get("/{agent_id}", response_model=AgentState, operation_id="retrieve_agent")@@ -769,10 +712,7 @@ async def retrieve_agent(actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- try:- return await server.agent_manager.get_agent_by_id_async(agent_id=agent_id, include_relationships=include_relationships, actor=actor)- except NoResultFound as e:- raise HTTPException(status_code=404, detail=str(e))+ return await server.agent_manager.get_agent_by_id_async(agent_id=agent_id, include_relationships=include_relationships, actor=actor)@router.delete("/{agent_id}", response_model=None, operation_id="delete_agent")@@ -785,11 +725,8 @@ async def delete_agent(Delete an agent."""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- try:- await server.agent_manager.delete_agent_async(agent_id=agent_id, actor=actor)- return JSONResponse(status_code=status.HTTP_200_OK, content={"message": f"Agent id={agent_id} successfully deleted"})- except NoResultFound:- raise HTTPException(status_code=404, detail=f"Agent agent_id={agent_id} not found for user_id={actor.id}.")+ await server.agent_manager.delete_agent_async(agent_id=agent_id, actor=actor)+ return JSONResponse(status_code=status.HTTP_200_OK, content={"message": f"Agent id={agent_id} successfully deleted"})@router.get("/{agent_id}/sources", response_model=list[Source], operation_id="list_agent_sources")@@ -889,10 +826,7 @@ async def retrieve_block("""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- try:- return await server.agent_manager.get_block_with_label_async(agent_id=agent_id, block_label=block_label, actor=actor)- except NoResultFound as e:- raise HTTPException(status_code=404, detail=str(e))+ return await server.agent_manager.get_block_with_label_async(agent_id=agent_id, block_label=block_label, actor=actor)@router.get("/{agent_id}/core-memory/blocks", response_model=list[Block], operation_id="list_core_memory_blocks")@@ -917,17 +851,14 @@ async def list_blocks("""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- try:- return await server.agent_manager.list_agent_blocks_async(- agent_id=agent_id,- actor=actor,- before=before,- after=after,- limit=limit,- ascending=(order == "asc"),- )- except NoResultFound:- raise HTTPException(status_code=404, detail="Agent not found")+ return await server.agent_manager.list_agent_blocks_async(+ agent_id=agent_id,+ actor=actor,+ before=before,+ after=after,+ limit=limit,+ ascending=(order == "asc"),+ )@router.patch("/{agent_id}/core-memory/blocks/{block_label}", response_model=Block, operation_id="modify_core_memory_block")@@ -1050,34 +981,26 @@ async def search_archival_memory("""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- try:- # convert datetime to string in ISO 8601 format- start_datetime = start_datetime.isoformat() if start_datetime else None- end_datetime = end_datetime.isoformat() if end_datetime else None-- # Use the shared agent manager method- formatted_results = await server.agent_manager.search_agent_archival_memory_async(- agent_id=agent_id,- actor=actor,- query=query,- tags=tags,- tag_match_mode=tag_match_mode,- top_k=top_k,- start_datetime=start_datetime,- end_datetime=end_datetime,- )+ # convert datetime to string in ISO 8601 format+ start_datetime = start_datetime.isoformat() if start_datetime else None+ end_datetime = end_datetime.isoformat() if end_datetime else None- # Convert to proper response schema- search_results = [ArchivalMemorySearchResult(**result) for result in formatted_results]+ # Use the shared agent manager method+ formatted_results = await server.agent_manager.search_agent_archival_memory_async(+ agent_id=agent_id,+ actor=actor,+ query=query,+ tags=tags,+ tag_match_mode=tag_match_mode,+ top_k=top_k,+ start_datetime=start_datetime,+ end_datetime=end_datetime,+ )- return ArchivalMemorySearchResponse(results=search_results, count=len(formatted_results))+ # Convert to proper response schema+ search_results = [ArchivalMemorySearchResult(**result) for result in formatted_results]- except NoResultFound as e:- raise HTTPException(status_code=404, detail=f"Agent with id={agent_id} not found for user_id={actor.id}.")- except ValueError as e:- raise HTTPException(status_code=400, detail=str(e))- except Exception as e:- raise HTTPException(status_code=500, detail=f"Internal server error during archival memory search: {str(e)}")+ return ArchivalMemorySearchResponse(results=search_results, count=len(formatted_results))# TODO(ethan): query or path parameter for memory_id?@@ -1572,21 +1495,18 @@ async def search_messages(if agent_count == 0:raise HTTPException(status_code=400, detail="No agents found in organization to derive embedding configuration from")- try:- results = await server.message_manager.search_messages_org_async(- actor=actor,- query_text=request.query,- search_mode=request.search_mode,- roles=request.roles,- project_id=request.project_id,- template_id=request.template_id,- limit=request.limit,- start_date=request.start_date,- end_date=request.end_date,- )- return results- except ValueError as e:- raise HTTPException(status_code=400, detail=str(e))+ results = await server.message_manager.search_messages_org_async(+ actor=actor,+ query_text=request.query,+ search_mode=request.search_mode,+ roles=request.roles,+ project_id=request.project_id,+ template_id=request.template_id,+ limit=request.limit,+ start_date=request.start_date,+ end_date=request.end_date,+ )+ return resultsasync def _process_message_background(diff --git a/letta/server/rest_api/routers/v1/blocks.py b/letta/server/rest_api/routers/v1/blocks.pyindex af9a8f86f..6c8ac280d 100644--- a/letta/server/rest_api/routers/v1/blocks.py+++ b/letta/server/rest_api/routers/v1/blocks.py@@ -154,13 +154,10 @@ async def retrieve_block(headers: HeaderParams = Depends(get_headers),):actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- try:- block = await server.block_manager.get_block_by_id_async(block_id=block_id, actor=actor)- if block is None:- raise HTTPException(status_code=404, detail="Block not found")- return block- except NoResultFound:- raise HTTPException(status_code=404, detail="Block not found")+ block = await server.block_manager.get_block_by_id_async(block_id=block_id, actor=actor)+ if block is None:+ raise NoResultFound(f"Block with id '{block_id}' not found")+ return block@router.get("/{block_id}/agents", response_model=List[AgentState], operation_id="list_agents_for_block")@@ -195,16 +192,13 @@ async def list_agents_for_block(Raises a 404 if the block does not exist."""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- try:- agents = await server.block_manager.get_agents_for_block_async(- block_id=block_id,- before=before,- after=after,- limit=limit,- ascending=(order == "asc"),- include_relationships=include_relationships,- actor=actor,- )- return agents- except NoResultFound:- raise HTTPException(status_code=404, detail=f"Block with id={block_id} not found")+ agents = await server.block_manager.get_agents_for_block_async(+ block_id=block_id,+ before=before,+ after=after,+ limit=limit,+ ascending=(order == "asc"),+ include_relationships=include_relationships,+ actor=actor,+ )+ return agentsdiff --git a/letta/server/server.py b/letta/server/server.pyindex b1be2dff8..69c298a0f 100644--- a/letta/server/server.py+++ b/letta/server/server.py@@ -19,7 +19,7 @@ import letta.system as systemfrom letta.config import LettaConfigfrom letta.constants import LETTA_TOOL_EXECUTION_DIRfrom letta.data_sources.connectors import DataConnector, load_data-from letta.errors import HandleNotFoundError+from letta.errors import HandleNotFoundError, LettaInvalidArgumentError, LettaMCPConnectionError, LettaMCPTimeoutErrorfrom letta.functions.mcp_client.types import MCPServerType, MCPTool, MCPToolHealth, SSEServerConfig, StdioServerConfigfrom letta.functions.schema_validator import validate_complete_json_schemafrom letta.groups.helpers import load_multi_agent@@ -363,7 +363,7 @@ class SyncServer(object):elif server_config.type == MCPServerType.STDIO:self.mcp_clients[server_name] = AsyncStdioMCPClient(server_config)else:- raise ValueError(f"Invalid MCP server config: {server_config}")+ raise LettaInvalidArgumentError(f"Invalid MCP server config: {server_config}", argument_name="server_config")try:await self.mcp_clients[server_name].connect_to_server()@@ -416,7 +416,7 @@ class SyncServer(object):if request.llm_config is None:if request.model is None:if settings.default_llm_handle is None:- raise ValueError("Must specify either model or llm_config in request")+ raise LettaInvalidArgumentError("Must specify either model or llm_config in request", argument_name="model")else:request.model = settings.default_llm_handleconfig_params = {@@ -436,7 +436,9 @@ class SyncServer(object):if request.embedding_config is None:if request.embedding is None:if settings.default_embedding_handle is None:- raise ValueError("Must specify either embedding or embedding_config in request")+ raise LettaInvalidArgumentError(+ "Must specify either embedding or embedding_config in request", argument_name="embedding"+ )else:request.embedding = settings.default_embedding_handleembedding_config_params = {@@ -760,7 +762,7 @@ class SyncServer(object):# TODO: move this into a threadsource = await self.source_manager.get_source_by_id(source_id=source_id)if source is None:- raise ValueError(f"Source {source_id} does not exist")+ raise NoResultFound(f"Source {source_id} does not exist")connector = DirectoryConnector(input_files=[file_path])num_passages, num_documents = await self.load_data(user_id=source.created_by_id, source_name=source.name, connector=connector)@@ -894,7 +896,7 @@ class SyncServer(object):actor = await self.user_manager.get_actor_by_id_async(actor_id=user_id)source = await self.source_manager.get_source_by_name(source_name=source_name, actor=actor)if source is None:- raise ValueError(f"Data source {source_name} does not exist for user {user_id}")+ raise NoResultFound(f"Data source {source_name} does not exist for user {user_id}")# load data into the document storepassage_count, document_count = await load_data(connector, source, self.passage_manager, self.file_manager, actor=actor)@@ -1042,13 +1044,18 @@ class SyncServer(object):if len(llm_configs) == 1:llm_config = llm_configs[0]elif len(llm_configs) > 1:- raise ValueError(f"Multiple LLM models with name {model_name} supported by {provider_name}")+ raise LettaInvalidArgumentError(+ f"Multiple LLM models with name {model_name} supported by {provider_name}", argument_name="model_name"+ )else:llm_config = llm_configs[0]if context_window_limit is not None:if context_window_limit > llm_config.context_window:- raise ValueError(f"Context window limit ({context_window_limit}) is greater than maximum of ({llm_config.context_window})")+ raise LettaInvalidArgumentError(+ f"Context window limit ({context_window_limit}) is greater than maximum of ({llm_config.context_window})",+ argument_name="context_window_limit",+ )llm_config.context_window = context_window_limitelse:llm_config.context_window = min(llm_config.context_window, model_settings.global_max_context_window_limit)@@ -1057,7 +1064,10 @@ class SyncServer(object):llm_config.max_tokens = max_tokensif max_reasoning_tokens is not None:if not max_tokens or max_reasoning_tokens > max_tokens:- raise ValueError(f"Max reasoning tokens ({max_reasoning_tokens}) must be less than max tokens ({max_tokens})")+ raise LettaInvalidArgumentError(+ f"Max reasoning tokens ({max_reasoning_tokens}) must be less than max tokens ({max_tokens})",+ argument_name="max_reasoning_tokens",+ )llm_config.max_reasoning_tokens = max_reasoning_tokensif enable_reasoner is not None:llm_config.enable_reasoner = enable_reasoner@@ -1077,8 +1087,10 @@ class SyncServer(object):all_embedding_configs = await provider.list_embedding_models_async()embedding_configs = [config for config in all_embedding_configs if config.handle == handle]if not embedding_configs:- raise ValueError(f"Embedding model {model_name} is not supported by {provider_name}")- except ValueError as e:+ raise LettaInvalidArgumentError(+ f"Embedding model {model_name} is not supported by {provider_name}", argument_name="model_name"+ )+ except LettaInvalidArgumentError as e:# search local configsembedding_configs = [config for config in self.get_local_embedding_configs() if config.handle == handle]if not embedding_configs:@@ -1087,7 +1099,9 @@ class SyncServer(object):if len(embedding_configs) == 1:embedding_config = embedding_configs[0]elif len(embedding_configs) > 1:- raise ValueError(f"Multiple embedding models with name {model_name} supported by {provider_name}")+ raise LettaInvalidArgumentError(+ f"Multiple embedding models with name {model_name} supported by {provider_name}", argument_name="model_name"+ )else:embedding_config = embedding_configs[0]@@ -1100,11 +1114,12 @@ class SyncServer(object):all_providers = await self.get_enabled_providers_async(actor)providers = [provider for provider in all_providers if provider.name == provider_name]if not providers:- raise ValueError(- f"Provider {provider_name} is not supported (supported providers: {', '.join([provider.name for provider in self._enabled_providers])})"+ raise LettaInvalidArgumentError(+ f"Provider {provider_name} is not supported (supported providers: {', '.join([provider.name for provider in self._enabled_providers])})",+ argument_name="provider_name",)elif len(providers) > 1:- raise ValueError(f"Multiple providers with name {provider_name} supported")+ raise LettaInvalidArgumentError(f"Multiple providers with name {provider_name} supported", argument_name="provider_name")else:provider = providers[0]@@ -1173,7 +1188,9 @@ class SyncServer(object):from letta.services.tool_schema_generator import generate_schema_for_tool_creation, generate_schema_for_tool_updateif tool_source_type not in (None, ToolSourceType.python, ToolSourceType.typescript):- raise ValueError("Tool source type is not supported at this time. Found {tool_source_type}")+ raise LettaInvalidArgumentError(+ f"Tool source type is not supported at this time. Found {tool_source_type}", argument_name="tool_source_type"+ )# If tools_json_schema is explicitly passed in, override it on the created Tool objectif tool_json_schema:@@ -1307,7 +1324,7 @@ class SyncServer(object):async def get_tools_from_mcp_server(self, mcp_server_name: str) -> List[MCPTool]:"""List the tools in an MCP server. Requires a client to be created."""if mcp_server_name not in self.mcp_clients:- raise ValueError(f"No client was created for MCP server: {mcp_server_name}")+ raise LettaInvalidArgumentError(f"No client was created for MCP server: {mcp_server_name}", argument_name="mcp_server_name")tools = await self.mcp_clients[mcp_server_name].list_tools()# Add health information to each tool@@ -1339,11 +1356,13 @@ class SyncServer(object):except Exception as e:# Raise an error telling the user to fix the config filelogger.error(f"Failed to parse MCP config file at {mcp_config_path}: {e}")- raise ValueError(f"Failed to parse MCP config file {mcp_config_path}")+ raise LettaInvalidArgumentError(f"Failed to parse MCP config file {mcp_config_path}")# Check if the server name is already in the configif server_config.server_name in current_mcp_servers and not allow_upsert:- raise ValueError(f"Server name {server_config.server_name} is already in the config file")+ raise LettaInvalidArgumentError(+ f"Server name {server_config.server_name} is already in the config file", argument_name="server_name"+ )# Attempt to initialize the connection to the serverif server_config.type == MCPServerType.SSE:@@ -1351,7 +1370,7 @@ class SyncServer(object):elif server_config.type == MCPServerType.STDIO:new_mcp_client = AsyncStdioMCPClient(server_config)else:- raise ValueError(f"Invalid MCP server config: {server_config}")+ raise LettaInvalidArgumentError(f"Invalid MCP server config: {server_config}", argument_name="server_config")try:await new_mcp_client.connect_to_server()except:@@ -1376,7 +1395,7 @@ class SyncServer(object):json.dump(new_mcp_file, f, indent=4)except Exception as e:logger.error(f"Failed to write MCP config file at {mcp_config_path}: {e}")- raise ValueError(f"Failed to write MCP config file {mcp_config_path}")+ raise LettaInvalidArgumentError(f"Failed to write MCP config file {mcp_config_path}")return list(current_mcp_servers.values())@@ -1399,12 +1418,12 @@ class SyncServer(object):except Exception as e:# Raise an error telling the user to fix the config filelogger.error(f"Failed to parse MCP config file at {mcp_config_path}: {e}")- raise ValueError(f"Failed to parse MCP config file {mcp_config_path}")+ raise LettaInvalidArgumentError(f"Failed to parse MCP config file {mcp_config_path}")# Check if the server name is already in the config# If it's not, throw an errorif server_name not in current_mcp_servers:- raise ValueError(f"Server name {server_name} not found in MCP config file")+ raise LettaInvalidArgumentError(f"Server name {server_name} not found in MCP config file", argument_name="server_name")# Remove from the server filedel current_mcp_servers[server_name]@@ -1416,7 +1435,7 @@ class SyncServer(object):json.dump(new_mcp_file, f, indent=4)except Exception as e:logger.error(f"Failed to write MCP config file at {mcp_config_path}: {e}")- raise ValueError(f"Failed to write MCP config file {mcp_config_path}")+ raise LettaInvalidArgumentError(f"Failed to write MCP config file {mcp_config_path}")return list(current_mcp_servers.values())@@ -1478,7 +1497,9 @@ class SyncServer(object):)streaming_interface = letta_agent.interfaceif not isinstance(streaming_interface, StreamingServerInterface):- raise ValueError(f"Agent has wrong type of interface: {type(streaming_interface)}")+ raise LettaInvalidArgumentError(+ f"Agent has wrong type of interface: {type(streaming_interface)}", argument_name="interface"+ )# Enable token-streaming within the request if desiredstreaming_interface.streaming_mode = stream_tokens@@ -1583,7 +1604,7 @@ class SyncServer(object):) -> Union[StreamingResponse, LettaResponse]:include_final_message = Trueif not stream_steps and stream_tokens:- raise ValueError("stream_steps must be 'true' if stream_tokens is 'true'")+ raise LettaInvalidArgumentError("stream_steps must be 'true' if stream_tokens is 'true'", argument_name="stream_steps")group = await self.group_manager.retrieve_group_async(group_id=group_id, actor=actor)agent_state_id = group.manager_agent_id or (group.agent_ids[0] if len(group.agent_ids) > 0 else None)@@ -1609,7 +1630,7 @@ class SyncServer(object):)streaming_interface = letta_multi_agent.interfaceif not isinstance(streaming_interface, StreamingServerInterface):- raise ValueError(f"Agent has wrong type of interface: {type(streaming_interface)}")+ raise LettaInvalidArgumentError(f"Agent has wrong type of interface: {type(streaming_interface)}", argument_name="interface")streaming_interface.streaming_mode = stream_tokensstreaming_interface.streaming_chat_completion_mode = chat_completion_modeif metadata and hasattr(streaming_interface, "metadata"):diff --git a/letta/services/agent_manager.py b/letta/services/agent_manager.pyindex 2e98dbec6..5091b12dd 100644--- a/letta/services/agent_manager.py+++ b/letta/services/agent_manager.py@@ -74,7 +74,7 @@ from letta.serialize_schemas.marshmallow_tool import SerializedToolSchemafrom letta.serialize_schemas.pydantic_agent_schema import AgentSchemafrom letta.server.db import db_registryfrom letta.services.archive_manager import ArchiveManager-from letta.services.block_manager import BlockManager+from letta.services.block_manager import BlockManager, validate_block_limit_constraintfrom letta.services.context_window_calculator.context_window_calculator import ContextWindowCalculatorfrom letta.services.context_window_calculator.token_counter import AnthropicTokenCounter, TiktokenCounterfrom letta.services.file_processor.chunker.line_chunker import LineChunker@@ -1661,6 +1661,9 @@ class AgentManager:update_data = block_update.model_dump(to_orm=True, exclude_unset=True, exclude_none=True)+ # Validate limit constraints before updating+ validate_block_limit_constraint(update_data, block)+for key, value in update_data.items():setattr(block, key, value)diff --git a/letta/services/block_manager.py b/letta/services/block_manager.pyindex bf757bb41..8231f8544 100644--- a/letta/services/block_manager.py+++ b/letta/services/block_manager.py@@ -5,6 +5,7 @@ from typing import Dict, List, Optionalfrom sqlalchemy import and_, delete, func, or_, selectfrom sqlalchemy.ext.asyncio import AsyncSession+from letta.errors import LettaInvalidArgumentErrorfrom letta.log import get_loggerfrom letta.orm.agent import Agent as AgentModelfrom letta.orm.block import Block as BlockModel@@ -23,6 +24,62 @@ from letta.utils import enforce_typeslogger = get_logger(__name__)+def validate_block_limit_constraint(update_data: dict, existing_block: BlockModel) -> None:+ """+ Validates that block limit constraints are satisfied when updating a block.++ Rules:+ - If limit is being updated, it must be >= the length of the value (existing or new)+ - If value is being updated, its length must not exceed the limit (existing or new)++ Args:+ update_data: Dictionary of fields to update+ existing_block: The current block being updated++ Raises:+ LettaInvalidArgumentError: If validation fails+ """+ # If limit is being updated, ensure it's >= current value length+ if "limit" in update_data:+ # Get the value that will be used (either from update_data or existing)+ value_to_check = update_data.get("value", existing_block.value)+ limit_to_check = update_data["limit"]+ if value_to_check and limit_to_check < len(value_to_check):+ raise LettaInvalidArgumentError(+ f"Limit ({limit_to_check}) cannot be less than current value length ({len(value_to_check)} characters)",+ argument_name="limit",+ )+ # If value is being updated and there's an existing limit, ensure value doesn't exceed limit+ elif "value" in update_data and existing_block.limit:+ if len(update_data["value"]) > existing_block.limit:+ raise LettaInvalidArgumentError(+ f"Value length ({len(update_data['value'])} characters) exceeds block limit ({existing_block.limit} characters)",+ argument_name="value",+ )+++def validate_block_creation(block_data: dict) -> None:+ """+ Validates that block limit constraints are satisfied when creating a block.++ Rules:+ - If both value and limit are provided, limit must be >= value length++ Args:+ block_data: Dictionary of block fields for creation++ Raises:+ LettaInvalidArgumentError: If validation fails+ """+ value = block_data.get("value")+ limit = block_data.get("limit")++ if value and limit and len(value) > limit:+ raise LettaInvalidArgumentError(+ f"Block limit ({limit}) must be greater than or equal to value length ({len(value)} characters)", argument_name="limit"+ )++class BlockManager:"""Manager class to handle business logic related to Blocks."""@@ -37,6 +94,8 @@ class BlockManager:else:async with db_registry.async_session() as session:data = block.model_dump(to_orm=True, exclude_none=True)+ # Validate block creation constraints+ validate_block_creation(data)block = BlockModel(**data, organization_id=actor.organization_id)await block.create_async(session, actor=actor, no_commit=True, no_refresh=True)pydantic_block = block.to_pydantic()@@ -58,6 +117,11 @@ class BlockManager:return []async with db_registry.async_session() as session:+ # Validate all blocks before creating any+ for block in blocks:+ block_data = block.model_dump(to_orm=True, exclude_none=True)+ validate_block_creation(block_data)+block_models = [BlockModel(**block.model_dump(to_orm=True, exclude_none=True), organization_id=actor.organization_id) for block in blocks]@@ -78,6 +142,9 @@ class BlockManager:block = await BlockModel.read_async(db_session=session, identifier=block_id, actor=actor)update_data = block_update.model_dump(to_orm=True, exclude_unset=True, exclude_none=True)+ # Validate limit constraints before updating+ validate_block_limit_constraint(update_data, block)+for key, value in update_data.items():setattr(block, key, value)@@ -653,7 +720,7 @@ class BlockManager:)if not block.current_history_entry_id:- raise ValueError(f"Block {block_id} has no history entry - cannot undo.")+ raise LettaInvalidArgumentError(f"Block {block_id} has no history entry - cannot undo.", argument_name="block_id")current_entry = await session.get(BlockHistory, block.current_history_entry_id)if not current_entry:@@ -672,7 +739,10 @@ class BlockManager:previous_entry = result.scalar_one_or_none()if not previous_entry:# No earlier checkpoint available- raise ValueError(f"Block {block_id} is already at the earliest checkpoint (seq={current_seq}). Cannot undo further.")+ raise LettaInvalidArgumentError(+ f"Block {block_id} is already at the earliest checkpoint (seq={current_seq}). Cannot undo further.",+ argument_name="block_id",+ )# 3) Move to that sequenceblock = await self._move_block_to_sequence(session, block, previous_entry.sequence_number, actor)@@ -699,11 +769,13 @@ class BlockManager:)if not block.current_history_entry_id:- raise ValueError(f"Block {block_id} has no history entry - cannot redo.")+ raise LettaInvalidArgumentError(f"Block {block_id} has no history entry - cannot redo.", argument_name="block_id")current_entry = await session.get(BlockHistory, block.current_history_entry_id)if not current_entry:- raise NoResultFound(f"BlockHistory row not found for id={block.current_history_entry_id}")+ raise LettaInvalidArgumentError(+ f"BlockHistory row not found for id={block.current_history_entry_id}", argument_name="block_id"+ )current_seq = current_entry.sequence_number@@ -717,7 +789,9 @@ class BlockManager:result = await session.execute(stmt)next_entry = result.scalar_one_or_none()if not next_entry:- raise ValueError(f"Block {block_id} is at the highest checkpoint (seq={current_seq}). Cannot redo further.")+ raise LettaInvalidArgumentError(+ f"Block {block_id} is at the highest checkpoint (seq={current_seq}). Cannot redo further.", argument_name="block_id"+ )block = await self._move_block_to_sequence(session, block, next_entry.sequence_number, actor)diff --git a/tests/managers/test_block_manager.py b/tests/managers/test_block_manager.pyindex 3d5aa801d..de8f01e73 100644--- a/tests/managers/test_block_manager.py+++ b/tests/managers/test_block_manager.py@@ -44,7 +44,7 @@ from letta.constants import (MULTI_AGENT_TOOLS,)from letta.data_sources.redis_client import NoopAsyncRedisClient, get_redis_client-from letta.errors import LettaAgentNotFoundError+from letta.errors import LettaAgentNotFoundError, LettaInvalidArgumentErrorfrom letta.functions.functions import derive_openai_json_schema, parse_source_codefrom letta.functions.mcp_client.types import MCPToolfrom letta.helpers import ToolRulesSolver@@ -451,7 +451,7 @@ async def test_update_block_limit(server: SyncServer, default_user):update_data = BlockUpdate(value="Updated Content" * 2000, description="Updated description")# Check that exceeding the block limit raises an exception- with pytest.raises(ValueError):+ with pytest.raises(LettaInvalidArgumentError):await block_manager.update_block_async(block_id=block.id, block_update=update_data, actor=default_user)# Ensure the update works when within limits@@ -908,8 +908,8 @@ async def test_undo_checkpoint_block(server: SyncServer, default_user):assert undone_block.label == "undo_test", "Label should also revert if changed (or remain the same if unchanged)"-#@pytest.mark.asyncio-#async def test_checkpoint_deletes_future_states_after_undo(server: SyncServer, default_user):+# @pytest.mark.asyncio+# async def test_checkpoint_deletes_future_states_after_undo(server: SyncServer, default_user):# """# Verifies that once we've undone to an earlier checkpoint, creating a new# checkpoint removes any leftover 'future' states that existed beyond that sequence.@@ -980,7 +980,7 @@ async def test_undo_checkpoint_block(server: SyncServer, default_user):async def test_undo_no_history(server: SyncServer, default_user):"""If a block has never been checkpointed (no current_history_entry_id),- undo_checkpoint_block should raise a ValueError.+ undo_checkpoint_block should raise a LettaInvalidArgumentError."""block_manager = BlockManager()@@ -988,7 +988,7 @@ async def test_undo_no_history(server: SyncServer, default_user):block = await block_manager.create_or_update_block_async(PydanticBlock(label="no_history_test", value="initial"), actor=default_user)# Attempt to undo- with pytest.raises(ValueError, match="has no history entry - cannot undo"):+ with pytest.raises(LettaInvalidArgumentError):await block_manager.undo_checkpoint_block(block_id=block.id, actor=default_user)@@ -1007,8 +1007,8 @@ async def test_undo_first_checkpoint(server: SyncServer, default_user):# 2) First checkpoint => seq=1await block_manager.checkpoint_block_async(block_id=block.id, actor=default_user)- # Attempt undo -> expect ValueError- with pytest.raises(ValueError, match="Cannot undo further"):+ # Attempt undo -> expect LettaInvalidArgumentError+ with pytest.raises(LettaInvalidArgumentError):await block_manager.undo_checkpoint_block(block_id=block.id, actor=default_user)@@ -1048,7 +1048,7 @@ async def test_undo_multiple_checkpoints(server: SyncServer, default_user):assert undone_block.value == "v1"# Try once more -> fails because seq=1 is the earliest- with pytest.raises(ValueError, match="Cannot undo further"):+ with pytest.raises(LettaInvalidArgumentError):await block_manager.undo_checkpoint_block(block_v1.id, actor=default_user)@@ -1145,15 +1145,15 @@ async def test_redo_checkpoint_block(server: SyncServer, default_user):async def test_redo_no_history(server: SyncServer, default_user):"""If a block has no current_history_entry_id (never checkpointed),- then redo_checkpoint_block should raise ValueError.+ then redo_checkpoint_block should raise LettaInvalidArgumentError."""block_manager = BlockManager()# Create block with no checkpointblock = await block_manager.create_or_update_block_async(PydanticBlock(label="redo_no_history", value="v0"), actor=default_user)- # Attempt to redo => expect ValueError- with pytest.raises(ValueError, match="no history entry - cannot redo"):+ # Attempt to redo => expect LettaInvalidArgumentError+ with pytest.raises(LettaInvalidArgumentError):await block_manager.redo_checkpoint_block(block.id, actor=default_user)@@ -1161,7 +1161,7 @@ async def test_redo_no_history(server: SyncServer, default_user):async def test_redo_at_highest_checkpoint(server: SyncServer, default_user):"""If the block is at the maximum sequence number, there's no higher checkpoint to move to.- redo_checkpoint_block should raise ValueError.+ redo_checkpoint_block should raise LettaInvalidArgumentError."""block_manager = BlockManager()@@ -1177,7 +1177,7 @@ async def test_redo_at_highest_checkpoint(server: SyncServer, default_user):# We are at seq=2, which is the highest checkpoint.# Attempt redo => there's no seq=3- with pytest.raises(ValueError, match="Cannot redo further"):+ with pytest.raises(LettaInvalidArgumentError):await block_manager.redo_checkpoint_block(b_init.id, actor=default_user)