Skip to content 
Create 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.
Note: Sending multiple concurrent requests to the same agent can lead to undefined behavior. Each agent processes messages sequentially, and concurrent requests may interleave in unexpected ways. Wait for each request to complete before sending the next one. Use separate agents or conversations for parallel processing.
Path ParametersExpand Collapse
Body ParametersJSONExpand Collapse
Deprecatedassistant_message_tool_kwarg: optional string
The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
Deprecatedassistant_message_tool_name: optional string
The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
client_skills: optional array of object { description, location, name }
Client-side skills available in the environment. These are rendered in the system prompt’s available skills section alongside agent-scoped skills from MemFS.
client_tools: optional array of object { name, description, parameters }
Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn.
Deprecatedenable_thinking: optional string
If set to True, enables reasoning before responses or tool calls from the agent.
include_compaction_messages: optional boolean
If True, compaction events emit structured SummaryMessage and EventMessage types. If False (default), compaction messages are not included in the response.
input: optional string or array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more
Syntactic sugar for a single user message. Equivalent to messages=[{‘role’: ‘user’, ‘content’: input}].
array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
ToolCallContent object { id, input, name, 2 more }
ReasoningContent object { is_native, reasoning, signature, type }
messages: optional array of MessageCreate { content, role, batch_item_id, 5 more } or ApprovalCreate { approval_request_id, approvals, approve, 4 more } or object { tool_returns, group_id, otid, type }
The messages to be sent to the agent.
MessageCreate object { content, role, batch_item_id, 5 more }
Request to create a message
The content of the message.
array of LettaMessageContentUnion
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
ToolCallContent object { id, input, name, 2 more }
ReasoningContent object { is_native, reasoning, signature, type }
ApprovalCreate object { approval_request_id, approvals, approve, 4 more }
Input to approve or deny a tool call request
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ToolReturn object { status, tool_call_id, tool_return, 3 more }
tool_return: array of TextContent { text, signature, type } or ImageContent { source, type } or string
The tool return value - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
ToolReturnCreate object { tool_returns, group_id, otid, type }
Submit tool return(s) from client-side tool execution.
This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case.
List of tool returns from client-side execution
tool_return: array of TextContent { text, signature, type } or ImageContent { source, type } or string
The tool return value - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
override_model: optional string
Model handle to use for this request instead of the agent’s default model. This allows sending a message to a different model without changing the agent’s configuration.
override_system: optional string
Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request.
return_logprobs: optional boolean
If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang).
return_token_ids: optional boolean
If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns ‘turns’ field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking.
ReturnsExpand Collapse
Run object { id, agent_id, background, 14 more }
Representation of a run - a conversation or processing session for an agent. Runs track when agents process messages and maintain the relationship between agents, steps, and messages.
callback_error: optional string
Optional error message from attempting to POST the callback endpoint.
request_config: optional object { assistant_message_tool_kwarg, assistant_message_tool_name, include_return_message_types, use_assistant_message }
Create Message Async
curl https://api.letta.com/v1/agents/$AGENT_ID/messages/async \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $LETTA_API_KEY" \
-d '{}'{
"id": "run-123e4567-e89b-12d3-a456-426614174000",
"agent_id": "agent_id",
"background": true,
"base_template_id": "base_template_id",
"callback_error": "callback_error",
"callback_sent_at": "2019-12-27T18:11:19.117Z",
"callback_status_code": 0,
"callback_url": "callback_url",
"completed_at": "2019-12-27T18:11:19.117Z",
"conversation_id": "conversation_id",
"created_at": "2019-12-27T18:11:19.117Z",
"metadata": {
"foo": "bar"
},
"request_config": {
"assistant_message_tool_kwarg": "assistant_message_tool_kwarg",
"assistant_message_tool_name": "assistant_message_tool_name",
"include_return_message_types": [
"system_message"
],
"use_assistant_message": true
},
"status": "created",
"stop_reason": "end_turn",
"total_duration_ns": 0,
"ttft_ns": 0
}Returns Examples
{
"id": "run-123e4567-e89b-12d3-a456-426614174000",
"agent_id": "agent_id",
"background": true,
"base_template_id": "base_template_id",
"callback_error": "callback_error",
"callback_sent_at": "2019-12-27T18:11:19.117Z",
"callback_status_code": 0,
"callback_url": "callback_url",
"completed_at": "2019-12-27T18:11:19.117Z",
"conversation_id": "conversation_id",
"created_at": "2019-12-27T18:11:19.117Z",
"metadata": {
"foo": "bar"
},
"request_config": {
"assistant_message_tool_kwarg": "assistant_message_tool_kwarg",
"assistant_message_tool_name": "assistant_message_tool_name",
"include_return_message_types": [
"system_message"
],
"use_assistant_message": true
},
"status": "created",
"stop_reason": "end_turn",
"total_duration_ns": 0,
"ttft_ns": 0
}