delete_agent
Remove a specific agent permanently from the Letta system by providing its unique ID. Use list_agents to identify agents before deletion.
Instructions
Delete a specific agent by ID. Use list_agents to find agent IDs. For bulk deletion, use bulk_delete_agents. WARNING: This action is permanent.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | The ID of the agent to delete |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | ||
| success | Yes | ||
| agent_id | No |
Implementation Reference
- src/tools/agents/delete-agent.js:4-35 (handler)The handler function that executes the delete_agent tool logic: validates agent_id, calls the API to delete the agent, handles errors like 404, and returns a success response with the deleted agent_id.
export async function handleDeleteAgent(server, args) { if (!args?.agent_id) { server.createErrorResponse('Missing required argument: agent_id'); } try { const headers = server.getApiHeaders(); const agentId = encodeURIComponent(args.agent_id); // Use the specific endpoint from the OpenAPI spec // Note: axios delete method typically doesn't have a body, config is the second arg await server.api.delete(`/agents/${agentId}`, { headers }); // Successful deletion usually returns 200 or 204 with no body return { content: [ { type: 'text', text: JSON.stringify({ agent_id: args.agent_id, }), }, ], }; } catch (error) { // Handle potential 404 if agent not found, or other API errors if (error.response && error.response.status === 404) { server.createErrorResponse(`Agent not found: ${args.agent_id}`); } server.createErrorResponse(error); } } - The tool definition including name, description, and inputSchema for validating the agent_id parameter.
export const deleteAgentDefinition = { name: 'delete_agent', description: 'Delete a specific agent by ID. Use list_agents to find agent IDs. For bulk deletion, use bulk_delete_agents. WARNING: This action is permanent.', inputSchema: { type: 'object', properties: { agent_id: { type: 'string', description: 'The ID of the agent to delete', }, }, required: ['agent_id'], }, }; - src/tools/index.js:187-188 (registration)Registration of the delete_agent handler in the main tool call switch statement within registerToolHandlers.
case 'delete_agent': return handleDeleteAgent(server, request.params.arguments); - src/tools/output-schemas.js:439-447 (schema)Output schema definition for structured responses from the delete_agent tool.
delete_agent: { type: 'object', properties: { success: { type: 'boolean' }, agent_id: { type: 'string' }, message: { type: 'string' }, }, required: ['success'], }, - src/tools/annotations.js:25-33 (helper)Annotations providing metadata about the delete_agent tool, including warnings about its dangerous nature and side effects.
delete_agent: { title: 'Delete Agent', readOnly: false, requiresAuth: true, costLevel: 'low', executionTime: 'fast', sideEffects: 'Permanently removes agent and associated data', dangerous: true, },