Invoca un agente de espacio de trabajo y transmite su respuesta como eventos enviados por el servidor. Para continuar una sesión, envíe el valor X-Session-ID devuelto por la respuesta anterior. Si omite el encabezado, la puerta de enlace inicia una nueva sesión y devuelve su ID en el encabezado de respuesta. El campo session_id del cuerpo no continúa una sesión. El cuerpo puede incluir campos adicionales de nivel superior. La puerta de enlace reenvía todos los campos excepto estos campos reservados: message, session_id, user_id y resume_map. resume_map continúa un turno suspendido. Para una sesión sin historial, resume_map se convierte en la entrada inicial del agente. Requiere un token Bearer válido.
Encabezados
-
ID de sesión devuelto por una respuesta anterior. Envíelo para continuar esa sesión. Los ID válidos coinciden con [A-Za-z0-9_-]{1,128}$. Si se omite, la puerta de enlace inicia una nueva sesión. El cuerpo session_id no continúa una sesión.
-
Clasifique una sesión recién creada como sesión de prueba; la clasificación existente permanece sin cambios.
Cuerpo
Requerido
Solicitud de invocación
-
Opcional cuando se proporcionan otros campos de agente: entrada de chat para agentes de chat. Nombre de campo reservado.
-
ResumeMap contiene respuestas por interrupción resueltas por OE. OE lo reenvía al agente como entrada ordinaria solo cuando inicia la primera ejecución de una sesión, donde no existe ningún turno suspendido local para responder.
Se permiten propiedades adicionales.
-
Campo de compatibilidad opcional. La puerta de enlace lo ignora para garantizar la continuidad de la sesión. Para continuar una sesión, envíe X-Session-ID en su lugar. Nombre de campo reservado.
-
Identidad opcional utilizada para la personalización y el aislamiento de memoria. Las llamadas con usuarios y claves API utilizan este valor o, por defecto, el usuario autenticado. Las llamadas a cuentas de servicio siempre utilizan la identidad de la cuenta de servicio. Las cuentas de servicio aún no pueden actuar como otro usuario. Nombre de campo reservado.
Respuestas
-
Versión de API no compatible o con formato incorrecto, operación no disponible en el contrato publicado seleccionado o representación inaceptable (incluidos parámetros de tipo de medio no compatibles o SSE excluidos). Los fallos de autenticación, autorización y límite de velocidad existentes tienen prioridad.
-
Flujo SSE. Un fallo previo al encabezado (antes del primer fotograma) se muestra como uno de los cuerpos de error JSON que se muestran a continuación; un fallo a mitad del flujo se muestra como un fragmento SSE terminal que contiene el mismo código/error, además de source/component/sandbox/boot_id en un objeto de metadatos para un sobre de fallo de inicio.
-
Solicitud incorrecta
-
No autorizado
-
Conflicto
-
PROJECT_SECRET_INVALID: el espacio de trabajo no puede iniciarse porque un secreto de proyecto no es válido o es inaccesible (corrija el secreto y vuelva a implementar); a mitad del proceso aparece como un fragmento SSE terminal con el código=PROJECT_SECRET_INVALID
-
Demasiadas peticiones
-
ErrorResponse o StartupFailureResponse para un fallo de inicio AGENT_STARTUP_FAILED/STARTUP_FAILED
-
StartupFailureResponse para un fallo de inicio POOL_EXHAUSTED/EXECUTOR_BOOT_FAILED/PLATFORM_DEPENDENCY_FAILED/POOL_UNREACHABLE; ErrorResponse en caso contrario. POOL_EXHAUSTED lleva un encabezado Retry-After.
-
Tiempo de espera del Gateway
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
}