API Reference

SDK v1.0 Migration Guide

Upgrading from v0.x to v1.0

This guide covers migrating from Letta SDK v0.x (e.g., 1.0.0-alpha.2) to v1.0 (e.g., 1.0.0-alpha.10+). For agent architecture migrations, see the Architecture Migration Guide.

Overview

SDK v1.0 introduces breaking changes to improve consistency and align with modern API design patterns:

  • Naming convention: All properties now use snake_case instead of camelCase
  • Client initialization: Simplified client constructor with renamed parameters
  • Method names: Several methods renamed for clarity
  • Type imports: Types moved to subpath exports for better organization
  • Enums: Replaced with string literal types
  • Tool calls: Changed from single object to array structure
  • Pagination: List methods now return page objects

Quick Reference

Package Update

Update your package dependency:

1{
2  "dependencies": {
3-   "@letta-ai/letta-client": "1.0.0-alpha.2"
4+   "@letta-ai/letta-client": "1.0.0-alpha.10"
5  }
6}

Import Changes

1// Old
2- import { LettaClient, Letta } from "@letta-ai/letta-client";
3
4// New
5+ import Letta from "@letta-ai/letta-client";
6+ import type {
7+   Block,
8+   CreateBlock,
9+   AgentType
10+ } from "@letta-ai/letta-client/resources/agents/agents";
11+ import type {
12+   LettaMessageUnion,
13+   ApprovalCreate
14+ } from "@letta-ai/letta-client/resources/agents/messages";
15+ import type {
16+   LlmConfig
17+ } from "@letta-ai/letta-client/resources/models/models";

Client Instantiation

1// Old
2- const client = new LettaClient({
3-   token: process.env.LETTA_API_KEY,
4-   baseUrl: "https://api.letta.com"
5- });
6
7// New
8+ const client = new Letta({
9+   apiKey: process.env.LETTA_API_KEY,
10+   baseURL: "https://api.letta.com"
11+ });

Breaking Changes by Category

1. Pagination

All list endpoints now use cursor-based pagination with consistent parameters:

1// Old - various pagination styles
2const messages = await client.agents.messages.list(agentId, {
3  sort_by: "created_at",
4  ascending: true
5});
6
7// New - standardized cursor pagination
8const messagesPage = await client.agents.messages.list(agentId, {
9  before: "msg_123",  // cursor (message ID)
10  after: "msg_456",   // cursor (message ID)
11  limit: 50,
12  order: "asc"  // or "desc"
13});
14const messages = messagesPage.items;

Affected endpoints:

  • agents.list() - renamed sort_by → order_by, ascending → order
  • agents.messages.list()
  • agents.tools.list()
  • agents.blocks.list()
  • agents.files.list()
  • agents.folders.list()
  • agents.groups.list()
  • blocks.list()
  • folders.list()
  • folders.files.list()
  • folders.passages.list()
  • folders.agents.list()
  • groups.list()
  • groups.messages.list()
  • identities.list()
  • providers.list()
  • runs.list()
  • runs.messages.list()
  • runs.steps.list()
  • jobs.list()
  • steps.list()
  • tags.list()
  • tools.list()
  • batches.list()
  • batches.messages.list()

2. Method Renames and Endpoint Restructuring

Many methods were reorganized for better SDK structure:

1// Agent updates
2- await client.agents.modify(agentId, updates)
3+ await client.agents.update(agentId, updates)
4
5// Message operations
6- await client.agents.summarize_agent_conversation(agentId)
7+ await client.agents.messages.summarize(agentId)
8
9- await client.agents.cancel_agent_run(agentId)
10+ await client.agents.messages.cancel(agentId)
11
12- await client.agents.messages.preview_raw_payload(agentId, messages)
13+ await client.agents.messages.preview(agentId, messages)
14
15// Agent file operations
16- await client.agents.list_agent_files(agentId)
17+ await client.agents.files.list(agentId)
18
19// Export/Import
20- await client.agents.export_agent_serialized(agentId)
21+ await client.agents.export(agentId)
22
23- await client.agents.import_agent_serialized(file)
24+ await client.agents.import(file)
25
26// Folder operations
27- await client.folders.get_agents_for_folder(folderId)
28+ await client.folders.agents.list(folderId)
29
30- await client.folders.retrieve_folder_metadata(folderId)
31+ await client.folders.retrieve_metadata(folderId)
32
33// Provider operations
34- await client.providers.check_provider(providerId)
35+ await client.providers.check(providerId)
36
37// Telemetry
38- await client.telemetry.retrieve_provider_trace(stepId)
39+ await client.steps.trace(stepId)
40
41// Step metrics
42- await client.steps.retrieve_step_metrics(stepId)
43+ await client.steps.metrics.retrieve(stepId)
44
45// Batch messages
46- await client.messages.list_batch_messages(batchId)
47+ await client.batches.messages.list(batchId)
48
49// Multi-agent groups
50- agent.multi_agent_group
51+ agent.managed_group

3. Deprecations

Several endpoints and fields are now deprecated:

Deprecated endpoints:

  • client.agents.search() - use client.agents.list() with filters
  • client.messages.search() - use client.agents.messages.list() with filters
  • client.runs.list_active() - use client.runs.list(active=True)
  • client.jobs.list_active() - use client.jobs.list(active=True)
  • client.folders.get_by_name() - use client.folders.list(name="...")
  • MCP routes under /tools/mcp/servers - replaced with new /mcp-servers endpoints
    • All old MCP methods moved from client.tools.mcp.servers to client.mcp_servers
    • Now use server IDs and tool IDs instead of names
  • Sources-related routes - replaced with folders
  • Passages routes - replaced with archives
  • Legacy agent architecture routes
  • All /count endpoints

Deprecated fields:

  • agent.memory - use agent.blocks
  • step.messages - use client.steps.messages.list(step_id)
  • agent.identity_ids - replaced with agent.identities (full objects)
  • agent.multi_agent_group - renamed to agent.managed_group
  • use_assistant_message parameter - no longer needed
  • tool_exec_environment_variables - renamed to secrets

Deprecated on agent/block objects:

  • Template-related fields: is_template, base_template_id, deployment_id
  • entity_id, preserve_on_migration, hidden
  • name on blocks (use label)

4. Property Names (camelCase → snake_case)

All API properties now use snake_case:

1// Agent properties
2- agent.llmConfig
3+ agent.llm_config
4
5- agent.contextWindowLimit
6+ agent.context_window_limit
7
8- agent.blockIds
9+ agent.block_ids
10
11- agent.includeBaseTools
12+ agent.include_base_tools
13
14- agent.includeBaseToolRules
15+ agent.include_base_tool_rules
16
17- agent.initialMessageSequence
18+ agent.initial_message_sequence
19
20// Message properties
21- message.messageType
22+ message.message_type
23
24- message.toolCallId
25+ message.tool_call_id
26
27- message.toolReturn
28+ message.tool_return
29
30- message.toolCall
31+ message.tool_calls  // Also changed to array!
32
33// API parameters
34- streamTokens: true
35+ stream_tokens: true
36
37- approvalRequestId: id
38+ approval_request_id: id

2. Agent Type Specification

1// Old
2- agentType: Letta.AgentType.LettaV1Agent
3
4// New
5+ agent_type: "letta_v1_agent" as AgentType

3. Method Renames

1// Agent updates
2- await client.agents.modify(agentId, { model, llmConfig })
3+ await client.agents.update(agentId, { model, llm_config })
4
5// Message streaming
6- client.agents.messages.createStream(agentId, { messages, streamTokens })
7+ client.agents.messages.stream(agentId, { messages, stream_tokens })

4. Message Roles and Stop Reasons

Enums replaced with string literals:

1// Message roles
2- role: Letta.MessageCreateRole.User
3+ role: "user"
4
5// Stop reasons
6- if (stopReason === Letta.StopReasonType.EndTurn)
7+ if (stopReason === "end_turn")
8
9- if (stopReason === Letta.StopReasonType.RequiresApproval)
10+ if (stopReason === "requires_approval")

5. Tool Calls Structure

Tool calls changed from single object to array:

1// Old - single tool_call
2- if (message.messageType === "approval_request_message") {
3-   const toolCall = message.toolCall;
4-   const id = toolCall.toolCallId;
5-   const name = toolCall.name;
6- }
7
8// New - tool_calls array
9+ if (message.message_type === "approval_request_message") {
10+   const toolCalls = message.tool_calls || [];
11+   if (toolCalls.length > 0) {
12+     const toolCall = toolCalls[0];
13+     const id = toolCall.tool_call_id;
14+     const name = toolCall.name;
15+   }
16+ }

6. Pagination

List methods now return page objects:

1// Old
2- const messages = await client.agents.messages.list(agentId);
3
4// New
5+ const messagesPage = await client.agents.messages.list(agentId);
6+ const messages = messagesPage.items;

7. Date Handling

1// Old
2- date: new Date()
3
4// New
5+ date: new Date().toISOString()

8. Archive Management (New APIs)

New endpoints for managing archival memory:

1// Create archive
2const archive = await client.archives.create({
3  name: "my-archive",
4  description: "Project knowledge base"
5});
6
7// List archives
8const archives = await client.archives.list();
9
10// Get archive by ID
11const archive = await client.archives.retrieve(archiveId);
12
13// Update archive
14await client.archives.update(archiveId, { name: "updated-name" });
15
16// Delete archive
17await client.archives.delete(archiveId);
18
19// Attach archive to agent
20await client.agents.archives.attach(agentId, archiveId);
21
22// Detach archive from agent
23await client.agents.archives.detach(agentId, archiveId);
24
25// List agents using an archive
26const agents = await client.archives.agents.list(archiveId);
27
28// Manage memories in archive
29await client.archives.memories.create(archiveId, { text: "Important fact" });
30await client.archives.memories.update(archiveId, memoryId, { text: "Updated fact" });
31await client.archives.memories.delete(archiveId, memoryId);

9. Identity and Block Management

New attach/detach patterns for identities and blocks:

1// Attach identity to agent
2await client.agents.identities.attach(agentId, identityId);
3
4// Detach identity from agent
5await client.agents.identities.detach(agentId, identityId);
6
7// Attach identity to block
8await client.blocks.identities.attach(blockId, identityId);
9
10// Detach identity from block
11await client.blocks.identities.detach(blockId, identityId);
12
13// Agent now returns full identity objects
14const agent = await client.agents.retrieve(agentId);
15// Old: agent.identity_ids = ["id1", "id2"]
16// New: agent.identities = [{ id: "id1", name: "Alice", ... }, ...]

10. Agent Configuration Updates

New parameters available for agent creation and updates:

1// Temperature, top_p, reasoning_effort now available at top level
2const agent = await client.agents.create({
3  model: "openai/gpt-4",
4  temperature: 0.7,
5  top_p: 0.9,
6  reasoning_effort: "medium",
7  max_tokens: 4096,
8  context_window_limit: 128000
9});
10
11// Update agent configuration
12await client.agents.update(agentId, {
13  temperature: 0.5,
14  context_window_limit: 64000
15});

11. Message Input Shorthand

Simplified syntax for sending simple user messages:

1// Old - verbose
2const response = await client.agents.messages.create(agentId, {
3  messages: [{
4    role: "user",
5    content: "Hello!"
6  }]
7});
8
9// New - shorthand available
10const response = await client.agents.messages.create(agentId, {
11  input: "Hello!"  // Automatically creates user message
12});
13
14// Both forms still supported

12. Attach/Detach Return Values

All attach/detach endpoints now return None instead of agent/object state:

1// Old - returned updated agent
2const updatedAgent = await client.agents.tools.attach(agentId, toolId);
3
4// New - returns void/None
5await client.agents.tools.attach(agentId, toolId);
6// Fetch agent separately if needed
7const agent = await client.agents.retrieve(agentId);

Affected methods:

  • agents.tools.attach/detach
  • agents.blocks.attach/detach
  • agents.folders.attach/detach
  • agents.archives.attach/detach
  • agents.identities.attach/detach
  • blocks.identities.attach/detach

13. Agent Import/Export Changes

Import endpoint now supports name overriding:

1// Old - append_copy_suffix parameter
2const agent = await client.agents.import(file, {
3  append_copy_suffix: true  // Deprecated
4});
5
6// New - override_name parameter
7const agent = await client.agents.import(file, {
8  override_name: "my-imported-agent"  // Optional, exact name to use
9});

14. Query Parameter to Request Body Changes

Several endpoints moved from query parameters to request body:

1// Tool approval settings (was query params, now request body)
2await client.agents.tools.update_approval(agentId, toolName, {
3  require_approval: true
4});
5
6// Reset messages (was query param, now request body)
7await client.agents.messages.reset(agentId, {
8  add_default_initial_messages: false
9});
10
11// Steps feedback (was query params, now request body)
12await client.steps.feedback.create(stepId, {
13  rating: "positive",
14  tags: ["helpful", "accurate"]
15});

15. Tags Endpoint

Tags list endpoint now uses name parameter instead of query_text:

1// Old
2const tags = await client.tags.list({ query_text: "important" });
3
4// New
5const tags = await client.tags.list({ name: "important" });

16. Project ID Handling

Project ID is now passed in the client constructor or headers:

1// Pass in constructor
2const client = new Letta({
3  apiKey: process.env.LETTA_API_KEY,
4  projectId: "proj_123"
5});
6
7// No longer in URL paths
8- await client.templates.agents.create("proj_123", templateVersion, data)
9+ await client.templates.agents.create(templateVersion, data)

17. MCP (Model Context Protocol) Server Management

MCP routes have been completely restructured with new endpoints under /mcp-servers:

1// OLD ROUTES (under /tools/mcp/servers - DEPRECATED)
2// Using server names and tool names
3
4// List MCP servers
5- const servers = await client.tools.mcp.servers.list();
6
7// Add MCP server
8- await client.tools.mcp.servers.create(serverConfig);
9
10// Update MCP server by name
11- await client.tools.mcp.servers.update(serverName, updateConfig);
12
13// Delete MCP server by name
14- await client.tools.mcp.servers.delete(serverName);
15
16// List tools from a server by name
17- const tools = await client.tools.mcp.servers.tools.list(serverName);
18
19// Add individual tool by name
20- await client.tools.mcp.servers.tools.add(serverName, toolName);
21
22// Resync tools
23- await client.tools.mcp.servers.resync(serverName);
24
25// Execute tool by names
26- await client.tools.mcp.servers.tools.execute(serverName, toolName, { args });
27
28// Connect to server (for OAuth)
29- await client.tools.mcp.servers.connect(serverConfig);
30
31// NEW ROUTES (under /mcp-servers)
32// Using server IDs and tool IDs
33
34// List MCP servers (returns array of server objects with IDs)
35+ const servers = await client.mcp_servers.list();
36
37// Create MCP server (automatically syncs tools)
38+ const server = await client.mcp_servers.create(serverConfig);
39+ // Returns: { id: "mcp_server_123", name: "...", ... }
40
41// Get MCP server by ID
42+ const server = await client.mcp_servers.retrieve(serverId);
43
44// Update MCP server by ID
45+ await client.mcp_servers.update(serverId, updateConfig);
46
47// Delete MCP server by ID
48+ await client.mcp_servers.delete(serverId);
49
50// List tools from a server by ID
51+ const tools = await client.mcp_servers.tools.list(serverId);
52
53// Get specific tool by ID
54+ const tool = await client.mcp_servers.tools.retrieve(serverId, toolId);
55
56// Run/execute tool by ID
57+ const result = await client.mcp_servers.tools.run(serverId, toolId, {
58+   args: { key: "value" }
59+ });
60
61// Refresh tools (replaces resync)
62+ await client.mcp_servers.refresh(serverId);
63
64// Connect to server (for OAuth) - now uses server ID
65+ await client.mcp_servers.connect(serverId);

Key Changes:

  • Namespace: Moved from client.tools.mcp.servers to client.mcp_servers
  • Identification: Use server IDs and tool IDs instead of names
    • Old: serverName (string) → New: serverId (ID string like "mcp_server_123")
    • Old: toolName (string) → New: toolId (ID string like "tool_456")
  • Tool Management: Tools are now automatically synced when creating a server
    • No longer need to manually “add” individual tools
    • Use refresh() to resync tools (replaces resync())
  • Tool Execution: Method renamed from execute() to run()
  • Server Retrieval: New retrieve() method to get individual server by ID
  • Tool Retrieval: New retrieve() method to get individual tool by ID

Migration Example:

1// Before: Using names
2const servers = await client.tools.mcp.servers.list();
3const myServer = servers.find(s => s.name === "my-server");
4const tools = await client.tools.mcp.servers.tools.list("my-server");
5const myTool = tools.find(t => t.name === "my-tool");
6await client.tools.mcp.servers.tools.execute("my-server", "my-tool", {
7  args: { query: "hello" }
8});
9
10// After: Using IDs
11const servers = await client.mcp_servers.list();
12const myServer = servers.find(s => s.name === "my-server");
13const serverId = myServer.id;  // Get ID from server object
14const tools = await client.mcp_servers.tools.list(serverId);
15const myTool = tools.find(t => t.name === "my-tool");
16const toolId = myTool.id;  // Get ID from tool object
17await client.mcp_servers.tools.run(serverId, toolId, {
18  args: { query: "hello" }
19});

Notes:

  • MCP servers and tools now have persistent IDs in the database
  • Server names are no longer unique identifiers - use IDs instead
  • Tool schemas are automatically kept in sync via the refresh() endpoint
  • The old routes under /tools/mcp/servers are deprecated and will be removed

Migration Examples

Complete Agent Creation

1// Before
2const agent = await client.agents.create({
3  agentType: Letta.AgentType.LettaV1Agent,
4  model: "openai/gpt-4",
5  contextWindowLimit: 200_000,
6  blockIds: ["block-1", "block-2"],
7  includeBaseTools: false,
8  includeBaseToolRules: false,
9  initialMessageSequence: [],
10});
11
12// After
13const agent = await client.agents.create({
14  agent_type: "letta_v1_agent" as AgentType,
15  model: "openai/gpt-4",
16  context_window_limit: 200_000,
17  block_ids: ["block-1", "block-2"],
18  include_base_tools: false,
19  include_base_tool_rules: false,
20  initial_message_sequence: [],
21});

Streaming Messages

1// Before
2const stream = await client.agents.messages.createStream(agentId, {
3  messages: [{
4    role: Letta.MessageCreateRole.User,
5    content: "Hello"
6  }],
7  streamTokens: true,
8});
9
10// After
11const stream = await client.agents.messages.stream(agentId, {
12  messages: [{
13    role: "user",
14    content: "Hello"
15  }],
16  stream_tokens: true,
17});

Handling Approvals

1// Before
2if (message.messageType === "approval_request_message") {
3  const toolCall = message.toolCall;
4  await client.agents.messages.create(agentId, {
5    messages: [{
6      type: "approval",
7      approvalRequestId: toolCall.toolCallId,
8      approve: true,
9    }],
10  });
11}
12
13// After
14if (message.message_type === "approval_request_message") {
15  const toolCalls = message.tool_calls || [];
16  if (toolCalls.length > 0) {
17    const toolCall = toolCalls[0];
18    await client.agents.messages.create(agentId, {
19      messages: [{
20        type: "approval",
21        approval_request_id: toolCall.tool_call_id,
22        approve: true,
23      }],
24    });
25  }
26}

Updating Agent Configuration

1// Before
2await client.agents.modify(agentId, {
3  model: "openai/gpt-4",
4  llmConfig: { temperature: 0.7 }
5});
6const agent = await client.agents.retrieve(agentId);
7const config = agent.llmConfig;
8
9// After
10await client.agents.update(agentId, {
11  model: "openai/gpt-4",
12  llm_config: { temperature: 0.7 }
13});
14const agent = await client.agents.retrieve(agentId);
15const config = agent.llm_config;

Migration Checklist

Use this checklist to ensure a complete migration:

Core SDK Changes:

  • Update package version to 1.0.0-alpha.10 or later
  • Update all imports (client and types)
  • Replace LettaClient with Letta
  • Update client constructor params: token → apiKey, baseUrl → baseURL
  • Add projectId to client constructor if using multi-project setup
  • Convert all property names from camelCase to snake_case
  • Replace enum references with string literals
  • Convert Date objects to ISO strings where required
  • Update type annotations to use new import paths

Method Renames:

  • Update modify() calls to update()
  • Update createStream() calls to stream()
  • Rename summarize_agent_conversation() → messages.summarize()
  • Rename cancel_agent_run() → messages.cancel()
  • Rename preview_raw_payload() → messages.preview()
  • Rename list_agent_files() → files.list()
  • Rename export_agent_serialized() → export()
  • Rename import_agent_serialized() → import()
  • Rename folder/provider method names (see section 2)
  • Update telemetry routes to use steps.trace()

Pagination:

  • Update all list methods to access .items property
  • Replace sort_by with order_by in agents.list()
  • Replace ascending with order parameter
  • Update pagination parameters: before, after, limit, order
  • Handle cursor-based pagination for all list endpoints

Message Handling:

  • Handle tool_calls as an array instead of single object
  • Update identity_ids references to use identities (full objects)
  • Replace agent.memory with agent.blocks
  • Update step.messages to use steps.messages.list()
  • Consider using new input shorthand for simple messages

Deprecations:

  • Remove usage of deprecated search endpoints
  • Replace list_active() with list(active=True)
  • Remove use_assistant_message parameter
  • Replace tool_exec_environment_variables with secrets
  • Remove template-related fields from agent/block objects
  • Replace sources endpoints with folders
  • Replace passages endpoints with archives

New Features:

  • Update attach/detach methods (now return None)
  • Use new archive management APIs if needed
  • Update agent import to use override_name instead of append_copy_suffix
  • Move query parameters to request body for affected endpoints
  • Use new agent configuration parameters (temperature, top_p, etc.)

MCP (Model Context Protocol) Changes:

  • Migrate from client.tools.mcp.servers to client.mcp_servers
  • Update MCP server references to use IDs instead of names
  • Update MCP tool references to use IDs instead of names
  • Remove manual tool “add” operations (tools auto-sync on server create)
  • Replace resync() calls with refresh()
  • Replace execute() calls with run()
  • Add server/tool ID lookup logic if using names
  • Update OAuth connection flow to use server IDs

Testing:

  • Test all agent operations (create, update, message)
  • Test streaming and approval flows
  • Verify memory block operations still work
  • Test pagination on list endpoints
  • Test archive management if used
  • Verify identity/block attach/detach operations
  • Test agent import/export

Automated Migration Tools

Find and Replace Script

Use this script to help automate common replacements:

$# Install dependencies
>npm install -g jscodeshift
>
># Run find-and-replace (adjust paths as needed)
>find src -name "*.ts" -o -name "*.tsx" | xargs sed -i '' \
>  -e 's/LettaClient/Letta/g' \
>  -e 's/\.modify(/.update(/g' \
>  -e 's/\.createStream(/.stream(/g' \
>  -e 's/\.messageType/.message_type/g' \
>  -e 's/\.toolCall/.tool_calls/g' \
>  -e 's/\.toolCallId/.tool_call_id/g' \
>  -e 's/\.toolReturn/.tool_return/g' \
>  -e 's/llmConfig/llm_config/g' \
>  -e 's/streamTokens/stream_tokens/g' \
>  -e 's/\.tools\.mcp\.servers/\.mcp_servers/g' \
>  -e 's/\.resync(/\.refresh(/g'
>
># Note: MCP server/tool name -> ID migration requires manual intervention
># as you need to fetch IDs from the API

Always review automated changes! These scripts help with common patterns but cannot handle all edge cases. Test thoroughly after migration.

Troubleshooting

”Property ‘llmConfig’ does not exist” (TypeScript)

Cause: Property renamed to llm_config

Fix: Update all references to use snake_case

1- agent.llmConfig
2+ agent.llm_config

”Cannot read property ‘toolCallId’ of undefined”

Cause: tool_call changed to tool_calls (array)

Fix: Access the first element of the array

1- const id = message.toolCall.toolCallId;
2+ const toolCalls = message.tool_calls || [];
3+ const id = toolCalls[0]?.tool_call_id;

”items is not iterable”

Cause: Trying to iterate over page object instead of items array

Fix: Access the .items property first

1- for (const message of messages) {
2+ const messagesPage = await client.agents.messages.list(agentId);
3+ for (const message of messagesPage.items) {

”Cannot find module ‘@letta-ai/letta-client/resources/…’”

Cause: Types moved to subpath exports

Fix: Update imports to use new subpaths

1- import { Letta } from "@letta-ai/letta-client";
2+ import type { Block } from "@letta-ai/letta-client/resources/agents/agents";

”Method ‘modify’ does not exist”

Cause: Method renamed to update

Fix: Update all modify calls

1- await client.agents.modify(agentId, updates)
2+ await client.agents.update(agentId, updates)

”Cannot access property ‘identity_ids’”

Cause: Field renamed to identities and now returns full objects

Fix: Access the identities array and extract IDs if needed

1- const ids = agent.identity_ids;
2+ const identities = agent.identities;
3+ const ids = identities.map(i => i.id);

”Pagination parameters ‘sort_by’ or ‘ascending’ not recognized”

Cause: Pagination parameters standardized to order_by and order

Fix: Update parameter names

1- await client.agents.list({ sort_by: "created_at", ascending: true })
2+ await client.agents.list({ order_by: "created_at", order: "asc" })

”Attach/detach methods return undefined”

Cause: These methods now return None/void instead of updated state

Fix: Fetch the object separately if you need the updated state

1await client.agents.tools.attach(agentId, toolId);
2const agent = await client.agents.retrieve(agentId);  // Get updated state

”Cannot find method ‘summarize_agent_conversation’”

Cause: Method moved to messages subresource

Fix: Use the new path

1- await client.agents.summarize_agent_conversation(agentId)
2+ await client.agents.messages.summarize(agentId)

”Query parameter ‘add_default_initial_messages’ not working”

Cause: Parameter moved from query to request body

Fix: Pass as request body parameter

1- await client.agents.messages.reset(agentId, { params: { add_default_initial_messages: false } })
2+ await client.agents.messages.reset(agentId, { add_default_initial_messages: false })

”Cannot find ‘client.tools.mcp.servers’”

Cause: MCP routes moved to new namespace

Fix: Use new MCP server methods

1- await client.tools.mcp.servers.list()
2+ await client.mcp_servers.list()

”MCP server not found by name”

Cause: MCP methods now use server IDs instead of names

Fix: Lookup server ID from name first

1// Get server ID from name
2const servers = await client.mcp_servers.list();
3const myServer = servers.find(s => s.name === "my-server");
4const serverId = myServer.id;
5
6// Use ID for subsequent operations
7await client.mcp_servers.tools.list(serverId);

”MCP tool ‘toolName’ not found”

Cause: MCP tool execution now uses tool IDs instead of names

Fix: Lookup tool ID from name first

1const tools = await client.mcp_servers.tools.list(serverId);
2const myTool = tools.find(t => t.name === "my-tool");
3const toolId = myTool.id;
4
5await client.mcp_servers.tools.run(serverId, toolId, { args });

”Method ‘execute’ not found on mcp_servers.tools”

Cause: Method renamed from execute() to run()

Fix: Use the new method name

1- await client.mcp_servers.tools.execute(serverId, toolId, { args })
2+ await client.mcp_servers.tools.run(serverId, toolId, { args })

Additional Resources

Getting Help

If you encounter issues during migration:

  1. Check the Changelog for detailed release notes
  2. Search GitHub Issues for known problems
  3. Ask in Discord #dev-help for community support
  4. Contact support@letta.com for enterprise support