feat: deprecate append copy suffix, add override name [LET-5779] (#5694)

* feat: deprecate append copy suffix, add override name [LET-5779]

* update open api json

fern/openapi.json

@@ -18593,7 +18593,20 @@
             "type": "boolean",
             "title": "Append Copy Suffix",
             "description": "If set to True, appends \"_copy\" to the end of the agent name.",
-            "default": true
+            "default": true,
+            "deprecated": true
+          },
+          "override_name": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Override Name",
+            "description": "If provided, overrides the agent name with this value."
           },
           "override_existing_tools": {
             "type": "boolean",

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

@@ -234,6 +234,7 @@ async def _import_agent(
     actor: User,
     # TODO: Support these fields for new agent file
     append_copy_suffix: bool = True,
+    override_name: Optional[str] = None,
     override_existing_tools: bool = True,
     project_id: str | None = None,
     strip_messages: bool = False,
@@ -254,6 +255,7 @@ async def _import_agent(
         schema=agent_schema,
         actor=actor,
         append_copy_suffix=append_copy_suffix,
+        override_name=override_name,
         override_existing_tools=override_existing_tools,
         env_vars=env_vars,
         override_embedding_config=embedding_config_override,
@@ -274,7 +276,15 @@ async def import_agent(
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
     x_override_embedding_model: str | None = Header(None, alias="x-override-embedding-model"),
-    append_copy_suffix: bool = Form(True, description='If set to True, appends "_copy" to the end of the agent name.'),
+    append_copy_suffix: bool = Form(
+        True,
+        description='If set to True, appends "_copy" to the end of the agent name.',
+        deprecated=True,
+    ),
+    override_name: Optional[str] = Form(
+        None,
+        description="If provided, overrides the agent name with this value.",
+    ),
     override_existing_tools: bool = Form(
         True,
         description="If set to True, existing tools can get their source code overwritten by the uploaded tool definitions. Note that Letta core tools can never be updated externally.",
@@ -327,6 +337,7 @@ async def import_agent(
             server=server,
             actor=actor,
             append_copy_suffix=append_copy_suffix,
+            override_name=override_name,
             override_existing_tools=override_existing_tools,
             project_id=project_id,
             strip_messages=strip_messages,

letta/services/agent_serialization_manager.py

@@ -452,6 +452,7 @@ class AgentSerializationManager:
         schema: AgentFileSchema,
         actor: User,
         append_copy_suffix: bool = False,
+        override_name: Optional[str] = None,
         override_existing_tools: bool = True,
         dry_run: bool = False,
         env_vars: Optional[Dict[str, Any]] = None,
@@ -658,7 +659,11 @@ class AgentSerializationManager:
 
                 # Convert AgentSchema back to CreateAgent, remapping tool/block IDs
                 agent_data = agent_schema.model_dump(exclude={"id", "in_context_message_ids", "messages"})
-                if append_copy_suffix:
+
+                # Handle agent name override: override_name takes precedence over append_copy_suffix
+                if override_name:
+                    agent_data["name"] = override_name
+                elif append_copy_suffix:
                     agent_data["name"] = agent_data.get("name") + "_copy"
 
                 # Remap tool_ids from file IDs to database IDs