feat: enable agent override for proxy (#7231)

letta/server/rest_api/proxy_helpers.py

@@ -453,6 +453,7 @@ async def get_or_create_claude_code_agent(
     server,
     actor,
     project_id: str = None,
+    agent_id: str = None,
 ):
     """
     Get or create a special agent for Claude Code sessions.
@@ -461,12 +462,24 @@ async def get_or_create_claude_code_agent(
         server: SyncServer instance
         actor: Actor performing the operation (user ID)
         project_id: Optional project ID to associate the agent with
+        agent_id: Optional specific agent ID to use (from X-LETTA-AGENT-ID header)
 
     Returns:
-        Agent ID
+        Agent instance
     """
     from letta.schemas.agent import CreateAgent
 
+    # If a specific agent ID is provided, try to use it directly
+    if agent_id:
+        logger.debug(f"Attempting to fetch agent by ID: {agent_id}")
+        try:
+            agent = await server.agent_manager.get_agent_by_id_async(agent_id=agent_id, actor=actor)
+            logger.info(f"Found agent via X-LETTA-AGENT-ID header: {agent.id} (name: {agent.name})")
+            return agent
+        except Exception as e:
+            logger.warning(f"Could not find agent with ID {agent_id}: {e}. Falling back to default behavior.")
+            # Fall through to default behavior below
+
     # Create short user identifier from UUID (first 8 chars)
     if actor:
         user_short_id = str(actor.id)[:8] if hasattr(actor, "id") else str(actor)[:8]

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

@@ -99,10 +99,14 @@ async def anthropic_messages_proxy(
     # Message persistence happens in the background after the response is returned.
     agent = None
     try:
+        # Check if X-LETTA-AGENT-ID header is provided
+        custom_agent_id = request.headers.get("x-letta-agent-id")
+
         agent = await get_or_create_claude_code_agent(
             server=server,
             actor=actor,
             project_id=project_id,
+            agent_id=custom_agent_id,
         )
         logger.debug(f"[{PROXY_NAME}] Using agent ID: {agent.id}")
     except Exception as e: