Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.litellm-agent-platform.ai/llms.txt

Use this file to discover all available pages before exploring further.

Sends a user message to an agent session. The request is synchronous — it waits for the agent to finish processing and returns the reply in the response body. The message is appended to the session’s conversation history. The session must be in ready status. If the session is still creating, wait for GET /sessions/{id} to return status: "ready" before calling this endpoint.
This endpoint applies only to API harnesses (opencode, claude-agent-sdk). TUI harnesses (claude-code, codex) expose a PTY via WebSocket (tty_url) and do not use this endpoint.

​
Request

POST /api/v1/managed_agents/sessions/{session_id}/message
Headers
HeaderValue
AuthorizationBearer <MASTER_KEY>
Content-Typeapplication/json

​
Path parameters

​
session_id
string
required
The unique ID of the session to send a message to.

​
Body parameters

Provide either text or parts — not both.
​
text
string
Plain-text message to send. The platform wraps this into a { type: "text", text: "..." } part before forwarding to the harness.
​
parts
array
Structured message parts in the harness wire format. Each part is an object with at minimum a type field. Use this when you need to send multimodal content or tool results directly.

​
Response

Returns the agent’s reply as a JSON object:
​
parts
array
Array of message parts from the agent. Each part has at minimum:

​
Error responses

StatusMeaning
404Session not found or not in ready state
502Harness request failed (sandbox unreachable or returned 5xx)
A 502 with a hard connect failure also marks the session dead immediately, so you can see the failure without waiting for the reconciler.

​
Example

curl -X POST "https://<your-platform-host>/api/v1/managed_agents/sessions/ses_01kabc/message" \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Summarize the largest file changed in the latest PR."}'

{
  "parts": [
    {
      "type": "text",
      "text": "The largest file changed in the latest PR is `src/server/k8s.ts` (+342 lines). It adds the Sandbox CR reconciler and warm-pool top-up logic..."
    }
  ]
}