Skip to content
Letta Letta Letta Docs
Sign up
API Reference

Steps

List Steps
steps.list(StepListParams**kwargs) -> SyncArrayPage[Step]
GET/v1/steps/
Retrieve Step
steps.retrieve(strstep_id) -> Step
GET/v1/steps/{step_id}
ModelsExpand Collapse
class ProviderTrace: …

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: Dict[str, object]

JSON content of the provider request

response_json: Dict[str, object]

JSON content of the provider response

id: Optional[str]

The human-friendly ID of the Provider_trace

agent_id: Optional[str]

ID of the agent that generated this trace

agent_tags: Optional[List[str]]

Tags associated with the agent for filtering

billing_context: Optional[BillingContext]

Billing context for LLM request cost tracking.

cost_source: Optional[str]

Cost source: ‘quota’ or ‘credits’

customer_id: Optional[str]

Customer ID for billing records

plan_type: Optional[str]

Subscription tier

call_type: Optional[str]

Type of call (agent_step, summarization, etc.)

compaction_settings: Optional[Dict[str, object]]

Compaction/summarization settings (summarization calls only)

created_at: Optional[datetime]

The timestamp when the object was created.

formatdate-time
created_by_id: Optional[str]

The id of the user that made this object.

last_updated_by_id: Optional[str]

The id of the user that made this object.

latency_ms: Optional[int]

LLM request latency in milliseconds

llm_config: Optional[Dict[str, object]]

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

org_id: Optional[str]

ID of the organization

run_id: Optional[str]

ID of the run this trace is associated with

source: Optional[str]

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

step_id: Optional[str]

ID of the step that this trace is associated with

updated_at: Optional[datetime]

The timestamp when the object was last updated.

formatdate-time
class Step: …
id: str

The id of the step. Assigned by the database.

agent_id: Optional[str]

The ID of the agent that performed the step.

cache_write_tokens: Optional[int]

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

cached_input_tokens: Optional[int]

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

completion_tokens: Optional[int]

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

completion_tokens_details: Optional[Dict[str, object]]

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

context_window_limit: Optional[int]

The context window limit configured for this step.

error_data: Optional[Dict[str, object]]

Error details including message, traceback, and additional context

error_type: Optional[str]

The type/class of the error that occurred

feedback: Optional[Literal["positive", "negative"]]

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

One of the following:
"positive"
"negative"
Deprecatedmessages: Optional[List[InternalMessage]]

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

id: str

The human-friendly ID of the Message

The role of the participant.

One of the following:
"assistant"
"user"
"tool"
"function"
"system"
"approval"
"summary"
agent_id: Optional[str]

The unique identifier of the agent.

approval_request_id: Optional[str]

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

approvals: Optional[List[Approval]]

The list of approvals for this message.

One of the following:
class ApprovalReturn: …
approve: bool

Whether the tool has been approved

tool_call_id: str

The ID of the tool call that corresponds to this approval

reason: Optional[str]

An optional explanation for the provided approval status

type: Optional[Literal["approval"]]

The message type to be created.

class ApprovalLettaSchemasMessageToolReturnOutput: …
status: Literal["success", "error"]

The status of the tool call

One of the following:
"success"
"error"
func_response: Optional[Union[str, List[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1], null]]

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

One of the following:
str
List[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1]
One of the following:
class TextContent: …
text: str

The text content of the message.

signature: Optional[str]

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

type: Optional[Literal["text"]]

The type of the message.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

class SourceBase64Image: …
data: str

The base64 encoded image data.

media_type: str

The media type for the image.

detail: Optional[str]

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

type: Optional[Literal["base64"]]

The source type for the image.

class SourceLettaImage: …
file_id: str

The unique identifier of the image file persisted in storage.

data: Optional[str]

The base64 encoded image data.

detail: Optional[str]

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

media_type: Optional[str]

The media type for the image.

type: Optional[Literal["letta"]]

The source type for the image.

type: Optional[Literal["image"]]

The type of the message.

stderr: Optional[List[str]]

Captured stderr from the tool invocation

stdout: Optional[List[str]]

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

tool_call_id: Optional[object]

The ID for the tool call

approve: Optional[bool]

Whether tool call is approved.

batch_item_id: Optional[str]

The id of the LLMBatchItem that this message is associated with

content: Optional[List[Content]]

The content of the message.

One of the following:
class TextContent: …
text: str

The text content of the message.

signature: Optional[str]

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

type: Optional[Literal["text"]]

The type of the message.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

class SourceBase64Image: …
data: str

The base64 encoded image data.

media_type: str

The media type for the image.

detail: Optional[str]

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

type: Optional[Literal["base64"]]

The source type for the image.

class SourceLettaImage: …
file_id: str

The unique identifier of the image file persisted in storage.

data: Optional[str]

The base64 encoded image data.

detail: Optional[str]

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

media_type: Optional[str]

The media type for the image.

type: Optional[Literal["letta"]]

The source type for the image.

type: Optional[Literal["image"]]

The type of the message.

class ToolCallContent: …
id: str

A unique identifier for this specific tool call instance.

input: Dict[str, object]

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

name: str

The name of the tool being called.

signature: Optional[str]

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

type: Optional[Literal["tool_call"]]

Indicates this content represents a tool call event.

class ToolReturnContent: …
content: str

The content returned by the tool execution.

is_error: bool

Indicates whether the tool execution resulted in an error.

tool_call_id: str

References the ID of the ToolCallContent that initiated this tool call.

type: Optional[Literal["tool_return"]]

Indicates this content represents a tool return event.

class ReasoningContent: …

Sent via the Anthropic Messages API

is_native: bool

Whether the reasoning content was generated by a reasoner model that processed this step.

reasoning: str

The intermediate reasoning or thought process content.

signature: Optional[str]

A unique identifier for this reasoning step.

type: Optional[Literal["reasoning"]]

Indicates this is a reasoning/intermediate step.

class RedactedReasoningContent: …

Sent via the Anthropic Messages API

data: str

The redacted or filtered intermediate reasoning content.

type: Optional[Literal["redacted_reasoning"]]

Indicates this is a redacted thinking step.

class OmittedReasoningContent: …

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[str]

A unique identifier for this reasoning step.

type: Optional[Literal["omitted_reasoning"]]

Indicates this is an omitted reasoning step.

class ContentSummarizedReasoningContent: …

The style of reasoning content returned by the OpenAI Responses API

id: str

The unique identifier for this reasoning step.

summary: List[ContentSummarizedReasoningContentSummary]

Summaries of the reasoning content.

index: int

The index of the summary part.

text: str

The text of the summary part.

encrypted_content: Optional[str]

The encrypted reasoning content.

type: Optional[Literal["summarized_reasoning"]]

Indicates this is a summarized reasoning step.

conversation_id: Optional[str]

The conversation this message belongs to

created_at: Optional[datetime]

The timestamp when the object was created.

formatdate-time
created_by_id: Optional[str]

The id of the user that made this object.

denial_reason: Optional[str]

The reason the tool call request was denied.

group_id: Optional[str]

The multi-agent group that the message was sent in

is_err: Optional[bool]

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

last_updated_by_id: Optional[str]

The id of the user that made this object.

model: Optional[str]

The model used to make the function call.

name: Optional[str]

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

otid: Optional[str]

The offline threading id associated with this message

run_id: Optional[str]

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

sender_id: Optional[str]

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

step_id: Optional[str]

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

tool_call_id: Optional[str]

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

tool_calls: Optional[List[ToolCall]]

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

id: str
function: ToolCallFunction

The function that the model called.

arguments: str
name: str
type: Literal["function"]
tool_returns: Optional[List[ToolReturn]]

Tool execution return information for prior tool calls

status: Literal["success", "error"]

The status of the tool call

One of the following:
"success"
"error"
func_response: Optional[Union[str, List[ToolReturnFuncResponseUnionMember1], null]]

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

One of the following:
str
List[ToolReturnFuncResponseUnionMember1]
One of the following:
class TextContent: …
text: str

The text content of the message.

signature: Optional[str]

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

type: Optional[Literal["text"]]

The type of the message.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

class SourceBase64Image: …
data: str

The base64 encoded image data.

media_type: str

The media type for the image.

detail: Optional[str]

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

type: Optional[Literal["base64"]]

The source type for the image.

class SourceLettaImage: …
file_id: str

The unique identifier of the image file persisted in storage.

data: Optional[str]

The base64 encoded image data.

detail: Optional[str]

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

media_type: Optional[str]

The media type for the image.

type: Optional[Literal["letta"]]

The source type for the image.

type: Optional[Literal["image"]]

The type of the message.

stderr: Optional[List[str]]

Captured stderr from the tool invocation

stdout: Optional[List[str]]

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

tool_call_id: Optional[object]

The ID for the tool call

updated_at: Optional[datetime]

The timestamp when the object was last updated.

formatdate-time
model: Optional[str]

The name of the model used for this step.

model_endpoint: Optional[str]

The model endpoint url used for this step.

model_handle: Optional[str]

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

origin: Optional[str]

The surface that this agent step was initiated from.

project_id: Optional[str]

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

prompt_tokens: Optional[int]

The number of tokens in the prompt during this step.

prompt_tokens_details: Optional[Dict[str, object]]

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

provider_category: Optional[str]

The category of the provider used for this step.

provider_id: Optional[str]

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

provider_name: Optional[str]

The name of the provider used for this step.

reasoning_tokens: Optional[int]

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

request_id: Optional[str]

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

run_id: Optional[str]

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

status: Optional[Literal["pending", "success", "failed", "cancelled"]]

Status of a step execution

One of the following:
"pending"
"success"
"failed"
"cancelled"
stop_reason: Optional[StopReasonType]

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: Optional[List[str]]

Metadata tags.

tid: Optional[str]

The unique identifier of the transaction that processed this step.

total_tokens: Optional[int]

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

trace_id: Optional[str]

The trace id of the agent step.

StepsMetrics

Retrieve Metrics For Step
steps.metrics.retrieve(strstep_id) -> MetricRetrieveResponse
GET/v1/steps/{step_id}/metrics
ModelsExpand Collapse
class MetricRetrieveResponse: …
id: str

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

agent_id: Optional[str]

The unique identifier of the agent.

base_template_id: Optional[str]

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

llm_request_ns: Optional[int]

Time spent on LLM requests in nanoseconds.

llm_request_start_ns: Optional[int]

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

project_id: Optional[str]

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

provider_id: Optional[str]

The unique identifier of the provider.

run_id: Optional[str]

The unique identifier of the run.

step_ns: Optional[int]

Total time for the step in nanoseconds.

step_start_ns: Optional[int]

The timestamp of the start of the step in nanoseconds.

template_id: Optional[str]

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

tool_execution_ns: Optional[int]

Time spent on tool execution in nanoseconds.

StepsTrace

Retrieve Trace For Step
steps.trace.retrieve(strstep_id) -> ProviderTrace
GET/v1/steps/{step_id}/trace

StepsFeedback

Modify Feedback For Step
steps.feedback.create(strstep_id, FeedbackCreateParams**kwargs) -> Step
PATCH/v1/steps/{step_id}/feedback

StepsMessages

List Messages For Step
steps.messages.list(strstep_id, MessageListParams**kwargs) -> SyncArrayPage[MessageListResponse]
GET/v1/steps/{step_id}/messages
ModelsExpand Collapse

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:
class SystemMessage: …

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

id: str
content: str

The message content sent by the system

date: datetime
is_err: Optional[bool]
message_type: Optional[Literal["system_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class UserMessage: …

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: str
content: Union[List[LettaUserMessageContentUnion], str]

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

One of the following:
List[LettaUserMessageContentUnion]
One of the following:
class TextContent: …
text: str

The text content of the message.

signature: Optional[str]

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

type: Optional[Literal["text"]]

The type of the message.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

class SourceBase64Image: …
data: str

The base64 encoded image data.

media_type: str

The media type for the image.

detail: Optional[str]

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

type: Optional[Literal["base64"]]

The source type for the image.

class SourceLettaImage: …
file_id: str

The unique identifier of the image file persisted in storage.

data: Optional[str]

The base64 encoded image data.

detail: Optional[str]

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

media_type: Optional[str]

The media type for the image.

type: Optional[Literal["letta"]]

The source type for the image.

type: Optional[Literal["image"]]

The type of the message.

str
date: datetime
is_err: Optional[bool]
message_type: Optional[Literal["user_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class ReasoningMessage: …

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: str
date: datetime
reasoning: str
is_err: Optional[bool]
message_type: Optional[Literal["reasoning_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
signature: Optional[str]
source: Optional[Literal["reasoner_model", "non_reasoner_model"]]
One of the following:
"reasoner_model"
"non_reasoner_model"
step_id: Optional[str]
class HiddenReasoningMessage: …

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: str
date: datetime
state: Literal["redacted", "omitted"]
One of the following:
"redacted"
"omitted"
hidden_reasoning: Optional[str]
is_err: Optional[bool]
message_type: Optional[Literal["hidden_reasoning_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class ToolCallMessage: …

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: str
date: datetime
Deprecatedtool_call: ToolCall
One of the following:
class ToolCall: …
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
is_err: Optional[bool]
message_type: Optional[Literal["tool_call_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
tool_calls: Optional[ToolCalls]
One of the following:
List[ToolCall]
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
class ToolReturnMessage: …

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: str
date: datetime
Deprecatedstatus: Literal["success", "error"]
One of the following:
"success"
"error"
Deprecatedtool_call_id: str
Deprecatedtool_return: str
is_err: Optional[bool]
message_type: Optional[Literal["tool_return_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
Deprecatedstderr: Optional[List[str]]
Deprecatedstdout: Optional[List[str]]
step_id: Optional[str]
tool_returns: Optional[List[ToolReturn]]
status: Literal["success", "error"]
One of the following:
"success"
"error"
tool_call_id: str
tool_return: Union[List[ToolReturnUnionMember0], str]

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

One of the following:
List[ToolReturnUnionMember0]
One of the following:
class TextContent: …
text: str

The text content of the message.

signature: Optional[str]

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

type: Optional[Literal["text"]]

The type of the message.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

class SourceBase64Image: …
data: str

The base64 encoded image data.

media_type: str

The media type for the image.

detail: Optional[str]

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

type: Optional[Literal["base64"]]

The source type for the image.

class SourceLettaImage: …
file_id: str

The unique identifier of the image file persisted in storage.

data: Optional[str]

The base64 encoded image data.

detail: Optional[str]

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

media_type: Optional[str]

The media type for the image.

type: Optional[Literal["letta"]]

The source type for the image.

type: Optional[Literal["image"]]

The type of the message.

str
stderr: Optional[List[str]]
stdout: Optional[List[str]]
type: Optional[Literal["tool"]]

The message type to be created.

class AssistantMessage: …

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: str
content: Union[List[LettaAssistantMessageContentUnion], str]

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

One of the following:
List[LettaAssistantMessageContentUnion]
text: str

The text content of the message.

signature: Optional[str]

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

type: Optional[Literal["text"]]

The type of the message.

str
date: datetime
is_err: Optional[bool]
message_type: Optional[Literal["assistant_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class ApprovalRequestMessage: …

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: str
date: datetime
Deprecatedtool_call: ToolCall

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

One of the following:
class ToolCall: …
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
is_err: Optional[bool]
message_type: Optional[Literal["approval_request_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
tool_calls: Optional[ToolCalls]

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

One of the following:
List[ToolCall]
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
class ApprovalResponseMessage: …

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: str
date: datetime
Deprecatedapproval_request_id: Optional[str]

The message ID of the approval request

approvals: Optional[List[Approval]]

The list of approval responses

One of the following:
class ApprovalReturn: …
approve: bool

Whether the tool has been approved

tool_call_id: str

The ID of the tool call that corresponds to this approval

reason: Optional[str]

An optional explanation for the provided approval status

type: Optional[Literal["approval"]]

The message type to be created.

class ToolReturn: …
status: Literal["success", "error"]
One of the following:
"success"
"error"
tool_call_id: str
tool_return: Union[List[ToolReturnUnionMember0], str]

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

One of the following:
List[ToolReturnUnionMember0]
One of the following:
class TextContent: …
text: str

The text content of the message.

signature: Optional[str]

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

type: Optional[Literal["text"]]

The type of the message.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

class SourceBase64Image: …
data: str

The base64 encoded image data.

media_type: str

The media type for the image.

detail: Optional[str]

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

type: Optional[Literal["base64"]]

The source type for the image.

class SourceLettaImage: …
file_id: str

The unique identifier of the image file persisted in storage.

data: Optional[str]

The base64 encoded image data.

detail: Optional[str]

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

media_type: Optional[str]

The media type for the image.

type: Optional[Literal["letta"]]

The source type for the image.

type: Optional[Literal["image"]]

The type of the message.

str
stderr: Optional[List[str]]
stdout: Optional[List[str]]
type: Optional[Literal["tool"]]

The message type to be created.

Deprecatedapprove: Optional[bool]

Whether the tool has been approved

is_err: Optional[bool]
message_type: Optional[Literal["approval_response_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

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.

Deprecatedreason: Optional[str]

An optional explanation for the provided approval status

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class SummaryMessage: …

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

id: str
date: datetime
summary: str
compaction_stats: Optional[CompactionStats]

Statistics about a memory compaction operation.

context_window: int

The model’s context window size

messages_count_after: int

Number of messages after compaction

messages_count_before: int

Number of messages before compaction

trigger: str

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

context_tokens_after: Optional[int]

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

context_tokens_before: Optional[int]

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

is_err: Optional[bool]
message_type: Optional[Literal["summary_message"]]
name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class EventMessage: …

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: str
date: datetime
event_data: Dict[str, object]
event_type: Literal["compaction"]
is_err: Optional[bool]
message_type: Optional[Literal["event_message"]]
name: Optional[str]
otid: Optional[str]

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: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]