agentsMessages

Send Message Async

Asynchronously process a user message and return a run object. The actual processing happens in the background, and the status can be checked using the run ID. This is "asynchronous" in the sense that it's a background run and explicitly must be fetched by the run ID.

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.

callback_urlstring or nullOptional
Optional callback URL to POST to when the job completes
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
agent_idstring
The unique identifier of the agent associated with the run.
idstring or nullformat: "^(job|run)-[a-fA-F0-9]{8}"

The human-friendly ID of the Run

statusenum or null
The current status of the run.
Allowed values:
created_atstring or nullformat: "date-time"
The timestamp when the run was created.
completed_atstring or nullformat: "date-time"
The timestamp when the run was completed.
base_template_idstring or null
The base template ID that the run belongs to.
backgroundboolean or null
Whether the run was created in background mode.
metadatamap from strings to any or null
Additional metadata for the run.
request_configobject or null
The request configuration for the run.
stop_reasonenum or null
The reason why the run was stopped.
callback_urlstring or null
If set, POST to this URL when the run completes.
callback_sent_atstring or nullformat: "date-time"
Timestamp when the callback was last attempted.
callback_status_codeinteger or null
HTTP status code returned by the callback endpoint.
callback_errorstring or null
Optional error message from attempting to POST the callback endpoint.
ttft_nsinteger or null
Time to first token for a run in nanoseconds
total_duration_nsinteger or null
Total run duration in nanoseconds

Errors