Steps

List Steps

client.steps.list(?, ?): ArrayPage<Step { id, agent_id, cache_write_tokens, 27 more } >

GET/v1/steps/

Retrieve Step

client.steps.retrieve(, ?): Step { id, agent_id, cache_write_tokens, 27 more }

GET/v1/steps/{step_id}

ModelsExpand Collapse

ProviderTrace { request_json, response_json, id, 15 more }

Letta’s internal representation of a provider trace.

Attributes: id (str): The unique identifier of the provider trace. request_json (Dict[str, Any]): JSON content of the provider request. response_json (Dict[str, Any]): JSON content of the provider response. step_id (str): ID of the step that this trace is associated with. agent_id (str): ID of the agent that generated this trace. agent_tags (list[str]): Tags associated with the agent for filtering. call_type (str): Type of call (agent_step, summarization, etc.). run_id (str): ID of the run this trace is associated with. source (str): Source service that generated this trace (memgpt-server, lettuce-py). organization_id (str): The unique identifier of the organization. user_id (str): The unique identifier of the user who initiated the request. compaction_settings (Dict[str, Any]): Compaction/summarization settings (only for summarization calls). llm_config (Dict[str, Any]): LLM configuration used for this call (only for non-summarization calls). created_at (datetime): The timestamp when the object was created.

request_json: Record<string, unknown>

JSON content of the provider request

response_json: Record<string, unknown>

JSON content of the provider response

id?: string

The human-friendly ID of the Provider_trace

agent_id?: string | null

ID of the agent that generated this trace

agent_tags?: Array<string> | null

Tags associated with the agent for filtering

billing_context?: BillingContext | null

Billing context for LLM request cost tracking.

cost_source?: string | null

Cost source: ‘quota’ or ‘credits’

customer_id?: string | null

Customer ID for billing records

plan_type?: string | null

Subscription tier

call_type?: string | null

Type of call (agent_step, summarization, etc.)

compaction_settings?: Record<string, unknown> | null

Compaction/summarization settings (summarization calls only)

created_at?: string

The timestamp when the object was created.

formatdate-time

created_by_id?: string | null

The id of the user that made this object.

last_updated_by_id?: string | null

The id of the user that made this object.

latency_ms?: number | null

LLM request latency in milliseconds

llm_config?: Record<string, unknown> | null

LLM configuration used for this call (non-summarization calls only)

org_id?: string | null

ID of the organization

run_id?: string | null

ID of the run this trace is associated with

source?: string | null

Source service that generated this trace (memgpt-server, lettuce-py)

step_id?: string | null

ID of the step that this trace is associated with

updated_at?: string | null

The timestamp when the object was last updated.

formatdate-time

Step { id, agent_id, cache_write_tokens, 27 more }

id: string

The id of the step. Assigned by the database.

agent_id?: string | null

The ID of the agent that performed the step.

cache_write_tokens?: number | null

The number of input tokens written to cache (Anthropic only). None if not reported by provider.

cached_input_tokens?: number | null

The number of input tokens served from cache. None if not reported by provider.

completion_tokens?: number | null

The number of tokens generated by the agent during this step.

completion_tokens_details?: Record<string, unknown> | null

Detailed completion token breakdown (e.g., reasoning_tokens).

context_window_limit?: number | null

The context window limit configured for this step.

error_data?: Record<string, unknown> | null

Error details including message, traceback, and additional context

error_type?: string | null

The type/class of the error that occurred

feedback?: "positive" | "negative" | null

The feedback for this step. Must be either ‘positive’ or ‘negative’.

One of the following:

"positive"

"negative"

Deprecatedmessages?: Array<InternalMessage { id, role, agent_id, 22 more } >

The messages generated during this step. Deprecated: use GET /v1/steps/{step_id}/messages endpoint instead

id: string

The human-friendly ID of the Message

role: MessageRole

The role of the participant.

One of the following:

"assistant"

"user"

"tool"

"function"

"system"

"approval"

"summary"

agent_id?: string | null

The unique identifier of the agent.

approval_request_id?: string | null

The id of the approval request if this message is associated with a tool call request.

approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | LettaSchemasMessageToolReturnOutput { status, func_response, stderr, 2 more } > | null

The list of approvals for this message.

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.

LettaSchemasMessageToolReturnOutput { status, func_response, stderr, 2 more }

status: "success" | "error"

The status of the tool call

One of the following:

"success"

"error"

func_response?: string | Array<TextContent { text, signature, type } | ImageContent { source, type } > | null

The function response - either a string or list of content parts (text/image)

One of the following:

string

Array<TextContent { text, signature, type } | ImageContent { source, type } >

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.

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.

One of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

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.

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.

type?: "image"

The type of the message.

stderr?: Array<string> | null

Captured stderr from the tool invocation

stdout?: Array<string> | null

Captured stdout (e.g. prints, logs) from the tool invocation

tool_call_id?: unknown

The ID for the tool call

approve?: boolean | null

Whether tool call is approved.

batch_item_id?: string | null

The id of the LLMBatchItem that this message is associated with

content?: Array<TextContent { text, signature, type } | ImageContent { source, type } | ToolCallContent { id, input, name, 2 more } | 5 more> | null

The content of the message.

One of the following:

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.

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.

One of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

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.

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.

type?: "image"

The type of the message.

ToolCallContent { id, input, name, 2 more }

id: string

A unique identifier for this specific tool call instance.

input: Record<string, unknown>

The parameters being passed to the tool, structured as a dictionary of parameter names to values.

The name of the tool being called.

signature?: string | null

Stores a unique identifier for any reasoning associated with this tool call.

type?: "tool_call"

Indicates this content represents a tool call event.

ToolReturnContent { 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?: "tool_return"

Indicates this content represents a tool return event.

ReasoningContent { 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?: string | null

A unique identifier for this reasoning step.

type?: "reasoning"

Indicates this is a reasoning/intermediate step.

RedactedReasoningContent { data, type }

Sent via the Anthropic Messages API

data: string

The redacted or filtered intermediate reasoning content.

type?: "redacted_reasoning"

Indicates this is a redacted thinking step.

OmittedReasoningContent { 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?: string | null

A unique identifier for this reasoning step.

type?: "omitted_reasoning"

Indicates this is an omitted reasoning step.

SummarizedReasoningContent { 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<Summary>

Summaries of the reasoning content.

index: number

The index of the summary part.

text: string

The text of the summary part.

encrypted_content?: string

The encrypted reasoning content.

type?: "summarized_reasoning"

Indicates this is a summarized reasoning step.

conversation_id?: string | null

The conversation this message belongs to

created_at?: string

The timestamp when the object was created.

formatdate-time

created_by_id?: string | null

The id of the user that made this object.

denial_reason?: string | null

The reason the tool call request was denied.

group_id?: string | null

The multi-agent group that the message was sent in

is_err?: boolean | null

Whether this message is part of an error step. Used only for debugging purposes.

last_updated_by_id?: string | null

The id of the user that made this object.

model?: string | null

The model used to make the function call.

name?: string | null

For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.

otid?: string | null

The offline threading id associated with this message

run_id?: string | null

The id of the run that this message was created in.

sender_id?: string | null

The id of the sender of the message, can be an identity id or agent id

step_id?: string | null

The id of the step that this message was created in.

tool_call_id?: string | null

The ID of the tool call. Only applicable for role tool.

tool_calls?: Array<ToolCall> | null

The list of tool calls requested. Only applicable for role assistant.

id: string

function: Function { arguments, name }

The function that the model called.

arguments: string

type: "function"

tool_returns?: Array<ToolReturn> | null

Tool execution return information for prior tool calls

status: "success" | "error"

The status of the tool call

One of the following:

"success"

"error"

func_response?: string | Array<TextContent { text, signature, type } | ImageContent { source, type } > | null

The function response - either a string or list of content parts (text/image)

One of the following:

string

Array<TextContent { text, signature, type } | ImageContent { source, type } >

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.

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.

One of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

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.

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.

type?: "image"

The type of the message.

stderr?: Array<string> | null

Captured stderr from the tool invocation

stdout?: Array<string> | null

Captured stdout (e.g. prints, logs) from the tool invocation

tool_call_id?: unknown

The ID for the tool call

updated_at?: string | null

The timestamp when the object was last updated.

formatdate-time

model?: string | null

The name of the model used for this step.

model_endpoint?: string | null

The model endpoint url used for this step.

model_handle?: string | null

The model handle (e.g., ‘openai/gpt-4o-mini’) used for this step.

origin?: string | null

The surface that this agent step was initiated from.

project_id?: string | null

The project that the agent that executed this step belongs to (cloud only).

prompt_tokens?: number | null

The number of tokens in the prompt during this step.

prompt_tokens_details?: Record<string, unknown> | null

Detailed prompt token breakdown (e.g., cached_tokens, cache_read_tokens, cache_creation_tokens).

provider_category?: string | null

The category of the provider used for this step.

provider_id?: string | null

The unique identifier of the provider that was configured for this step

provider_name?: string | null

The name of the provider used for this step.

reasoning_tokens?: number | null

The number of reasoning/thinking tokens generated. None if not reported by provider.

request_id?: string | null

The API request log ID from cloud-api for correlating steps with API requests.

run_id?: string | null

The unique identifier of the run that this step belongs to. Only included for async calls.

status?: "pending" | "success" | "failed" | "cancelled" | null

Status of a step execution

One of the following:

"pending"

"success"

"failed"

"cancelled"

stop_reason?: StopReasonType | null

The stop reason associated with the step.

One of the following:

"end_turn"

"error"

"llm_api_error"

"invalid_llm_response"

"invalid_tool_call"

"max_steps"

"max_tokens_exceeded"

"no_tool_call"

"tool_rule"

"cancelled"

"insufficient_credits"

"requires_approval"

"context_window_overflow_in_system_prompt"

tags?: Array<string>

Metadata tags.

tid?: string | null

The unique identifier of the transaction that processed this step.

total_tokens?: number | null

The total number of tokens processed by the agent during this step.

trace_id?: string | null

The trace id of the agent step.

StepsMetrics

Retrieve Metrics For Step

client.steps.metrics.retrieve(, ?): MetricRetrieveResponse { id, agent_id, base_template_id, 9 more }

GET/v1/steps/{step_id}/metrics

ModelsExpand Collapse

MetricRetrieveResponse { id, agent_id, base_template_id, 9 more }

id: string

The id of the step this metric belongs to (matches steps.id).

agent_id?: string | null

The unique identifier of the agent.

base_template_id?: string | null

The base template ID that the step belongs to (cloud only).

llm_request_ns?: number | null

Time spent on LLM requests in nanoseconds.

llm_request_start_ns?: number | null

The timestamp of the start of the llm request in nanoseconds.

project_id?: string | null

The project that the step belongs to (cloud only).

provider_id?: string | null

The unique identifier of the provider.

run_id?: string | null

The unique identifier of the run.

step_ns?: number | null

Total time for the step in nanoseconds.

step_start_ns?: number | null

The timestamp of the start of the step in nanoseconds.

template_id?: string | null

The template ID that the step belongs to (cloud only).

tool_execution_ns?: number | null

Time spent on tool execution in nanoseconds.

StepsTrace

Retrieve Trace For Step

client.steps.trace.retrieve(, ?): ProviderTrace { request_json, response_json, id, 15 more } | null

GET/v1/steps/{step_id}/trace

StepsFeedback

Modify Feedback For Step

client.steps.feedback.create(, , ?): Step { id, agent_id, cache_write_tokens, 27 more }

PATCH/v1/steps/{step_id}/feedback

StepsMessages

List Messages For Step

client.steps.messages.list(, ?, ?): ArrayPage<MessageListResponse>

GET/v1/steps/{step_id}/messages

ModelsExpand Collapse

MessageListResponse = 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

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.

name?: string | null

otid?: string | null

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

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)

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.

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.

One of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

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.

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.

type?: "image"

The type of the message.

string

date: string

is_err?: boolean | null

message_type?: "user_message"

The type of the 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.

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"

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"

One of the following:

"redacted"

"omitted"

hidden_reasoning?: string | null

is_err?: boolean | null

message_type?: "hidden_reasoning_message"

The type of the 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 }

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.

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

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"

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.

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"

One of the following:

"success"

"error"

tool_call_id: string

tool_return: Array<TextContent { text, signature, type } | ImageContent { source, type } > | string

The tool return value - either a string or list of content parts (text/image)

One of the following:

Array<TextContent { text, signature, type } | ImageContent { source, type } >

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.

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.

One of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

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.

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.

type?: "image"

The type of the message.

string

stderr?: Array<string> | null

stdout?: Array<string> | null

type?: "tool"

The message type to be created.

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)

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.

string

date: string

is_err?: boolean | null

message_type?: "assistant_message"

The type of the 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

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.

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

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

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.

ToolReturn { status, tool_call_id, tool_return, 3 more }

status: "success" | "error"

One of the following:

"success"

"error"

tool_call_id: string

tool_return: Array<TextContent { text, signature, type } | ImageContent { source, type } > | string

The tool return value - either a string or list of content parts (text/image)

One of the following:

Array<TextContent { text, signature, type } | ImageContent { source, type } >

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.

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.

One of the following:

URLImage { url, type }

url: string

The URL of the image.

type?: "url"

The source type for the image.

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.

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.

type?: "image"

The type of the message.

string

stderr?: Array<string> | null

stdout?: Array<string> | null

type?: "tool"

The message type to be created.

Deprecatedapprove?: boolean | null

Whether the tool has been approved

is_err?: boolean | null

message_type?: "approval_response_message"

The type of the 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, 9 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

compaction_stats?: CompactionStats | null

Statistics about a memory compaction operation.

context_window: number

The model’s context window size

messages_count_after: number

Number of messages after compaction

messages_count_before: number

Number of messages before compaction

trigger: string

What triggered the compaction (e.g., ‘context_window_exceeded’, ‘post_step_context_check’)

context_tokens_after?: number | null

Token count after compaction (message tokens only, does not include tool definitions)

context_tokens_before?: number | null

Token count before compaction (from LLM usage stats, includes full context sent to LLM)

is_err?: boolean | null

message_type?: "summary_message"

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"

is_err?: boolean | null

message_type?: "event_message"

name?: string | null

otid?: string | null

run_id?: string | null

sender_id?: string | null

seq_id?: number | null

step_id?: string | null