Invoca um agente de espaço de trabalho e retorna sua resposta. Para continuar uma sessão, envie o valor X-Session-ID retornado pela resposta anterior. Se você omitir o cabeçalho, o gateway iniciará uma nova sessão e retornará seu ID no cabeçalho de resposta. O campo session_id do corpo não continua uma sessão. O corpo pode incluir campos extras de nível superior. O gateway encaminha todos os campo , exceto estes campos reservados: message, session_id, user_id e resume_map. resume_map continua uma curva suspensa. Para uma sessão sem histórico, resume_map se torna a entrada inicial do agente . Exige um token de Portador válido.
Cabeçalhos
-
ID da sessão retornada por uma resposta anterior. Envie para continuar a sessão. As IDs válidas correspondem a [A-Za-z0-9_-]{1,128}$. Se omitido, o gateway inicia uma nova sessão. O corpo da sessão_id não continua uma sessão
-
Classificar uma sessão recém-criada como uma sessão de teste; a classificação existente não é alterada
-
orçamento de espera por solicitação em segundos para esta invocação de bloqueio (1-120). O padrão é o INVOKE_WORKSPACE_TIMEOUT_SECONDS do sistema quando omitido
O valor mínimo é
1, o valor máximo é120.
corpo, corpo
Obrigatório
Solicitação de invocar
-
Opcional quando outros campos do agente são fornecidos: entrada de chat para agentes de chat. Nome do campo reservado.
-
ResumeMap contém respostas por interrupção resolvidas por OE. A OE a encaminha para o agente como entrada comum somente quando inicia a primeira execução de uma sessão, onde não existe nenhuma vez suspensa local para responder.
Propriedades adicionais são permitidas.
-
campo de compatibilidade opcional. O gateway o ignora para a continuação da sessão. Para continuar uma sessão, envie X-Session-ID . Nome do campo reservado.
-
Identidade opcional usada para personalização e isolamento de memória. As chamadas de chave de API e humanos usam esse valor ou padrão para o usuário autenticado. As chamadas de conta de serviço sempre usam a identidade da conta de serviço. As contas de serviço ainda não podem agir como outro usuário. Nome do campo reservado.
Respostas
-
Versão de API não permitida ou malformada, uma operação indisponível no contrato publicado selecionado ou uma representação inaceitável (incluindo parâmetros de tipo de mídia não suportados ou SSE excluído). Falhas existentes de autenticação, autorização e limite de taxa têm precedência.
-
OK
-
Solicitação inválida
-
Não autorizado
-
Conflito
-
PROJECT_SECRET_INVALID: o espaço de trabalho não pode ser iniciado porque um segredo de projeto é inválido ou inacessível (corrija o segredo e redistribua)
-
Muitas solicitações
-
InvokeWorkspaceResponse quando a execução do próprio agente for resolvida com um erro(Sucesso:false com execution_id/status); StartupFailureResponse para uma falha de inicialização do AGENT_STARTUP_FAILED/STARTUP_FAILED; ErroResposta de outra forma
-
StartupFailureResponse para uma falha de inicialização POOL_EXHAUSTED/EXECUTOR_BOOT_FAILED/PLATFORM_DEPENDENCY_FAILED/POOL_UNREACHABLE; ErrorResponse de outra forma. POOL_EXHAUSTED carrega um cabeçalho Retry-After
-
Tempo limite do 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
}