pub struct SendMessagesRequest {
pub agent_mode: Option<SendAgentMode>,
pub messages: Vec<SendMessageItem>,
pub mode: Option<SendMode>,
pub prepend: Option<bool>,
pub request_headers: Option<HashMap<String, String>>,
pub response_format: Option<SendMessagesRequestResponseFormat>,
pub traceparent: Option<String>,
pub tracestate: Option<String>,
pub wait: Option<bool>,
}Expand description
Parameters for sending zero or more user messages to the session in a single turn. Remote-backed (Mission Control) sessions do not support this method and will return an error.
Experimental. This type is part of an experimental wire-protocol surface and may change or be removed in future SDK or CLI releases.
Fields§
§agent_mode: Option<SendAgentMode>The UI mode the agent was in when these messages were sent. Defaults to the session’s current mode.
messages: Vec<SendMessageItem>The user messages to append to the conversation, in order, before running one agent loop. When the batch starts a run, its final message is the primary initiating message; earlier messages provide context, not separate runs or replies. May be empty, in which case a single turn runs over the existing history with no new user message or originatingMessageId.
mode: Option<SendMode>How to deliver the messages. enqueue (default) appends to the message queue. immediate interjects during an in-progress turn.
prepend: Option<bool>If true, adds the messages to the front of the queue instead of the end
request_headers: Option<HashMap<String, String>>Custom HTTP headers to include in outbound model requests for this turn. Merged with session-level provider headers; per-turn headers augment and overwrite session-level headers with the same key.
response_format: Option<SendMessagesRequestResponseFormat>Provider-native output format for the whole turn, including an empty message batch and all tool-call iterations. Not inherited by later turns or subagents. Ordinary steering inherits the active format; specifying responseFormat with mode: immediate is an error, even while idle. Returned assistant content remains text; the runtime does not parse or validate it. Unsupported models or schemas produce provider errors.
traceparent: Option<String>W3C Trace Context traceparent header for distributed tracing of this agent turn
tracestate: Option<String>W3C Trace Context tracestate header for distributed tracing
wait: Option<bool>If true, await completion of the agentic loop for this turn before returning. Defaults to false (fire-and-forget). When true, the result still contains the same messageIds; the caller can rely on the agent having processed the messages before the call resolves. Transport-dependent tail semantics: on a LOCAL (in-process) session the wait additionally blocks until the completed turn’s event tail has been dispatched to this session’s in-process subscribers, so a subsequent read of subscriber state already reflects the turn; on a REMOTE session the wait resolves once the loop completes and mirrored delivery follows over the wire. Callers that need the stronger local guarantee on remote sessions should await the event stream explicitly.