agents

Send Message Async

Changed on

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.

post/v1/agents/{agent_id}/messages/async

Request

  • Base URL
    https://app.letta.com
  • URL
    https://app.letta.com/v1/agents/{agent_id}/messages/async
  • Auth
    HTTP bearer

Path parameters

agent_idstring required

Request body

max_stepsinteger

Maximum number of steps the agent should take to process the request.

use_assistant_messageboolean

Whether the server should parse specific tool call arguments (default send_message) as AssistantMessage objects.

assistant_message_tool_namestring

The name of the designated message tool.

assistant_message_tool_kwargstring

The name of the message argument in the designated message tool.

include_return_message_typesMessageType[] nullable

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

enable_thinkingstring

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

callback_urlstring nullable

Optional callback URL to POST to when the job completes

Response

Successful Response

idstring

The human-friendly ID of the Run

status'created' | 'running' | 'completed' | 'failed' | 'cancelled'

Status of the run.

created_atstring date-time

The timestamp when the run was created.

completed_atstring date-time nullable

The timestamp when the run was completed.

agent_idstring required

The unique identifier of the agent associated with the run.

backgroundboolean nullable

Whether the run was created in background mode.

metadataobject nullable

Additional metadata for the run.

stop_reason'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval'
callback_urlstring nullable

If set, POST to this URL when the run completes.

callback_sent_atstring date-time nullable

Timestamp when the callback was last attempted.

callback_status_codeinteger nullable

HTTP status code returned by the callback endpoint.

callback_errorstring nullable

Optional error message from attempting to POST the callback endpoint.

ttft_nsinteger nullable

Time to first token for a run in nanoseconds

total_duration_nsinteger nullable

Total run duration in nanoseconds

Example response

{
  "id": "run-123e4567-e89b-12d3-a456-426614174000"
}

Changes

  • f0554a0bf8b2Revision changes
    • info

      added the new optional request property ///////

    • info

      added the new optional request property ///////

    • info

      added the new optional request property ///////

  • ac8e1eb68404Revision changes
    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      the response property became required for the status

    • info

      removed the expired enum value from the response property for the response status

    • info

      removed the pending enum value from the response property for the response status

    • info

      response property agent_id list-of-types was narrowed by removing types null from media type application/json of response 200