list_messages
Retrieve paginated conversation history from Letta agents to review interactions, debug behavior, or analyze message flow.
Instructions
Retrieve messages from an agent's conversation history. Returns paginated message history including user messages, assistant responses, tool calls, and system messages. Use for reviewing past conversations or debugging agent behavior.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ID of the agent whose messages to retrieve | |
| limit | No | Maximum number of messages to return | |
| order | No | Sort order: "asc" for oldest first, "desc" for newest first | |
| before | No | Pagination cursor - get messages before this message ID | |
| after | No | Pagination cursor - get messages after this message ID | |
| group_id | No | Filter messages by group ID |
Implementation Reference
- src/tools/messages/list-messages.js:4-40 (handler)The handler function that implements the list_messages tool. It fetches the agent's messages using the server API with optional pagination and filtering parameters, formats the response as MCP content, and handles errors.export async function handleListMessages(server, args) { if (!args?.agent_id) { throw new Error('Missing required argument: agent_id'); } try { const headers = server.getApiHeaders(); const agentId = encodeURIComponent(args.agent_id); // Construct query parameters const params = {}; if (args.limit) params.limit = args.limit; if (args.order) params.order = args.order; if (args.before) params.before = args.before; if (args.after) params.after = args.after; if (args.group_id) params.group_id = args.group_id; const response = await server.api.get(`/agents/${agentId}/messages`, { headers, params, }); return { content: [ { type: 'text', text: JSON.stringify({ messages: response.data, count: response.data.length, }), }, ], }; } catch (error) { return server.createErrorResponse(error); } }
- The tool definition object containing name, description, and inputSchema for the list_messages tool, used for tool listing and input validation.export const listMessagesDefinition = { name: 'list_messages', description: "Retrieve messages from an agent's conversation history. Returns paginated message history including user messages, assistant responses, tool calls, and system messages. Use for reviewing past conversations or debugging agent behavior.", inputSchema: { type: 'object', properties: { agent_id: { type: 'string', description: 'ID of the agent whose messages to retrieve', }, limit: { type: 'integer', description: 'Maximum number of messages to return', }, order: { type: 'string', enum: ['asc', 'desc'], description: 'Sort order: "asc" for oldest first, "desc" for newest first', }, before: { type: 'string', description: 'Pagination cursor - get messages before this message ID', }, after: { type: 'string', description: 'Pagination cursor - get messages after this message ID', }, group_id: { type: 'string', description: 'Filter messages by group ID', }, }, required: ['agent_id'], }, };
- src/tools/index.js:221-222 (registration)Registers the list_messages handler in the central tool dispatch switch statement within the MCP CallToolRequest handler.case 'list_messages': return handleListMessages(server, request.params.arguments);
- src/tools/index.js:138-138 (registration)Includes the listMessagesDefinition in the allTools array, which is enhanced and registered for ListToolsRequest.listMessagesDefinition,