Invoca un agente de espacio de trabajo y devuelve su respuesta. 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 la 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.
-
Presupuesto de espera por solicitud en segundos para esta invocación bloqueante (1-120). Si se omite, se utiliza por defecto el valor de INVOKE_WORKSPACE_TIMEOUT_SECONDS del despliegue.
El valor mínimo es
1, el valor máximo es120.
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.
-
OK
-
Solicitud incorrecta
-
No autorizado
-
Conflicto
-
PROJECT_SECRET_INVALID: el espacio de trabajo no se puede iniciar porque un secreto de proyecto no es válido o es inaccesible (corrija el secreto y vuelva a implementar).
-
Demasiadas peticiones
-
InvokeWorkspaceResponse cuando la ejecución del agente finaliza con un error (Success: false con un execution_id/status); StartupFailureResponse para un fallo de inicio AGENT_STARTUP_FAILED/STARTUP_FAILED; ErrorResponse en caso contrario.
-
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}/invoke' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "X-Session-ID: string" \
--header "X-Agent-Engine-Test-Session: true" \
--header "X-Agent-Engine-Invoke-Timeout-Seconds: 42" \
--data '{
"message": "string",
"resume_map": {},
"session_id": "string",
"user_id": "string"
}'# Headers
X-Session-ID: string
X-Agent-Engine-Test-Session: true
X-Agent-Engine-Invoke-Timeout-Seconds: 42
# 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"
}# Headers
X-Session-ID: string
# Payload
{
"error": "string",
"error_code": "string",
"execution_id": "string",
"response": "string",
"status": "string",
"success": true,
"suspend_context": {},
"suspend_reason": "string"
}# Headers
X-Session-ID: string
# Payload
{
"error": "string",
"error_code": "string",
"execution_id": "string",
"response": "string",
"status": "string",
"success": true,
"suspend_context": {},
"suspend_reason": "string"
}{
"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
}{
"error": "string",
"error_code": "string",
"execution_id": "string",
"response": "string",
"status": "string",
"success": true,
"suspend_context": {},
"suspend_reason": "string"
}{
"boot_id": "string",
"code": "string",
"component": "string",
"error": "string",
"execution_id": "string",
"sandbox": "string",
"source": "string",
"success": true
}{
"code": "string",
"error": "string",
"success": true
}{
"error": "string",
"error_code": "string",
"execution_id": "string",
"response": "string",
"status": "string",
"success": true,
"suspend_context": {},
"suspend_reason": "string"
}{
"boot_id": "string",
"code": "string",
"component": "string",
"error": "string",
"execution_id": "string",
"sandbox": "string",
"source": "string",
"success": true
}{
"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
}# 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
}