Send Message Streaming

Process a user message and return the agent’s response. This endpoint accepts a message from a user and processes it through the agent. It will stream the steps of the response always, and stream the tokens if ‘stream_tokens’ is set to True.

Authentication

AuthorizationBearer

Header authentication of the form Bearer <token>

Path Parameters

agent_idstringRequiredformat: "^agent-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"=42 characters

The ID of the agent in the format ‘agent-<uuid4>’

Request

This endpoint expects an object.
messageslist of objects or nullOptional
The messages to be sent to the agent.
inputstring or list of objects or nullOptional

Syntactic sugar for a single user message. Equivalent to messages=[{‘role’: ‘user’, ‘content’: input}].

max_stepsintegerOptionalDefaults to 50
Maximum number of steps the agent should take to process the request.
include_return_message_typeslist of enums or nullOptional

Only return specified message types in the response. If None (default) returns all messages.

streamingbooleanOptionalDefaults to false

If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response.

stream_tokensbooleanOptionalDefaults to false

Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true).

include_pingsbooleanOptionalDefaults to true

Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true).

backgroundbooleanOptionalDefaults to false

Whether to process the request in the background (only used when streaming=true).

use_assistant_messagebooleanOptionalDefaults to trueDeprecated

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.

assistant_message_tool_namestringOptionalDefaults to send_messageDeprecated

The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.

assistant_message_tool_kwargstringOptionalDefaults to messageDeprecated

The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.

enable_thinkingstringOptionalDeprecated
If set to True, enables reasoning before responses or tool calls from the agent.

Response

Successful response
SystemMessageobject
OR
UserMessageobject
OR
ReasoningMessageobject
OR
HiddenReasoningMessageobject
OR
ToolCallMessageobject
OR
ToolReturnMessageobject
OR
AssistantMessageobject
OR
ApprovalRequestMessageobject
OR
ApprovalResponseMessageobject
OR
LettaPingobject
OR
LettaStopReasonobject
OR
LettaUsageStatisticsobject

Errors