letta-nightly 0.6.39.dev20250313162623__py3-none-any.whl → 0.6.40.dev20250314173529__py3-none-any.whl

letta/server/rest_api/routers/v1/agents.py

@@ -24,6 +24,7 @@ from letta.schemas.run import Run
 from letta.schemas.source import Source
 from letta.schemas.tool import Tool
 from letta.schemas.user import User
+from letta.serialize_schemas.pydantic_agent_schema import AgentSchema
 from letta.server.rest_api.utils import get_letta_server
 from letta.server.server import SyncServer
 
@@ -35,81 +36,82 @@ router = APIRouter(prefix="/agents", tags=["agents"])
 logger = get_logger(__name__)
 
 
-# TODO: This should be paginated
 @router.get("/", response_model=List[AgentState], operation_id="list_agents")
 def list_agents(
     name: Optional[str] = Query(None, description="Name of the agent"),
     tags: Optional[List[str]] = Query(None, description="List of tags to filter agents by"),
     match_all_tags: bool = Query(
         False,
-        description="If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed in tags.",
+        description="If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags.",
     ),
-    server: "SyncServer" = Depends(get_letta_server),
+    server: SyncServer = Depends(get_letta_server),
     actor_id: Optional[str] = Header(None, alias="user_id"),
     before: Optional[str] = Query(None, description="Cursor for pagination"),
     after: Optional[str] = Query(None, description="Cursor for pagination"),
-    limit: Optional[int] = Query(None, description="Limit for pagination"),
+    limit: Optional[int] = Query(50, description="Limit for pagination"),
     query_text: Optional[str] = Query(None, description="Search agents by name"),
-    project_id: Optional[str] = Query(None, description="Search agents by project id"),
-    template_id: Optional[str] = Query(None, description="Search agents by template id"),
-    base_template_id: Optional[str] = Query(None, description="Search agents by base template id"),
-    identity_id: Optional[str] = Query(None, description="Search agents by identifier id"),
+    project_id: Optional[str] = Query(None, description="Search agents by project ID"),
+    template_id: Optional[str] = Query(None, description="Search agents by template ID"),
+    base_template_id: Optional[str] = Query(None, description="Search agents by base template ID"),
+    identity_id: Optional[str] = Query(None, description="Search agents by identity ID"),
     identifier_keys: Optional[List[str]] = Query(None, description="Search agents by identifier keys"),
+    include_relationships: Optional[List[str]] = Query(
+        None,
+        description=(
+            "Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in the response. "
+            "If not provided, all relationships are loaded by default. "
+            "Using this can optimize performance by reducing unnecessary joins."
+        ),
+    ),
 ):
     """
     List all agents associated with a given user.
-    This endpoint retrieves a list of all agents and their configurations associated with the specified user ID.
+
+    This endpoint retrieves a list of all agents and their configurations
+    associated with the specified user ID.
     """
+
+    # Retrieve the actor (user) details
     actor = server.user_manager.get_user_or_default(user_id=actor_id)
 
-    # Use dictionary comprehension to build kwargs dynamically
-    kwargs = {
-        key: value
-        for key, value in {
-            "name": name,
-            "project_id": project_id,
-            "template_id": template_id,
-            "base_template_id": base_template_id,
-        }.items()
-        if value is not None
-    }
-
-    # Call list_agents with the dynamic kwargs
-    agents = server.agent_manager.list_agents(
+    # Call list_agents directly without unnecessary dict handling
+    return server.agent_manager.list_agents(
         actor=actor,
+        name=name,
         before=before,
         after=after,
         limit=limit,
         query_text=query_text,
         tags=tags,
         match_all_tags=match_all_tags,
-        identifier_keys=identifier_keys,
+        project_id=project_id,
+        template_id=template_id,
+        base_template_id=base_template_id,
         identity_id=identity_id,
-        **kwargs,
+        identifier_keys=identifier_keys,
+        include_relationships=include_relationships,
     )
-    return agents
 
 
-@router.get("/{agent_id}/download", operation_id="download_agent_serialized")
-def download_agent_serialized(
+@router.get("/{agent_id}/export", operation_id="export_agent_serialized", response_model=AgentSchema)
+def export_agent_serialized(
     agent_id: str,
     server: "SyncServer" = Depends(get_letta_server),
     actor_id: Optional[str] = Header(None, alias="user_id"),
-):
+) -> AgentSchema:
     """
-    Download the serialized JSON representation of an agent.
+    Export 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")
+        return server.agent_manager.serialize(agent_id=agent_id, actor=actor)
     except NoResultFound:
         raise HTTPException(status_code=404, detail=f"Agent with id={agent_id} not found for user_id={actor.id}.")
 
 
-@router.post("/upload", response_model=AgentState, operation_id="upload_agent_serialized")
-async def upload_agent_serialized(
+@router.post("/import", response_model=AgentState, operation_id="import_agent_serialized")
+async def import_agent_serialized(
     file: UploadFile = File(...),
     server: "SyncServer" = Depends(get_letta_server),
     actor_id: Optional[str] = Header(None, alias="user_id"),
@@ -121,15 +123,19 @@ async def upload_agent_serialized(
     project_id: Optional[str] = Query(None, description="The project ID to associate the uploaded agent with."),
 ):
     """
-    Upload a serialized agent JSON file and recreate the agent in the system.
+    Import a serialized agent 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)
+
+        # 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_json,
+            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,
@@ -141,7 +147,7 @@ async def upload_agent_serialized(
         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)}")
+        raise HTTPException(status_code=422, detail=f"Invalid agent schema: {e.errors()}")
 
     except IntegrityError as e:
         raise HTTPException(status_code=409, detail=f"Database integrity error: {str(e)}")
@@ -149,9 +155,9 @@ async def upload_agent_serialized(
     except OperationalError as e:
         raise HTTPException(status_code=503, detail=f"Database connection error. Please try again later: {str(e)}")
 
-    except Exception:
+    except Exception as e:
         traceback.print_exc()
-        raise HTTPException(status_code=500, detail="An unexpected error occurred while uploading the agent.")
+        raise HTTPException(status_code=500, detail=f"An unexpected error occurred while uploading the agent: {str(e)}")
 
 
 @router.get("/{agent_id}/context", response_model=ContextWindowOverview, operation_id="retrieve_agent_context_window")
@@ -530,7 +536,7 @@ def list_messages(
     )
 
 
-@router.patch("/{agent_id}/messages/{message_id}", response_model=LettaMessageUpdateUnion, operation_id="modify_message")
+@router.patch("/{agent_id}/messages/{message_id}", response_model=LettaMessageUnion, operation_id="modify_message")
 def modify_message(
     agent_id: str,
     message_id: str,

letta/server/rest_api/routers/v1/groups.py

@@ -0,0 +1,233 @@
+from typing import Annotated, List, Optional
+
+from fastapi import APIRouter, Body, Depends, Header, Query
+from pydantic import Field
+
+from letta.constants import DEFAULT_MESSAGE_TOOL, DEFAULT_MESSAGE_TOOL_KWARG
+from letta.schemas.group import Group, GroupCreate, ManagerType
+from letta.schemas.letta_message import LettaMessageUnion
+from letta.schemas.letta_request import LettaRequest, LettaStreamingRequest
+from letta.schemas.letta_response import LettaResponse
+from letta.server.rest_api.utils import get_letta_server
+from letta.server.server import SyncServer
+
+router = APIRouter(prefix="/groups", tags=["groups"])
+
+
+@router.post("/", response_model=Group, operation_id="create_group")
+async def create_group(
+    server: SyncServer = Depends(get_letta_server),
+    request: GroupCreate = Body(...),
+    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+):
+    """
+    Create a multi-agent group with a specified management pattern. When no
+    management config is specified, this endpoint will use round robin for
+    speaker selection.
+    """
+    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+    return server.group_manager.create_group(request, actor=actor)
+
+
+@router.get("/", response_model=List[Group], operation_id="list_groups")
+def list_groups(
+    server: "SyncServer" = Depends(get_letta_server),
+    actor_id: Optional[str] = Header(None, alias="user_id"),
+    manager_type: Optional[ManagerType] = Query(None, description="Search groups by manager type"),
+    before: Optional[str] = Query(None, description="Cursor for pagination"),
+    after: Optional[str] = Query(None, description="Cursor for pagination"),
+    limit: Optional[int] = Query(None, description="Limit for pagination"),
+    project_id: Optional[str] = Query(None, description="Search groups by project id"),
+):
+    """
+    Fetch all multi-agent groups matching query.
+    """
+    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+    return server.group_manager.list_groups(
+        project_id=project_id,
+        manager_type=manager_type,
+        before=before,
+        after=after,
+        limit=limit,
+        actor=actor,
+    )
+
+
+@router.post("/", response_model=Group, operation_id="create_group")
+def create_group(
+    group: GroupCreate = Body(...),
+    server: "SyncServer" = Depends(get_letta_server),
+    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    x_project: Optional[str] = Header(None, alias="X-Project"),  # Only handled by next js middleware
+):
+    """
+    Create a new multi-agent group with the specified configuration.
+    """
+    try:
+        actor = server.user_manager.get_user_or_default(user_id=actor_id)
+        return server.group_manager.create_group(group, actor=actor)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.put("/", response_model=Group, operation_id="upsert_group")
+def upsert_group(
+    group: GroupCreate = Body(...),
+    server: "SyncServer" = Depends(get_letta_server),
+    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    x_project: Optional[str] = Header(None, alias="X-Project"),  # Only handled by next js middleware
+):
+    """
+    Create a new multi-agent group with the specified configuration.
+    """
+    try:
+        actor = server.user_manager.get_user_or_default(user_id=actor_id)
+        return server.group_manager.create_group(group, actor=actor)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/{group_id}", response_model=None, operation_id="delete_group")
+def delete_group(
+    group_id: str,
+    server: "SyncServer" = Depends(get_letta_server),
+    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+):
+    """
+    Delete a multi-agent group.
+    """
+    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+    try:
+        server.group_manager.delete_group(group_id=group_id, actor=actor)
+        return JSONResponse(status_code=status.HTTP_200_OK, content={"message": f"Group id={group_id} successfully deleted"})
+    except NoResultFound:
+        raise HTTPException(status_code=404, detail=f"Group id={group_id} not found for user_id={actor.id}.")
+
+
+@router.post(
+    "/{group_id}/messages",
+    response_model=LettaResponse,
+    operation_id="send_group_message",
+)
+async def send_group_message(
+    agent_id: str,
+    server: SyncServer = Depends(get_letta_server),
+    request: LettaRequest = Body(...),
+    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+):
+    """
+    Process a user message and return the group's response.
+    This endpoint accepts a message from a user and processes it through through agents in the group based on the specified pattern
+    """
+    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+    result = await server.send_group_message_to_agent(
+        group_id=group_id,
+        actor=actor,
+        messages=request.messages,
+        stream_steps=False,
+        stream_tokens=False,
+        # Support for AssistantMessage
+        use_assistant_message=request.use_assistant_message,
+        assistant_message_tool_name=request.assistant_message_tool_name,
+        assistant_message_tool_kwarg=request.assistant_message_tool_kwarg,
+    )
+    return result
+
+
+@router.post(
+    "/{group_id}/messages/stream",
+    response_model=None,
+    operation_id="send_group_message_streaming",
+    responses={
+        200: {
+            "description": "Successful response",
+            "content": {
+                "text/event-stream": {"description": "Server-Sent Events stream"},
+            },
+        }
+    },
+)
+async def send_group_message_streaming(
+    group_id: str,
+    server: SyncServer = Depends(get_letta_server),
+    request: LettaStreamingRequest = Body(...),
+    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+):
+    """
+    Process a user message and return the group's responses.
+    This endpoint accepts a message from a user and processes it through agents in the group based on the specified pattern.
+    It will stream the steps of the response always, and stream the tokens if 'stream_tokens' is set to True.
+    """
+    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+    result = await server.send_group_message_to_agent(
+        group_id=group_id,
+        actor=actor,
+        messages=request.messages,
+        stream_steps=True,
+        stream_tokens=request.stream_tokens,
+        # Support for AssistantMessage
+        use_assistant_message=request.use_assistant_message,
+        assistant_message_tool_name=request.assistant_message_tool_name,
+        assistant_message_tool_kwarg=request.assistant_message_tool_kwarg,
+    )
+    return result
+
+
+GroupMessagesResponse = Annotated[
+    List[LettaMessageUnion], Field(json_schema_extra={"type": "array", "items": {"$ref": "#/components/schemas/LettaMessageUnion"}})
+]
+
+
+@router.get("/{group_id}/messages", response_model=GroupMessagesResponse, operation_id="list_group_messages")
+def list_group_messages(
+    group_id: str,
+    server: "SyncServer" = Depends(get_letta_server),
+    after: Optional[str] = Query(None, description="Message after which to retrieve the returned messages."),
+    before: Optional[str] = Query(None, description="Message before which to retrieve the returned messages."),
+    limit: int = Query(10, description="Maximum number of messages to retrieve."),
+    use_assistant_message: bool = Query(True, description="Whether to use assistant messages"),
+    assistant_message_tool_name: str = Query(DEFAULT_MESSAGE_TOOL, description="The name of the designated message tool."),
+    assistant_message_tool_kwarg: str = Query(DEFAULT_MESSAGE_TOOL_KWARG, description="The name of the message argument."),
+    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+):
+    """
+    Retrieve message history for an agent.
+    """
+    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+
+    return server.group_manager.list_group_messages(
+        group_id=group_id,
+        before=before,
+        after=after,
+        limit=limit,
+        actor=actor,
+        use_assistant_message=use_assistant_message,
+        assistant_message_tool_name=assistant_message_tool_name,
+        assistant_message_tool_kwarg=assistant_message_tool_kwarg,
+    )
+
+
+'''
+@router.patch("/{group_id}/reset-messages", response_model=None, operation_id="reset_group_messages")
+def reset_group_messages(
+    group_id: str,
+    add_default_initial_messages: bool = Query(default=False, description="If true, adds the default initial messages after resetting."),
+    server: "SyncServer" = Depends(get_letta_server),
+    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+):
+    """
+    Resets the messages for all agents that are part of the multi-agent group.
+    TODO: only delete group messages not all messages!
+    """
+    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+    group = server.group_manager.retrieve_group(group_id=group_id, actor=actor)
+    agent_ids = group.agent_ids
+    if group.manager_agent_id:
+        agent_ids.append(group.manager_agent_id)
+    for agent_id in agent_ids:
+        server.agent_manager.reset_messages(
+            agent_id=agent_id,
+            actor=actor,
+            add_default_initial_messages=add_default_initial_messages,
+        )
+'''

letta/server/rest_api/routers/v1/tools.py

@@ -13,7 +13,7 @@ from fastapi import APIRouter, Body, Depends, Header, HTTPException
 
 from letta.errors import LettaToolCreateError
 from letta.helpers.composio_helpers import get_composio_api_key
-from letta.helpers.mcp_helpers import LocalServerConfig, MCPTool, SSEServerConfig
+from letta.helpers.mcp_helpers import MCPTool, SSEServerConfig, StdioServerConfig
 from letta.log import get_logger
 from letta.orm.errors import UniqueConstraintViolationError
 from letta.schemas.letta_message import ToolReturnMessage
@@ -333,7 +333,7 @@ def add_composio_tool(
 
 
 # Specific routes for MCP
-@router.get("/mcp/servers", response_model=dict[str, Union[SSEServerConfig, LocalServerConfig]], operation_id="list_mcp_servers")
+@router.get("/mcp/servers", response_model=dict[str, Union[SSEServerConfig, StdioServerConfig]], operation_id="list_mcp_servers")
 def list_mcp_servers(server: SyncServer = Depends(get_letta_server), user_id: Optional[str] = Header(None, alias="user_id")):
     """
     Get a list of all configured MCP servers
@@ -376,7 +376,7 @@ def add_mcp_tool(
     actor_id: Optional[str] = Header(None, alias="user_id"),
 ):
     """
-    Add a new MCP tool by server + tool name
+    Register a new MCP tool as a Letta server by MCP server + tool name
     """
     actor = server.user_manager.get_user_or_default(user_id=actor_id)
 
@@ -399,3 +399,31 @@ def add_mcp_tool(
 
     tool_create = ToolCreate.from_mcp(mcp_server_name=mcp_server_name, mcp_tool=mcp_tool)
     return server.tool_manager.create_or_update_mcp_tool(tool_create=tool_create, actor=actor)
+
+
+@router.put("/mcp/servers", response_model=List[Union[StdioServerConfig, SSEServerConfig]], operation_id="add_mcp_server")
+def add_mcp_server_to_config(
+    request: Union[StdioServerConfig, SSEServerConfig] = Body(...),
+    server: SyncServer = Depends(get_letta_server),
+    actor_id: Optional[str] = Header(None, alias="user_id"),
+):
+    """
+    Add a new MCP server to the Letta MCP server config
+    """
+    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+    return server.add_mcp_server_to_config(server_config=request, allow_upsert=True)
+
+
+@router.delete(
+    "/mcp/servers/{mcp_server_name}", response_model=List[Union[StdioServerConfig, SSEServerConfig]], operation_id="delete_mcp_server"
+)
+def delete_mcp_server_from_config(
+    mcp_server_name: str,
+    server: SyncServer = Depends(get_letta_server),
+    actor_id: Optional[str] = Header(None, alias="user_id"),
+):
+    """
+    Add a new MCP server to the Letta MCP server config
+    """
+    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+    return server.delete_mcp_server_from_config(server_name=mcp_server_name)

letta/server/rest_api/utils.py

@@ -18,7 +18,7 @@ from letta.errors import ContextWindowExceededError, RateLimitExceededError
 from letta.helpers.datetime_helpers import get_utc_time
 from letta.log import get_logger
 from letta.schemas.enums import MessageRole
-from letta.schemas.letta_message import TextContent
+from letta.schemas.letta_message_content import TextContent
 from letta.schemas.message import Message
 from letta.schemas.usage import LettaUsageStatistics
 from letta.schemas.user import User