retrieve_agent
Retrieve complete details for a specific agent by ID to access its full operational state and configuration within the Letta system.
Instructions
Get the full state of a specific agent by ID. Similar to get_agent_summary but returns complete details. Use list_agents to find agent IDs.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | The ID of the agent to retrieve |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | Yes | ||
| model | No | ||
| tools | No | ||
| memory | No | ||
| created_at | No | ||
| description | No | ||
| embedding_model | No |
Implementation Reference
- src/tools/agents/retrieve-agent.js:4-34 (handler)The main handler function that implements the logic for the 'retrieve_agent' tool. It fetches the full state of an agent by ID using the server's API and returns it as JSON text content.
export async function handleRetrieveAgent(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 const response = await server.api.get(`/agents/${agentId}`, { headers }); const agentState = response.data; // Assuming response.data is the AgentState object return { content: [ { type: 'text', text: JSON.stringify({ agent: agentState, }), }, ], }; } 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 input schema for 'retrieve_agent'.
export const retrieveAgentDefinition = { name: 'retrieve_agent', description: 'Get the full state of a specific agent by ID. Similar to get_agent_summary but returns complete details. Use list_agents to find agent IDs.', inputSchema: { type: 'object', properties: { agent_id: { type: 'string', description: 'The ID of the agent to retrieve', }, }, required: ['agent_id'], }, }; - src/tools/index.js:183-184 (registration)Switch case in the tool call handler that routes 'retrieve_agent' calls to the handleRetrieveAgent function.
case 'retrieve_agent': return handleRetrieveAgent(server, request.params.arguments); - src/tools/index.js:119-119 (registration)Inclusion of retrieveAgentDefinition in the allTools array used to register tool definitions with the MCP server.
retrieveAgentDefinition, - src/tools/index.js:6-6 (registration)Import of the handler and definition for 'retrieve_agent'.
import { handleRetrieveAgent, retrieveAgentDefinition } from './agents/retrieve-agent.js';