Modify Message

client.agents.messages.modify(, , ?): MessageModifyResponse

patch/v1/agents/{agent_id}/messages/{message_id}

Update the details of a message associated with an agent.

ParametersExpand Collapse

messageID: string

The ID of the message in the format 'message-'

minLength44

maxLength44

MessageModifyParams = UpdateSystemMessage | UpdateUserMessage | UpdateReasoningMessage | UpdateAssistantMessage

MessageModifyParamsBase { agent_id, content, message_type }

agent_id: string

Path param: The ID of the agent in the format 'agent-'

minLength42

maxLength42

content: string

Body param: The message content sent by the system (can be a string or an array of multi-modal content parts)

message_type?: "system_message"

Body param:

Accepts one of the following:

"system_message"

UpdateSystemMessage extends MessageModifyParamsBase { agent_id, content, message_type }

UpdateUserMessage extends MessageModifyParamsBase { agent_id, content, message_type }

UpdateReasoningMessage extends MessageModifyParamsBase { agent_id, content, message_type }

UpdateAssistantMessage extends MessageModifyParamsBase { agent_id, content, message_type }

ReturnsExpand Collapse

MessageModifyResponse = SystemMessage { id, content, date, 8 more } | UserMessage { id, content, date, 8 more } | ReasoningMessage { id, date, reasoning, 10 more } | 8 more

A message generated by the system. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system

Accepts one of the following:

SystemMessage { id, content, date, 8 more }

A message generated by the system. Never streamed back on a response, only used for cursor pagination.

id: string

content: string

The message content sent by the system

date: string

is_err?: boolean | null

message_type?: "system_message"

The type of the message.

Accepts one of the following:

"system_message"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null

UserMessage { id, content, date, 8 more }

A message sent by the user. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)

id: string

content: Array<LettaUserMessageContentUnion> | string

The message content sent by the user (can be a string or an array of multi-modal content parts)

Accepts one of the following:

Array<LettaUserMessageContentUnion>

TextContent { text, signature, type }

text: string

The text content of the message.

signature?: string | null

Stores a unique identifier for any reasoning associated with this text content.

type?: "text"

The type of the message.

Accepts one of the following:

"text"

ImageContent { source, type }

source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

Accepts one of the following:

"url"

Base64Image { data, media_type, detail, type }

data: string

The base64 encoded image data.

media_type: string

The media type for the image.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type?: "base64"

The source type for the image.

Accepts one of the following:

"base64"

LettaImage { file_id, data, detail, 2 more }

file_id: string

The unique identifier of the image file persisted in storage.

data?: string | null

The base64 encoded image data.

detail?: string | null

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media_type?: string | null

The media type for the image.

type?: "letta"

The source type for the image.

Accepts one of the following:

"letta"

type?: "image"

The type of the message.

Accepts one of the following:

"image"

string

date: string

is_err?: boolean | null

message_type?: "user_message"

The type of the message.

Accepts one of the following:

"user_message"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null

ReasoningMessage { id, date, reasoning, 10 more }

Representation of an agent's internal reasoning.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step

id: string

date: string

reasoning: string

is_err?: boolean | null

message_type?: "reasoning_message"

The type of the message.

Accepts one of the following:

"reasoning_message"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

signature?: string | null

source?: "reasoner_model" | "non_reasoner_model"

Accepts one of the following:

"reasoner_model"

"non_reasoner_model"

step_id?: string | null

HiddenReasoningMessage { id, date, state, 9 more }

Representation of an agent's internal reasoning where reasoning content has been hidden from the response.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent

id: string

date: string

state: "redacted" | "omitted"

Accepts one of the following:

"redacted"

"omitted"

hidden_reasoning?: string | null

is_err?: boolean | null

message_type?: "hidden_reasoning_message"

The type of the message.

Accepts one of the following:

"hidden_reasoning_message"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null

ToolCallMessage { id, date, tool_call, 9 more }

A message representing a request to call a tool (generated by the LLM to trigger tool execution).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call

id: string

date: string

Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }

Accepts one of the following:

ToolCall { arguments, name, tool_call_id }

arguments: string

tool_call_id: string

ToolCallDelta { arguments, name, tool_call_id }

arguments?: string | null

name?: string | null

tool_call_id?: string | null

is_err?: boolean | null

message_type?: "tool_call_message"

The type of the message.

Accepts one of the following:

"tool_call_message"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null

tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null

Accepts one of the following:

Array<ToolCall { arguments, name, tool_call_id } >

arguments: string

tool_call_id: string

ToolCallDelta { arguments, name, tool_call_id }

arguments?: string | null

name?: string | null

tool_call_id?: string | null

ToolReturnMessage { id, date, status, 13 more }

A message representing the return value of a tool call (generated by Letta executing the requested tool).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support

id: string

date: string

Deprecatedstatus: "success" | "error"

Accepts one of the following:

"success"

"error"

Deprecatedtool_call_id: string

Deprecatedtool_return: string

is_err?: boolean | null

message_type?: "tool_return_message"

The type of the message.

Accepts one of the following:

"tool_return_message"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

Deprecatedstderr?: Array<string> | null

Deprecatedstdout?: Array<string> | null

step_id?: string | null

tool_returns?: Array<ToolReturn { status, tool_call_id, tool_return, 3 more } > | null

status: "success" | "error"

Accepts one of the following:

"success"

"error"

tool_call_id: string

tool_return: string

stderr?: Array<string> | null

stdout?: Array<string> | null

type?: "tool"

The message type to be created.

Accepts one of the following:

"tool"

AssistantMessage { id, content, date, 8 more }

A message sent by the LLM in response to user input. Used in the LLM context.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)

id: string

content: Array<LettaAssistantMessageContentUnion { text, signature, type } > | string

The message content sent by the agent (can be a string or an array of content parts)

Accepts one of the following:

Array<LettaAssistantMessageContentUnion { text, signature, type } >

text: string

The text content of the message.

signature?: string | null

Stores a unique identifier for any reasoning associated with this text content.

type?: "text"

The type of the message.

Accepts one of the following:

"text"

string

date: string

is_err?: boolean | null

message_type?: "assistant_message"

The type of the message.

Accepts one of the following:

"assistant_message"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null

ApprovalRequestMessage { id, date, tool_call, 9 more }

A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call

id: string

date: string

Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }

The tool call that has been requested by the llm to run

Accepts one of the following:

ToolCall { arguments, name, tool_call_id }

arguments: string

tool_call_id: string

ToolCallDelta { arguments, name, tool_call_id }

arguments?: string | null

name?: string | null

tool_call_id?: string | null

is_err?: boolean | null

message_type?: "approval_request_message"

The type of the message.

Accepts one of the following:

"approval_request_message"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null

tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null

The tool calls that have been requested by the llm to run, which are pending approval

Accepts one of the following:

Array<ToolCall { arguments, name, tool_call_id } >

arguments: string

tool_call_id: string

ToolCallDelta { arguments, name, tool_call_id }

arguments?: string | null

name?: string | null

tool_call_id?: string | null

ApprovalResponseMessage { id, date, approval_request_id, 11 more }

A message representing a response form the user indicating whether a tool has been approved to run.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status

id: string

date: string

Deprecatedapproval_request_id?: string | null

The message ID of the approval request

approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | ToolReturn { status, tool_call_id, tool_return, 3 more } > | null

The list of approval responses

Accepts one of the following:

ApprovalReturn { approve, tool_call_id, reason, type }

approve: boolean

Whether the tool has been approved

tool_call_id: string

The ID of the tool call that corresponds to this approval

reason?: string | null

An optional explanation for the provided approval status

type?: "approval"

The message type to be created.

Accepts one of the following:

"approval"

ToolReturn { status, tool_call_id, tool_return, 3 more }

status: "success" | "error"

Accepts one of the following:

"success"

"error"

tool_call_id: string

tool_return: string

stderr?: Array<string> | null

stdout?: Array<string> | null

type?: "tool"

The message type to be created.

Accepts one of the following:

"tool"

Deprecatedapprove?: boolean | null

Whether the tool has been approved

is_err?: boolean | null

message_type?: "approval_response_message"

The type of the message.

Accepts one of the following:

"approval_response_message"

name?: string | null

otid?: string | null

Deprecatedreason?: string | null

An optional explanation for the provided approval status

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null

SummaryMessage { id, date, summary, 8 more }

A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.

id: string

date: string

summary: string

is_err?: boolean | null

message_type?: "summary"

Accepts one of the following:

"summary"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null

EventMessage { id, date, event_data, 9 more }

A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.

id: string

date: string

event_data: Record<string, unknown>

event_type: "compaction"

Accepts one of the following:

"compaction"

is_err?: boolean | null

message_type?: "event"

Accepts one of the following:

"event"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null

Modify Message

import Letta from '@letta-ai/letta-client';

const client = new Letta({
  apiKey: 'My API Key',
});

const response = await client.agents.messages.modify('message-123e4567-e89b-42d3-8456-426614174000', {
  agent_id: 'agent-123e4567-e89b-42d3-8456-426614174000',
  content: 'content',
});

console.log(response);

{
  "id": "id",
  "content": "content",
  "date": "2019-12-27T18:11:19.117Z",
  "is_err": true,
  "message_type": "system_message",
  "name": "name",
  "otid": "otid",
  "run_id": "run_id",
  "sender_id": "sender_id",
  "seq_id": 0,
  "step_id": "step_id"
}

Returns Examples

{
  "id": "id",
  "content": "content",
  "date": "2019-12-27T18:11:19.117Z",
  "is_err": true,
  "message_type": "system_message",
  "name": "name",
  "otid": "otid",
  "run_id": "run_id",
  "sender_id": "sender_id",
  "seq_id": 0,
  "step_id": "step_id"
}