list_agents
Retrieve available agents in the Letta system to manage, interact with, or create new agents for your workflow.
Instructions
List all available agents in the Letta system. Use with create_agent to add new ones, get_agent_summary for details, or prompt_agent to interact with them.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Optional filter to search for specific agents |
Implementation Reference
- src/tools/agents/list-agents.js:8-52 (handler)The core handler function that fetches agents from the Letta API, applies optional filtering, summarizes the list, and returns a structured JSON response.export async function handleListAgents(server, args) { try { // Headers for API requests const headers = server.getApiHeaders(); // Get the list of agents const response = await server.api.get('/agents/', { headers }); const agents = response.data; // Apply filter if provided let filteredAgents = agents; if (args?.filter) { const filter = args.filter.toLowerCase(); filteredAgents = agents.filter( (agent) => agent.name.toLowerCase().includes(filter) || (agent.description && agent.description.toLowerCase().includes(filter)), ); } // Extract only essential details for the response const summarizedAgents = filteredAgents.map((agent) => ({ id: agent.id, name: agent.name, description: agent.description, })); return { content: [ { type: 'text', text: JSON.stringify({ count: summarizedAgents.length, agents: summarizedAgents, // Use summarized list }), }, ], }; } catch (error) { logger.error('Error in list_agents:', error.message); logger.error('API Base URL:', server.apiBase); logger.error('Full error:', error.response?.data || error); server.createErrorResponse(error); } }
- The tool definition object including name, description, and input schema for the list_agents tool.export const listAgentsToolDefinition = { name: 'list_agents', description: 'List all available agents in the Letta system. Use with create_agent to add new ones, get_agent_summary for details, or prompt_agent to interact with them.', inputSchema: { type: 'object', properties: { filter: { type: 'string', description: 'Optional filter to search for specific agents', }, }, required: [], }, };
- src/tools/index.js:153-154 (registration)Registration in the central tool call dispatcher switch statement, routing 'list_agents' calls to the handler.case 'list_agents': return handleListAgents(server, request.params.arguments);
- src/tools/index.js:104-104 (registration)Inclusion of the tool definition in the allTools array for ListToolsRequestSchema registration.listAgentsToolDefinition,
- src/tools/output-schemas.js:23-43 (schema)Output schema definition for structured responses from the list_agents tool.list_agents: { type: 'object', properties: { agents: { type: 'array', items: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' }, description: { type: 'string' }, created_at: { type: 'string' }, model: { type: 'string' }, embedding_model: { type: 'string' }, }, required: ['id', 'name'], }, }, }, required: ['agents'], },