agentsMessages

Send Message

Process a user message and return the agent's response. This endpoint accepts a message from a user and processes it through the agent. The response format is controlled by the `streaming` field in the request body: - If `streaming=false` (default): Returns a complete LettaResponse with all messages - If `streaming=true`: Returns a Server-Sent Events (SSE) stream Additional streaming options (only used when streaming=true): - `stream_tokens`: Stream individual tokens instead of complete steps - `include_pings`: Include keepalive pings to prevent connection timeouts - `background`: Process the request in the background

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
messageslist of objects
The messages returned by the agent.
stop_reasonobject
The stop reason from Letta indicating why agent loop stopped execution.
usageobject
The usage statistics of the agent.

Errors