Invokes a workspace agent and streams its response as Server-Sent Events. To continue a session, send the X-Session-ID value returned by the previous response. If you omit the header, the gateway starts a new session and returns its ID in the response header. The body session_id field does not continue a session. The body can include extra top-level fields. The gateway forwards every field except these reserved fields: message, session_id, user_id, and resume_map. resume_map continues a suspended turn. For a session with no history, resume_map becomes the initial agent input. Requires a valid Bearer token.
Headers
-
Session ID returned by a previous response. Send it to continue that session. Valid IDs match [A-Za-z0-9_-]{1,128}$. If omitted, the gateway starts a new session. Body session_id does not continue a session
-
Classify a newly created session as a testing session; existing classification is unchanged
Body
Required
Invoke request
-
Optional when other agent fields are provided: chat input for chat agents. Reserved field name.
-
ResumeMap contains per-interrupt answers resolved by OE. OE forwards it to the agent as ordinary input only when it starts a session's first execution, where no local suspended turn exists to answer.
Additional properties are allowed.
-
Optional compatibility field. The gateway ignores it for session continuity. To continue a session, send X-Session-ID instead. Reserved field name.
-
Optional identity used for personalization and Memory isolation. Human and API key calls use this value, or default to the authenticated user. Service account calls always use the service account identity. Service accounts cannot yet act as another user. Reserved field name.
Responses
-
Unsupported or malformed API version, an operation unavailable in the selected published contract, or an unacceptable representation (including unsupported media-type parameters or excluded SSE). Existing authentication, authorization, and rate-limit failures take precedence.
-
SSE stream. A pre-header failure (before the first frame) renders as one of the JSON error bodies below; a mid-stream failure instead renders as a terminal SSE chunk carrying the same code/error, plus source/component/sandbox/boot_id in a metadata object for a startup-failure envelope
-
Bad Request
-
Unauthorized
-
Conflict
-
PROJECT_SECRET_INVALID: the workspace cannot start because a project secret is invalid or unreachable (fix the secret and redeploy); mid-stream it appears as a terminal SSE chunk carrying code=PROJECT_SECRET_INVALID
-
Too Many Requests
-
ErrorResponse, or StartupFailureResponse for an AGENT_STARTUP_FAILED/STARTUP_FAILED startup failure
-
StartupFailureResponse for a POOL_EXHAUSTED/EXECUTOR_BOOT_FAILED/PLATFORM_DEPENDENCY_FAILED/POOL_UNREACHABLE startup failure; ErrorResponse otherwise. POOL_EXHAUSTED carries a Retry-After header
-
Gateway Timeout
curl \
--request POST 'https://agentengine.mongodb.com/api/v1/projects/{id}/workspaces/{workspace_id}/invokeStream' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "X-Session-ID: string" \
--header "X-Agent-Engine-Test-Session: true" \
--data '{
"message": "string",
"resume_map": {},
"session_id": "string",
"user_id": "string"
}'# Headers
X-Session-ID: string
X-Agent-Engine-Test-Session: true
# Payload
{
"message": "string",
"resume_map": {},
"session_id": "string",
"user_id": "string"
}{
"detail": "This operation is not available in API version 2026-09-20-preview.",
"error": 406,
"errorCode": "OPERATION_NOT_IN_API_VERSION",
"parameters": [
"Accept"
],
"reason": "Not Acceptable"
}{
"detail": "This operation supports text/event-stream, which the Accept header excludes. Remove unsupported media-type parameters or accept this type with a positive q value.",
"error": 406,
"errorCode": "UNACCEPTABLE_MEDIA_TYPE",
"parameters": [
"Accept"
],
"reason": "Not Acceptable"
}{
"detail": "The requested API version is not supported. Supported versions: 2026-09-20-preview.",
"error": 406,
"errorCode": "UNSUPPORTED_API_VERSION",
"parameters": [
"Accept"
],
"reason": "Not Acceptable"
}{
"detail": "This operation is not available in API version 2026-09-20-preview.",
"error": 406,
"errorCode": "OPERATION_NOT_IN_API_VERSION",
"parameters": [
"Accept"
],
"reason": "Not Acceptable"
}: connected
data: {"message":"Example event payload"}
{
"code": "string",
"error": "string",
"success": true
}{
"code": "string",
"error": "string",
"success": true
}{
"code": "string",
"error": "string",
"success": true
}{
"code": "string",
"error": "string",
"success": true
}{
"blocking_execution_id": "string",
"blocking_status": "string",
"code": "string",
"error": "string",
"last_activity_at": "string"
}{
"blocking_execution_id": "string",
"blocking_status": "string",
"code": "string",
"error": "string",
"last_activity_at": "string"
}{
"code": "string",
"error": "string",
"success": true
}{
"code": "string",
"error": "string",
"success": true
}# Headers
Retry-After: string
# Payload
{
"code": "string",
"error": "string",
"success": true
}# Headers
Retry-After: string
# Payload
{
"code": "string",
"error": "string",
"success": true
}{
"code": "string",
"error": "string",
"success": true
}{
"boot_id": "string",
"code": "string",
"component": "string",
"error": "string",
"execution_id": "string",
"sandbox": "string",
"source": "string",
"success": true
}{
"code": "string",
"error": "string",
"success": true
}{
"boot_id": "string",
"code": "string",
"component": "string",
"error": "string",
"execution_id": "string",
"sandbox": "string",
"source": "string",
"success": true
}# Headers
Retry-After: string
# Payload
{
"boot_id": "string",
"code": "string",
"component": "string",
"error": "string",
"execution_id": "string",
"sandbox": "string",
"source": "string",
"success": true
}# Headers
Retry-After: string
# Payload
{
"code": "string",
"error": "string",
"success": true
}# Headers
Retry-After: string
# Payload
{
"boot_id": "string",
"code": "string",
"component": "string",
"error": "string",
"execution_id": "string",
"sandbox": "string",
"source": "string",
"success": true
}# Headers
Retry-After: string
# Payload
{
"code": "string",
"error": "string",
"success": true
}{
"code": "string",
"error": "string",
"success": true
}{
"code": "string",
"error": "string",
"success": true
}