调用工作区代理并返回其响应。要继续会话，请发送上一个响应返回的 X-Session- ID值。如果省略该标头，网关将启动一个新会话，并在响应标头中返回其ID 。正文 session_id字段不会继续会话。正文可以包含额外的顶级字段。网关会转发除以下保留字段之外的所有字段：message、session_id、user_id 和resume_map。 resume_map 会继续暂停的回合。对于没有历史记录的会话，resume_map 将成为代理的初始输入。需要有效的持有者令牌。
标头
-
上一个响应返回的会话ID 。发送它以继续该会话。有效 ID 匹配 [A-Za-z0-9_-]{1,128}$。如果省略，网关将启动一个新会话。正文 session_id 不会继续会话
-
将新创建的会话归类为测试会话；现有分类不变
-
此阻塞调用 (1-120) 的每个请求等待预算（以秒为单位）。省略时默认为部署的 INVOKE_WORKSPACE_TIMEOUT_SECONDS
最小值为
1，最大值为120。
响应
-
不支持或格式不正确的API版本、所选已发布合约中不可用的操作或不可接受的表示形式（包括不支持的媒体类型参数或排除的 SSE）。现有的身份验证、授权和速率限制失败优先。
-
正常
-
Bad Request
-
Unauthorized
-
冲突
-
PROJECT_SECRET_INVALID：工作区无法启动，因为项目密钥无效或无法访问（修复密钥并重新部署）
-
请求过多
-
当代理自身的执行因错误而解决时，调用 WorkspaceResponse（Success:false，带有execution_id/status）；针对 AGENT_STARTUP_FAILED/STARTUP_FAILED初创企业失败的 StartupFailureResponse；否则出现错误响应
-
针对 POOL_EXHAUSTED/EXECUTOR_BOOT_FAILED/PLATFORM_DEPENDENCY_FAILED/POOL_UNREACHABLE初创企业失败的 StartupFailureResponse；否则为 ErrorResponse。 POOL_EXHAUSTED 带有 Retry-After 标头
-
网关超时
POST /api/v1/projects/{id}/workspaces/{workspace_id}/invoke
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"
}
响应示例 (406)
操作不可用
{
"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"
}
响应示例 (406)
{
"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"
}
响应示例 (200)
# 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"
}
响应示例 (200)
# 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"
}
响应示例 (400)
{
"code": "string",
"error": "string",
"success": true
}
响应示例 (400)
{
"code": "string",
"error": "string",
"success": true
}
响应示例 (401)
{
"code": "string",
"error": "string",
"success": true
}
响应示例 (401)
{
"code": "string",
"error": "string",
"success": true
}
响应示例 (409)
{
"blocking_execution_id": "string",
"blocking_status": "string",
"code": "string",
"error": "string",
"last_activity_at": "string"
}
响应示例 (409)
{
"blocking_execution_id": "string",
"blocking_status": "string",
"code": "string",
"error": "string",
"last_activity_at": "string"
}
响应示例 (422)
{
"code": "string",
"error": "string",
"success": true
}
响应示例 (422)
{
"code": "string",
"error": "string",
"success": true
}
响应示例 (429)
# Headers
Retry-After: string
# Payload
{
"code": "string",
"error": "string",
"success": true
}
响应示例 (429)
# Headers
Retry-After: string
# Payload
{
"code": "string",
"error": "string",
"success": true
}
响应示例 (500)
Invokeworkspaceresponse
{
"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
}
响应示例 (500)
Invokeworkspaceresponse
{
"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
}
响应示例 (503)
Startupfailureresponse
# 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
}
响应示例 (503)
Startupfailureresponse
# 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
}
响应示例 (504)
{
"code": "string",
"error": "string",
"success": true
}
响应示例 (504)
{
"code": "string",
"error": "string",
"success": true
}