Messages
List Messages
Create Message
Update Message
Create Message Streaming
Cancel Message
Create Message Async
Reset Messages
Summarize Messages
ModelsExpand Collapse
ApprovalCreate = object { approval_request_id, approvals, approve, 3 more }
Input to approve or deny a tool call request
Deprecatedapproval_request_id: optional string
The message ID of the approval request
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ApprovalReturn = object { 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: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
ToolReturn = object { status, tool_call_id, tool_return, 3 more }
status: "success" or "error"
type: optional "tool"
The message type to be created.
Deprecatedapprove: optional boolean
Whether the tool has been approved
group_id: optional string
The multi-agent group that the message was sent in
Deprecatedreason: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
ApprovalRequestMessage = object { 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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool call that has been requested by the llm to run
ToolCall = object { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
message_type: optional "approval_request_message"
The type of the message.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool calls that have been requested by the llm to run, which are pending approval
ToolCallDelta = object { arguments, name, tool_call_id }
ApprovalResponseMessage = object { 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
Deprecatedapproval_request_id: optional string
The message ID of the approval request
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ApprovalReturn = object { 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: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
ToolReturn = object { status, tool_call_id, tool_return, 3 more }
status: "success" or "error"
type: optional "tool"
The message type to be created.
Deprecatedapprove: optional boolean
Whether the tool has been approved
message_type: optional "approval_response_message"
The type of the message.
Deprecatedreason: optional string
An optional explanation for the provided approval status
ApprovalReturn = object { 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: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
AssistantMessage = object { 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)
The message content sent by the agent (can be a string or an array of content parts)
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
message_type: optional "assistant_message"
The type of the message.
EventMessage = object { 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.
event_type: "compaction"
message_type: optional "event"
HiddenReasoningMessage = object { 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
state: "redacted" or "omitted"
message_type: optional "hidden_reasoning_message"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
InternalMessage = object { id, role, agent_id, 21 more }
Letta's internal representation of a message. Includes methods to convert to/from LLM provider formats.
Attributes:
id (str): The unique identifier of the message.
role (MessageRole): The role of the participant.
text (str): The text of the message.
user_id (str): The unique identifier of the user.
agent_id (str): The unique identifier of the agent.
model (str): The model used to make the function call.
name (str): The name of the participant.
created_at (datetime): The time the message was created.
tool_calls (List[OpenAIToolCall,]): The list of tool calls requested.
tool_call_id (str): The id of the tool call.
step_id (str): The id of the step that this message was created in.
otid (str): The offline threading id associated with this message.
tool_returns (List[ToolReturn]): The list of tool returns requested.
group_id (str): The multi-agent group that the message was sent in.
sender_id (str): The id of the sender of the message, can be an identity id or agent id.
t
id: string
The human-friendly ID of the Message
The role of the participant.
agent_id: optional string
The unique identifier of the agent.
approval_request_id: optional string
The id of the approval request if this message is associated with a tool call request.
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or object { status, func_response, stderr, 2 more }
The list of approvals for this message.
ApprovalReturn = object { 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: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
LettaSchemasMessageToolReturn = object { status, func_response, stderr, 2 more }
status: "success" or "error"
The status of the tool call
func_response: optional string
The function response string
stderr: optional array of string
Captured stderr from the tool invocation
stdout: optional array of string
Captured stdout (e.g. prints, logs) from the tool invocation
tool_call_id: optional unknown
The ID for the tool call
approve: optional boolean
Whether tool call is approved.
batch_item_id: optional string
The id of the LLMBatchItem that this message is associated with
content: optional array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more
The content of the message.
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
ToolCallContent = object { id, input, name, 2 more }
id: string
A unique identifier for this specific tool call instance.
input: map[unknown]
The parameters being passed to the tool, structured as a dictionary of parameter names to values.
name: string
The name of the tool being called.
signature: optional string
Stores a unique identifier for any reasoning associated with this tool call.
type: optional "tool_call"
Indicates this content represents a tool call event.
ToolReturnContent = object { content, is_error, tool_call_id, type }
content: string
The content returned by the tool execution.
is_error: boolean
Indicates whether the tool execution resulted in an error.
tool_call_id: string
References the ID of the ToolCallContent that initiated this tool call.
type: optional "tool_return"
Indicates this content represents a tool return event.
ReasoningContent = object { is_native, reasoning, signature, type }
Sent via the Anthropic Messages API
is_native: boolean
Whether the reasoning content was generated by a reasoner model that processed this step.
reasoning: string
The intermediate reasoning or thought process content.
signature: optional string
A unique identifier for this reasoning step.
type: optional "reasoning"
Indicates this is a reasoning/intermediate step.
RedactedReasoningContent = object { data, type }
Sent via the Anthropic Messages API
data: string
The redacted or filtered intermediate reasoning content.
type: optional "redacted_reasoning"
Indicates this is a redacted thinking step.
OmittedReasoningContent = object { signature, type }
A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
signature: optional string
A unique identifier for this reasoning step.
type: optional "omitted_reasoning"
Indicates this is an omitted reasoning step.
SummarizedReasoning = object { id, summary, encrypted_content, type }
The style of reasoning content returned by the OpenAI Responses API
id: string
The unique identifier for this reasoning step.
summary: array of object { index, text }
Summaries of the reasoning content.
index: number
The index of the summary part.
text: string
The text of the summary part.
encrypted_content: optional string
The encrypted reasoning content.
type: optional "summarized_reasoning"
Indicates this is a summarized reasoning step.
created_at: optional string
The timestamp when the object was created.
created_by_id: optional string
The id of the user that made this object.
denial_reason: optional string
The reason the tool call request was denied.
group_id: optional string
The multi-agent group that the message was sent in
is_err: optional boolean
Whether this message is part of an error step. Used only for debugging purposes.
last_updated_by_id: optional string
The id of the user that made this object.
model: optional string
The model used to make the function call.
name: optional string
For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.
otid: optional string
The offline threading id associated with this message
run_id: optional string
The id of the run that this message was created in.
sender_id: optional string
The id of the sender of the message, can be an identity id or agent id
step_id: optional string
The id of the step that this message was created in.
tool_call_id: optional string
The ID of the tool call. Only applicable for role tool.
tool_calls: optional array of object { id, function, type }
The list of tool calls requested. Only applicable for role assistant.
function: object { arguments, name }
type: "function"
tool_returns: optional array of object { status, func_response, stderr, 2 more }
Tool execution return information for prior tool calls
status: "success" or "error"
The status of the tool call
func_response: optional string
The function response string
stderr: optional array of string
Captured stderr from the tool invocation
stdout: optional array of string
Captured stdout (e.g. prints, logs) from the tool invocation
tool_call_id: optional unknown
The ID for the tool call
updated_at: optional string
The timestamp when the object was last updated.
JobStatus = "created" or "running" or "completed" or 4 more
Status of the job.
JobType = "job" or "run" or "batch"
LettaAssistantMessageContentUnion = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
LettaRequest = object { assistant_message_tool_kwarg, assistant_message_tool_name, enable_thinking, 5 more }
Deprecatedassistant_message_tool_kwarg: optional string
The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
Deprecatedassistant_message_tool_name: optional string
The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
Deprecatedenable_thinking: optional string
If set to True, enables reasoning before responses or tool calls from the agent.
Only return specified message types in the response. If None (default) returns all messages.
input: optional string or array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more
Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}].
UnionMember1 = array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
ToolCallContent = object { id, input, name, 2 more }
id: string
A unique identifier for this specific tool call instance.
input: map[unknown]
The parameters being passed to the tool, structured as a dictionary of parameter names to values.
name: string
The name of the tool being called.
signature: optional string
Stores a unique identifier for any reasoning associated with this tool call.
type: optional "tool_call"
Indicates this content represents a tool call event.
ToolReturnContent = object { content, is_error, tool_call_id, type }
content: string
The content returned by the tool execution.
is_error: boolean
Indicates whether the tool execution resulted in an error.
tool_call_id: string
References the ID of the ToolCallContent that initiated this tool call.
type: optional "tool_return"
Indicates this content represents a tool return event.
ReasoningContent = object { is_native, reasoning, signature, type }
Sent via the Anthropic Messages API
is_native: boolean
Whether the reasoning content was generated by a reasoner model that processed this step.
reasoning: string
The intermediate reasoning or thought process content.
signature: optional string
A unique identifier for this reasoning step.
type: optional "reasoning"
Indicates this is a reasoning/intermediate step.
RedactedReasoningContent = object { data, type }
Sent via the Anthropic Messages API
data: string
The redacted or filtered intermediate reasoning content.
type: optional "redacted_reasoning"
Indicates this is a redacted thinking step.
OmittedReasoningContent = object { signature, type }
A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
signature: optional string
A unique identifier for this reasoning step.
type: optional "omitted_reasoning"
Indicates this is an omitted reasoning step.
SummarizedReasoning = object { id, summary, encrypted_content, type }
The style of reasoning content returned by the OpenAI Responses API
id: string
The unique identifier for this reasoning step.
summary: array of object { index, text }
Summaries of the reasoning content.
index: number
The index of the summary part.
text: string
The text of the summary part.
encrypted_content: optional string
The encrypted reasoning content.
type: optional "summarized_reasoning"
Indicates this is a summarized reasoning step.
max_steps: optional number
Maximum number of steps the agent should take to process the request.
messages: optional array of MessageCreate { content, role, batch_item_id, 5 more } or ApprovalCreate { approval_request_id, approvals, approve, 3 more }
The messages to be sent to the agent.
MessageCreate = object { content, role, batch_item_id, 5 more }
Request to create a message
The content of the message.
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
ToolCallContent = object { id, input, name, 2 more }
id: string
A unique identifier for this specific tool call instance.
input: map[unknown]
The parameters being passed to the tool, structured as a dictionary of parameter names to values.
name: string
The name of the tool being called.
signature: optional string
Stores a unique identifier for any reasoning associated with this tool call.
type: optional "tool_call"
Indicates this content represents a tool call event.
ToolReturnContent = object { content, is_error, tool_call_id, type }
content: string
The content returned by the tool execution.
is_error: boolean
Indicates whether the tool execution resulted in an error.
tool_call_id: string
References the ID of the ToolCallContent that initiated this tool call.
type: optional "tool_return"
Indicates this content represents a tool return event.
ReasoningContent = object { is_native, reasoning, signature, type }
Sent via the Anthropic Messages API
is_native: boolean
Whether the reasoning content was generated by a reasoner model that processed this step.
reasoning: string
The intermediate reasoning or thought process content.
signature: optional string
A unique identifier for this reasoning step.
type: optional "reasoning"
Indicates this is a reasoning/intermediate step.
RedactedReasoningContent = object { data, type }
Sent via the Anthropic Messages API
data: string
The redacted or filtered intermediate reasoning content.
type: optional "redacted_reasoning"
Indicates this is a redacted thinking step.
OmittedReasoningContent = object { signature, type }
A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
signature: optional string
A unique identifier for this reasoning step.
type: optional "omitted_reasoning"
Indicates this is an omitted reasoning step.
role: "user" or "system" or "assistant"
The role of the participant.
batch_item_id: optional string
The id of the LLMBatchItem that this message is associated with
group_id: optional string
The multi-agent group that the message was sent in
name: optional string
The name of the participant.
otid: optional string
The offline threading id associated with this message
sender_id: optional string
The id of the sender of the message, can be an identity id or agent id
type: optional "message"
The message type to be created.
ApprovalCreate = object { approval_request_id, approvals, approve, 3 more }
Input to approve or deny a tool call request
Deprecatedapproval_request_id: optional string
The message ID of the approval request
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ApprovalReturn = object { 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: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
ToolReturn = object { status, tool_call_id, tool_return, 3 more }
status: "success" or "error"
type: optional "tool"
The message type to be created.
Deprecatedapprove: optional boolean
Whether the tool has been approved
group_id: optional string
The multi-agent group that the message was sent in
Deprecatedreason: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
Deprecateduse_assistant_message: optional boolean
Whether the server should parse specific tool call arguments (default send_message) as AssistantMessage objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
LettaResponse = object { messages, stop_reason, usage }
Response object from an agent interaction, consisting of the new messages generated by the agent and usage statistics.
The type of the returned messages can be either Message or LettaMessage, depending on what was specified in the request.
Attributes: messages (List[Union[Message, LettaMessage]]): The messages returned by the agent. usage (LettaUsageStatistics): The usage statistics
The messages returned by the agent.
SystemMessage = object { id, content, date, 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
content: string
The message content sent by the system
message_type: optional "system_message"
The type of the message.
UserMessage = object { 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)
The message content sent by the user (can be a string or an array of multi-modal content parts)
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
message_type: optional "user_message"
The type of the message.
ReasoningMessage = object { 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
message_type: optional "reasoning_message"
The type of the message.
source: optional "reasoner_model" or "non_reasoner_model"
HiddenReasoningMessage = object { 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
state: "redacted" or "omitted"
message_type: optional "hidden_reasoning_message"
The type of the message.
ToolCallMessage = object { 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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
ToolCall = object { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
message_type: optional "tool_call_message"
The type of the message.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
ToolReturnMessage = object { 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
Deprecatedstatus: "success" or "error"
message_type: optional "tool_return_message"
The type of the message.
status: "success" or "error"
type: optional "tool"
The message type to be created.
AssistantMessage = object { 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)
The message content sent by the agent (can be a string or an array of content parts)
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
message_type: optional "assistant_message"
The type of the message.
ApprovalRequestMessage = object { 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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool call that has been requested by the llm to run
ToolCall = object { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
message_type: optional "approval_request_message"
The type of the message.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool calls that have been requested by the llm to run, which are pending approval
ToolCallDelta = object { arguments, name, tool_call_id }
ApprovalResponseMessage = object { 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
Deprecatedapproval_request_id: optional string
The message ID of the approval request
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ApprovalReturn = object { 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: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
ToolReturn = object { status, tool_call_id, tool_return, 3 more }
status: "success" or "error"
type: optional "tool"
The message type to be created.
Deprecatedapprove: optional boolean
Whether the tool has been approved
message_type: optional "approval_response_message"
The type of the message.
Deprecatedreason: optional string
An optional explanation for the provided approval status
SummaryMessage = object { 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.
message_type: optional "summary"
EventMessage = object { 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.
event_type: "compaction"
message_type: optional "event"
stop_reason: object { stop_reason, message_type }
The stop reason from Letta indicating why agent loop stopped execution.
The reason why execution stopped.
message_type: optional "stop_reason"
The type of the message.
usage: object { completion_tokens, message_type, prompt_tokens, 3 more }
The usage statistics of the agent.
completion_tokens: optional number
The number of tokens generated by the agent.
message_type: optional "usage_statistics"
prompt_tokens: optional number
The number of tokens in the prompt.
run_ids: optional array of string
The background task run IDs associated with the agent interaction
step_count: optional number
The number of steps taken by the agent.
total_tokens: optional number
The total number of tokens processed by the agent.
LettaStreamingRequest = object { assistant_message_tool_kwarg, assistant_message_tool_name, background, 9 more }
Deprecatedassistant_message_tool_kwarg: optional string
The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
Deprecatedassistant_message_tool_name: optional string
The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
background: optional boolean
Whether to process the request in the background (only used when streaming=true).
Deprecatedenable_thinking: optional string
If set to True, enables reasoning before responses or tool calls from the agent.
include_pings: optional boolean
Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true).
Only return specified message types in the response. If None (default) returns all messages.
input: optional string or array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more
Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}].
UnionMember1 = array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
ToolCallContent = object { id, input, name, 2 more }
id: string
A unique identifier for this specific tool call instance.
input: map[unknown]
The parameters being passed to the tool, structured as a dictionary of parameter names to values.
name: string
The name of the tool being called.
signature: optional string
Stores a unique identifier for any reasoning associated with this tool call.
type: optional "tool_call"
Indicates this content represents a tool call event.
ToolReturnContent = object { content, is_error, tool_call_id, type }
content: string
The content returned by the tool execution.
is_error: boolean
Indicates whether the tool execution resulted in an error.
tool_call_id: string
References the ID of the ToolCallContent that initiated this tool call.
type: optional "tool_return"
Indicates this content represents a tool return event.
ReasoningContent = object { is_native, reasoning, signature, type }
Sent via the Anthropic Messages API
is_native: boolean
Whether the reasoning content was generated by a reasoner model that processed this step.
reasoning: string
The intermediate reasoning or thought process content.
signature: optional string
A unique identifier for this reasoning step.
type: optional "reasoning"
Indicates this is a reasoning/intermediate step.
RedactedReasoningContent = object { data, type }
Sent via the Anthropic Messages API
data: string
The redacted or filtered intermediate reasoning content.
type: optional "redacted_reasoning"
Indicates this is a redacted thinking step.
OmittedReasoningContent = object { signature, type }
A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
signature: optional string
A unique identifier for this reasoning step.
type: optional "omitted_reasoning"
Indicates this is an omitted reasoning step.
SummarizedReasoning = object { id, summary, encrypted_content, type }
The style of reasoning content returned by the OpenAI Responses API
id: string
The unique identifier for this reasoning step.
summary: array of object { index, text }
Summaries of the reasoning content.
index: number
The index of the summary part.
text: string
The text of the summary part.
encrypted_content: optional string
The encrypted reasoning content.
type: optional "summarized_reasoning"
Indicates this is a summarized reasoning step.
max_steps: optional number
Maximum number of steps the agent should take to process the request.
messages: optional array of MessageCreate { content, role, batch_item_id, 5 more } or ApprovalCreate { approval_request_id, approvals, approve, 3 more }
The messages to be sent to the agent.
MessageCreate = object { content, role, batch_item_id, 5 more }
Request to create a message
The content of the message.
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
ToolCallContent = object { id, input, name, 2 more }
id: string
A unique identifier for this specific tool call instance.
input: map[unknown]
The parameters being passed to the tool, structured as a dictionary of parameter names to values.
name: string
The name of the tool being called.
signature: optional string
Stores a unique identifier for any reasoning associated with this tool call.
type: optional "tool_call"
Indicates this content represents a tool call event.
ToolReturnContent = object { content, is_error, tool_call_id, type }
content: string
The content returned by the tool execution.
is_error: boolean
Indicates whether the tool execution resulted in an error.
tool_call_id: string
References the ID of the ToolCallContent that initiated this tool call.
type: optional "tool_return"
Indicates this content represents a tool return event.
ReasoningContent = object { is_native, reasoning, signature, type }
Sent via the Anthropic Messages API
is_native: boolean
Whether the reasoning content was generated by a reasoner model that processed this step.
reasoning: string
The intermediate reasoning or thought process content.
signature: optional string
A unique identifier for this reasoning step.
type: optional "reasoning"
Indicates this is a reasoning/intermediate step.
RedactedReasoningContent = object { data, type }
Sent via the Anthropic Messages API
data: string
The redacted or filtered intermediate reasoning content.
type: optional "redacted_reasoning"
Indicates this is a redacted thinking step.
OmittedReasoningContent = object { signature, type }
A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
signature: optional string
A unique identifier for this reasoning step.
type: optional "omitted_reasoning"
Indicates this is an omitted reasoning step.
role: "user" or "system" or "assistant"
The role of the participant.
batch_item_id: optional string
The id of the LLMBatchItem that this message is associated with
group_id: optional string
The multi-agent group that the message was sent in
name: optional string
The name of the participant.
otid: optional string
The offline threading id associated with this message
sender_id: optional string
The id of the sender of the message, can be an identity id or agent id
type: optional "message"
The message type to be created.
ApprovalCreate = object { approval_request_id, approvals, approve, 3 more }
Input to approve or deny a tool call request
Deprecatedapproval_request_id: optional string
The message ID of the approval request
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ApprovalReturn = object { 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: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
ToolReturn = object { status, tool_call_id, tool_return, 3 more }
status: "success" or "error"
type: optional "tool"
The message type to be created.
Deprecatedapprove: optional boolean
Whether the tool has been approved
group_id: optional string
The multi-agent group that the message was sent in
Deprecatedreason: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
stream_tokens: optional boolean
Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true).
streaming: optional boolean
If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response.
Deprecateduse_assistant_message: optional boolean
Whether the server should parse specific tool call arguments (default send_message) as AssistantMessage objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
LettaStreamingResponse = SystemMessage { id, content, date, 8 more } or UserMessage { id, content, date, 8 more } or ReasoningMessage { id, date, reasoning, 10 more } or 9 more
Streaming response type for Server-Sent Events (SSE) endpoints. Each event in the stream will be one of these types.
SystemMessage = object { id, content, date, 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
content: string
The message content sent by the system
message_type: optional "system_message"
The type of the message.
UserMessage = object { 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)
The message content sent by the user (can be a string or an array of multi-modal content parts)
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
message_type: optional "user_message"
The type of the message.
ReasoningMessage = object { 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
message_type: optional "reasoning_message"
The type of the message.
source: optional "reasoner_model" or "non_reasoner_model"
HiddenReasoningMessage = object { 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
state: "redacted" or "omitted"
message_type: optional "hidden_reasoning_message"
The type of the message.
ToolCallMessage = object { 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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
ToolCall = object { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
message_type: optional "tool_call_message"
The type of the message.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
ToolReturnMessage = object { 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
Deprecatedstatus: "success" or "error"
message_type: optional "tool_return_message"
The type of the message.
status: "success" or "error"
type: optional "tool"
The message type to be created.
AssistantMessage = object { 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)
The message content sent by the agent (can be a string or an array of content parts)
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
message_type: optional "assistant_message"
The type of the message.
ApprovalRequestMessage = object { 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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool call that has been requested by the llm to run
ToolCall = object { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
message_type: optional "approval_request_message"
The type of the message.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool calls that have been requested by the llm to run, which are pending approval
ToolCallDelta = object { arguments, name, tool_call_id }
ApprovalResponseMessage = object { 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
Deprecatedapproval_request_id: optional string
The message ID of the approval request
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ApprovalReturn = object { 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: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
ToolReturn = object { status, tool_call_id, tool_return, 3 more }
status: "success" or "error"
type: optional "tool"
The message type to be created.
Deprecatedapprove: optional boolean
Whether the tool has been approved
message_type: optional "approval_response_message"
The type of the message.
Deprecatedreason: optional string
An optional explanation for the provided approval status
Ping = object { message_type }
Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests.
message_type: "ping"
The type of the message.
StopReason = object { stop_reason, message_type }
The stop reason from Letta indicating why agent loop stopped execution.
The reason why execution stopped.
message_type: optional "stop_reason"
The type of the message.
UsageStatistics = object { completion_tokens, message_type, prompt_tokens, 3 more }
Usage statistics for the agent interaction.
Attributes: completion_tokens (int): The number of tokens generated by the agent. prompt_tokens (int): The number of tokens in the prompt. total_tokens (int): The total number of tokens processed by the agent. step_count (int): The number of steps taken by the agent.
completion_tokens: optional number
The number of tokens generated by the agent.
message_type: optional "usage_statistics"
prompt_tokens: optional number
The number of tokens in the prompt.
run_ids: optional array of string
The background task run IDs associated with the agent interaction
step_count: optional number
The number of steps taken by the agent.
total_tokens: optional number
The total number of tokens processed by the agent.
LettaUserMessageContentUnion = TextContent { text, signature, type } or ImageContent { source, type }
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
Message = SystemMessage { id, content, date, 8 more } or UserMessage { id, content, date, 8 more } or ReasoningMessage { id, date, reasoning, 10 more } or 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
SystemMessage = object { id, content, date, 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
content: string
The message content sent by the system
message_type: optional "system_message"
The type of the message.
UserMessage = object { 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)
The message content sent by the user (can be a string or an array of multi-modal content parts)
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
message_type: optional "user_message"
The type of the message.
ReasoningMessage = object { 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
message_type: optional "reasoning_message"
The type of the message.
source: optional "reasoner_model" or "non_reasoner_model"
HiddenReasoningMessage = object { 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
state: "redacted" or "omitted"
message_type: optional "hidden_reasoning_message"
The type of the message.
ToolCallMessage = object { 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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
ToolCall = object { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
message_type: optional "tool_call_message"
The type of the message.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
ToolReturnMessage = object { 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
Deprecatedstatus: "success" or "error"
message_type: optional "tool_return_message"
The type of the message.
status: "success" or "error"
type: optional "tool"
The message type to be created.
AssistantMessage = object { 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)
The message content sent by the agent (can be a string or an array of content parts)
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
message_type: optional "assistant_message"
The type of the message.
ApprovalRequestMessage = object { 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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool call that has been requested by the llm to run
ToolCall = object { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
message_type: optional "approval_request_message"
The type of the message.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool calls that have been requested by the llm to run, which are pending approval
ToolCallDelta = object { arguments, name, tool_call_id }
ApprovalResponseMessage = object { 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
Deprecatedapproval_request_id: optional string
The message ID of the approval request
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ApprovalReturn = object { 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: optional string
An optional explanation for the provided approval status
type: optional "approval"
The message type to be created.
ToolReturn = object { status, tool_call_id, tool_return, 3 more }
status: "success" or "error"
type: optional "tool"
The message type to be created.
Deprecatedapprove: optional boolean
Whether the tool has been approved
message_type: optional "approval_response_message"
The type of the message.
Deprecatedreason: optional string
An optional explanation for the provided approval status
SummaryMessage = object { 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.
message_type: optional "summary"
EventMessage = object { 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.
event_type: "compaction"
message_type: optional "event"
MessageRole = "assistant" or "user" or "tool" or 3 more
MessageType = "system_message" or "user_message" or "assistant_message" or 6 more
OmittedReasoningContent = object { signature, type }
A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
signature: optional string
A unique identifier for this reasoning step.
type: optional "omitted_reasoning"
Indicates this is an omitted reasoning step.
ReasoningContent = object { is_native, reasoning, signature, type }
Sent via the Anthropic Messages API
is_native: boolean
Whether the reasoning content was generated by a reasoner model that processed this step.
reasoning: string
The intermediate reasoning or thought process content.
signature: optional string
A unique identifier for this reasoning step.
type: optional "reasoning"
Indicates this is a reasoning/intermediate step.
ReasoningMessage = object { 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
message_type: optional "reasoning_message"
The type of the message.
source: optional "reasoner_model" or "non_reasoner_model"
RedactedReasoningContent = object { data, type }
Sent via the Anthropic Messages API
data: string
The redacted or filtered intermediate reasoning content.
type: optional "redacted_reasoning"
Indicates this is a redacted thinking step.
Run = object { id, agent_id, background, 13 more }
Representation of a run - a conversation or processing session for an agent. Runs track when agents process messages and maintain the relationship between agents, steps, and messages.
id: string
The human-friendly ID of the Run
agent_id: string
The unique identifier of the agent associated with the run.
background: optional boolean
Whether the run was created in background mode.
base_template_id: optional string
The base template ID that the run belongs to.
callback_error: optional string
Optional error message from attempting to POST the callback endpoint.
callback_sent_at: optional string
Timestamp when the callback was last attempted.
callback_status_code: optional number
HTTP status code returned by the callback endpoint.
callback_url: optional string
If set, POST to this URL when the run completes.
completed_at: optional string
The timestamp when the run was completed.
created_at: optional string
The timestamp when the run was created.
metadata: optional map[unknown]
Additional metadata for the run.
request_config: optional object { assistant_message_tool_kwarg, assistant_message_tool_name, include_return_message_types, use_assistant_message }
The request configuration for the run.
assistant_message_tool_kwarg: optional string
The name of the message argument in the designated message tool.
assistant_message_tool_name: optional string
The name of the designated message tool.
Only return specified message types in the response. If None (default) returns all messages.
use_assistant_message: optional boolean
Whether the server should parse specific tool call arguments (default send_message) as AssistantMessage objects.
status: optional "created" or "running" or "completed" or 2 more
The current status of the run.
The reason why the run was stopped.
total_duration_ns: optional number
Total run duration in nanoseconds
ttft_ns: optional number
Time to first token for a run in nanoseconds
SummaryMessage = object { 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.
message_type: optional "summary"
SystemMessage = object { id, content, date, 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
content: string
The message content sent by the system
message_type: optional "system_message"
The type of the message.
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ToolCall = object { arguments, name, tool_call_id }
ToolCallContent = object { id, input, name, 2 more }
id: string
A unique identifier for this specific tool call instance.
input: map[unknown]
The parameters being passed to the tool, structured as a dictionary of parameter names to values.
name: string
The name of the tool being called.
signature: optional string
Stores a unique identifier for any reasoning associated with this tool call.
type: optional "tool_call"
Indicates this content represents a tool call event.
ToolCallDelta = object { arguments, name, tool_call_id }
ToolCallMessage = object { 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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
ToolCall = object { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
message_type: optional "tool_call_message"
The type of the message.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
ToolCallDelta = object { arguments, name, tool_call_id }
ToolReturn = object { status, tool_call_id, tool_return, 3 more }
status: "success" or "error"
type: optional "tool"
The message type to be created.
ToolReturnContent = object { content, is_error, tool_call_id, type }
content: string
The content returned by the tool execution.
is_error: boolean
Indicates whether the tool execution resulted in an error.
tool_call_id: string
References the ID of the ToolCallContent that initiated this tool call.
type: optional "tool_return"
Indicates this content represents a tool return event.
UpdateAssistantMessage = object { content, message_type }
The message content sent by the assistant (can be a string or an array of content parts)
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
message_type: optional "assistant_message"
UpdateReasoningMessage = object { reasoning, message_type }
message_type: optional "reasoning_message"
UpdateSystemMessage = object { content, message_type }
content: string
The message content sent by the system (can be a string or an array of multi-modal content parts)
message_type: optional "system_message"
UpdateUserMessage = object { content, message_type }
The message content sent by the user (can be a string or an array of multi-modal content parts)
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
message_type: optional "user_message"
UserMessage = object { 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)
The message content sent by the user (can be a string or an array of multi-modal content parts)
TextContent = object { text, signature, type }
text: string
The text content of the message.
signature: optional string
Stores a unique identifier for any reasoning associated with this text content.
type: optional "text"
The type of the message.
ImageContent = object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
URL = object { url, type }
url: string
The URL of the image.
type: optional "url"
The source type for the image.
Base64 = object { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: optional "base64"
The source type for the image.
Letta = object { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data: optional string
The base64 encoded image data.
detail: optional string
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: optional string
The media type for the image.
type: optional "letta"
The source type for the image.
type: optional "image"
The type of the message.
message_type: optional "user_message"
The type of the message.