--- title: "Send Message" method: POST path: "/v1/agents/{agent_id}/messages" tags: ["agents"] --- # Send Message `POST /v1/agents/{agent_id}/messages` Process a user message and return the agent's response. This endpoint accepts a message from a user and processes it through the agent. ## Path parameters - `agent_id` string, required ## Request body - LettaRequest - `messages` union[], required — The messages to be sent to the agent. - union - MessageCreate — Request to create a message - `type` 'message', nullable — The message type to be created. - `role` 'user' | 'system' | 'assistant', required — The role of the participant. - `content` union, required — The content of the message. - LettaMessageContentUnion[] - union - … - string - `name` string, nullable — The name of the participant. - `otid` string, nullable — The offline threading id associated with this message - `sender_id` string, nullable — The id of the sender of the message, can be an identity id or agent id - `batch_item_id` string, nullable — The id of the LLMBatchItem that this message is associated with - `group_id` string, nullable — The multi-agent group that the message was sent in - ApprovalCreate — Input to approve or deny a tool call request - `type` 'approval' — The message type to be created. - `approve` boolean, required — Whether the tool has been approved - `approval_request_id` string, required — The message ID of the approval request - `reason` string, nullable — An optional explanation for the provided approval status - `max_steps` integer — Maximum number of steps the agent should take to process the request. - `use_assistant_message` boolean — Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. - `assistant_message_tool_name` string — The name of the designated message tool. - `assistant_message_tool_kwarg` string — The name of the message argument in the designated message tool. - `include_return_message_types` MessageType[], nullable — Only return specified message types in the response. If `None` (default) returns all messages. - `enable_thinking` string — If set to True, enables reasoning before responses or tool calls from the agent. ## Response `200` Successful Response - LettaResponse — Response object from an agent interaction, consisting of the new messages generated by the agent and usage statistics. The type of the returned messages can be either `Message` or `LettaMessage`, depending on what was specified in the request. Attributes: messages (List[Union[Message, LettaMessage]]): The messages returned by the agent. usage (LettaUsageStatistics): The usage statistics - `messages` LettaMessageUnion[], required — The messages returned by the agent. - union - SystemMessage — A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id` string, required - `date` string, date-time, required - `name` string, nullable - `message_type` 'system_message' — The type of the message. - `otid` string, nullable - `sender_id` string, nullable - `step_id` string, nullable - `is_err` boolean, nullable - `seq_id` integer, nullable - `run_id` string, nullable - `content` string, required — The message content sent by the system - UserMessage — A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id` string, required - `date` string, date-time, required - `name` string, nullable - `message_type` 'user_message' — The type of the message. - `otid` string, nullable - `sender_id` string, nullable - `step_id` string, nullable - `is_err` boolean, nullable - `seq_id` integer, nullable - `run_id` string, nullable - `content` union, required — The message content sent by the user (can be a string or an array of multi-modal content parts) - LettaUserMessageContentUnion[] - union - … - string - ReasoningMessage — Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id` string, required - `date` string, date-time, required - `name` string, nullable - `message_type` 'reasoning_message' — The type of the message. - `otid` string, nullable - `sender_id` string, nullable - `step_id` string, nullable - `is_err` boolean, nullable - `seq_id` integer, nullable - `run_id` string, nullable - `source` 'reasoner_model' | 'non_reasoner_model' - `reasoning` string, required - `signature` string, nullable - HiddenReasoningMessage — Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id` string, required - `date` string, date-time, required - `name` string, nullable - `message_type` 'hidden_reasoning_message' — The type of the message. - `otid` string, nullable - `sender_id` string, nullable - `step_id` string, nullable - `is_err` boolean, nullable - `seq_id` integer, nullable - `run_id` string, nullable - `state` 'redacted' | 'omitted', required - `hidden_reasoning` string, nullable - ToolCallMessage — A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id` string, required - `date` string, date-time, required - `name` string, nullable - `message_type` 'tool_call_message' — The type of the message. - `otid` string, nullable - `sender_id` string, nullable - `step_id` string, nullable - `is_err` boolean, nullable - `seq_id` integer, nullable - `run_id` string, nullable - `tool_call` union, required - ToolCall - `name` string, required - `arguments` string, required - `tool_call_id` string, required - ToolCallDelta - `name` string, nullable - `arguments` string, nullable - `tool_call_id` string, nullable - `tool_calls` union - ToolCall[] - `name` string, required - `arguments` string, required - `tool_call_id` string, required - ToolCallDelta - `name` string, nullable - `arguments` string, nullable - `tool_call_id` string, nullable - ToolReturnMessage — A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id` string, required - `date` string, date-time, required - `name` string, nullable - `message_type` 'tool_return_message' — The type of the message. - `otid` string, nullable - `sender_id` string, nullable - `step_id` string, nullable - `is_err` boolean, nullable - `seq_id` integer, nullable - `run_id` string, nullable - `tool_return` string, required - `status` 'success' | 'error', required - `tool_call_id` string, required - `stdout` string[], nullable - `stderr` string[], nullable - `tool_returns` LettaSchemasLettaMessageToolReturn[], nullable - `tool_return` string, required - `status` 'success' | 'error', required - `tool_call_id` string, required - `stdout` string[], nullable - `stderr` string[], nullable - AssistantMessage — A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id` string, required - `date` string, date-time, required - `name` string, nullable - `message_type` 'assistant_message' — The type of the message. - `otid` string, nullable - `sender_id` string, nullable - `step_id` string, nullable - `is_err` boolean, nullable - `seq_id` integer, nullable - `run_id` string, nullable - `content` union, required — The message content sent by the agent (can be a string or an array of content parts) - LettaAssistantMessageContentUnion[] - `type` 'text' — The type of the message. - `text` string, required — The text content of the message. - `signature` string, nullable — Stores a unique identifier for any reasoning associated with this text content. - string - ApprovalRequestMessage — A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id` string, required - `date` string, date-time, required - `name` string, nullable - `message_type` 'approval_request_message' — The type of the message. - `otid` string, nullable - `sender_id` string, nullable - `step_id` string, nullable - `is_err` boolean, nullable - `seq_id` integer, nullable - `run_id` string, nullable - `tool_call` union, required — The tool call that has been requested by the llm to run - ToolCall - `name` string, required - `arguments` string, required - `tool_call_id` string, required - ToolCallDelta - `name` string, nullable - `arguments` string, nullable - `tool_call_id` string, nullable - ApprovalResponseMessage — A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id` string, required - `date` string, date-time, required - `name` string, nullable - `message_type` 'approval_response_message' — The type of the message. - `otid` string, nullable - `sender_id` string, nullable - `step_id` string, nullable - `is_err` boolean, nullable - `seq_id` integer, nullable - `run_id` string, nullable - `approve` boolean, required — Whether the tool has been approved - `approval_request_id` string, required — The message ID of the approval request - `reason` string, nullable — An optional explanation for the provided approval status - `stop_reason` LettaStopReason, required — The stop reason from Letta indicating why agent loop stopped execution. - `message_type` 'stop_reason' — The type of the message. - `stop_reason` 'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval', required - `usage` LettaUsageStatistics, required — Usage statistics for the agent interaction. Attributes: completion_tokens (int): The number of tokens generated by the agent. prompt_tokens (int): The number of tokens in the prompt. total_tokens (int): The total number of tokens processed by the agent. step_count (int): The number of steps taken by the agent. - `message_type` 'usage_statistics' - `completion_tokens` integer — The number of tokens generated by the agent. - `prompt_tokens` integer — The number of tokens in the prompt. - `total_tokens` integer — The total number of tokens processed by the agent. - `step_count` integer — The number of steps taken by the agent. - `steps_messages` array[], nullable — The messages generated per step - Message[] - `created_by_id` string, nullable — The id of the user that made this object. - `last_updated_by_id` string, nullable — The id of the user that made this object. - `created_at` string, date-time — The timestamp when the object was created. - `updated_at` string, date-time, nullable — The timestamp when the object was last updated. - `id` string — The human-friendly ID of the Message - `agent_id` string, nullable — The unique identifier of the agent. - `model` string, nullable — The model used to make the function call. - `role` 'assistant' | 'user' | 'tool' | 'function' | 'system' | 'approval', required - `content` union[], nullable — The content of the message. - union - TextContent - … - ImageContent - … - ToolCallContent - … - ToolReturnContent - … - ReasoningContent — Sent via the Anthropic Messages API - … - RedactedReasoningContent — Sent via the Anthropic Messages API - … - OmittedReasoningContent — A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - … - SummarizedReasoningContent — The style of reasoning content returned by the OpenAI Responses API - … - `name` string, nullable — For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called. - `tool_calls` ChatCompletionMessageFunctionToolCall[], nullable — The list of tool calls requested. Only applicable for role assistant. - `id` string, required - `function` Function, required - `arguments` string, required - `name` string, required - `type` 'function', required - `tool_call_id` string, nullable — The ID of the tool call. Only applicable for role tool. - `step_id` string, nullable — The id of the step that this message was created in. - `run_id` string, nullable — The id of the run that this message was created in. - `otid` string, nullable — The offline threading id associated with this message - `tool_returns` LettaSchemasMessageToolReturn[], nullable — Tool execution return information for prior tool calls - `tool_call_id` unknown - `status` 'success' | 'error', required — The status of the tool call - `stdout` string[], nullable — Captured stdout (e.g. prints, logs) from the tool invocation - `stderr` string[], nullable — Captured stderr from the tool invocation - `func_response` string, nullable — The function response string - `group_id` string, nullable — The multi-agent group that the message was sent in - `sender_id` string, nullable — The id of the sender of the message, can be an identity id or agent id - `batch_item_id` string, nullable — The id of the LLMBatchItem that this message is associated with - `is_err` boolean, nullable — Whether this message is part of an error step. Used only for debugging purposes. - `approval_request_id` string, nullable — The id of the approval request if this message is associated with a tool call request. - `approve` boolean, nullable — Whether tool call is approved. - `denial_reason` string, nullable — The reason the tool call request was denied. - `run_ids` string[], nullable — The background task run IDs associated with the agent interaction ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.net/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yu-code666/letta-api/versions/6cec99480c13/schema)