Referência de Eventos SSE¶

Referência completa de todos os Server-Sent Events emitidos pela API de streaming do Nodexa (stream: true).

Formato dos Eventos¶

Cada evento é enviado como duas linhas seguidas de uma linha em branco:

event: <event-type>
data: <json-payload>

O stream termina com:

data: [DONE]

Heartbeat¶

A cada 15 segundos de inatividade, uma linha de comentário é enviada para manter a conexão ativa:

: heartbeat

Comentários SSE (linhas começando com :) são ignorados pelos parsers padrão.

Índice de Eventos¶

Evento	Descrição
`response.created`	Stream iniciado, processamento começa
`response.status`	Atualização de status de processamento
`response.output_text.delta`	Token de texto do assistant
`response.reasoning_summary_text.delta`	Token de resumo de raciocínio (apenas modelos de raciocínio)
`response.function_call_arguments.delta`	Argumentos parciais de chamada de função
`response.function_call_arguments.done`	Argumentos de chamada de função completos
`response.output_item.added`	Novo item de saída adicionado (message, handover, oauth_required)
`response.output_item.done`	Item de saída completo
`response.web_search_call.in_progress`	Busca na web iniciando
`response.web_search_call.searching`	Consulta de busca na web submetida
`response.web_search_call.completed`	Resultados de busca na web prontos
`response.completed`	Resposta totalmente completa
`response.error`	Erro ocorrido, stream encerrando

Detalhes dos Eventos¶

`response.created`¶

Emitido imediatamente quando a plataforma começa a processar a request.

{
  "type": "response.created",
  "response": {
    "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
    "status": "in_progress"
  }
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.created"`
`response.id`	`string`	ID único de resposta para threading
`response.status`	`string`	Sempre `"in_progress"` neste ponto

Caso de uso: Exibir um indicador de carregamento/digitação.

`response.status`¶

Emitido quando o status de processamento interno muda (por exemplo, roteando para um Agente Especialista, carregando tools, executando recuperação de dados).

{
  "type": "response.status",
  "status": "processing"
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.status"`
`status`	`string`	Descrição do status atual

`response.output_text.delta`¶

Emitido para cada token de texto. Concatene todos os valores delta para reconstruir o texto completo.

{
  "type": "response.output_text.delta",
  "delta": " world"
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.output_text.delta"`
`delta`	`string`	Token(s) a adicionar ao buffer de texto atual

Caso de uso: Adicione cada delta ao seu buffer de exibição de texto.

let textBuffer = '';
if (event.type === 'response.output_text.delta') {
  textBuffer += event.delta;
  updateUI(textBuffer);
}

`response.reasoning_summary_text.delta`¶

Emitido durante a fase de raciocínio de modelos que expõem um resumo de raciocínio (por exemplo, OpenAI o1, o3-mini). Esses tokens representam o processo de "pensamento" visível do modelo, não a resposta final.

{
  "type": "response.reasoning_summary_text.delta",
  "delta": "The user is asking about the history of"
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.reasoning_summary_text.delta"`
`delta`	`string`	Token(s) de resumo de raciocínio

Caso de uso: Opcionalmente exibir uma seção "pensando...". Esses tokens chegam antes dos eventos response.output_text.delta.

Note

Emitido apenas por modelos de raciocínio. Não aparece para modelos de chat padrão.

`response.function_call_arguments.delta`¶

Emitido enquanto o modelo gera argumentos JSON para uma function call. Útil para exibir um indicador de "preparando para chamar tool".

{
  "type": "response.function_call_arguments.delta",
  "delta": "{\"city\": \"Par"
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.function_call_arguments.delta"`
`delta`	`string`	String de argumentos JSON parcial

Caso de uso: Exibir um indicador de chamada de tool na interface.

`response.function_call_arguments.done`¶

Emitido quando os argumentos da function call estão completamente montados. Este é o evento que aciona a execução da tool no lado do cliente.

{
  "type": "response.function_call_arguments.done",
  "name": "get_weather",
  "call_id": "call_abc123",
  "arguments": "{\"city\": \"Paris\", \"unit\": \"celsius\"}"
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.function_call_arguments.done"`
`name`	`string`	Nome da função a chamar
`call_id`	`string`	ID único para esta chamada — inclua em `function_call_output`
`arguments`	`string`	String de argumentos completa codificada em JSON

Caso de uso: Faça parse de arguments, execute a função, colete o call_id e envie uma request de acompanhamento. Confira Function Calling.

`response.output_item.added`¶

Emitido quando o modelo adiciona um item estruturado ao seu array de saída. O item.type determina que tipo de item é.

Item de mensagem¶

{
  "type": "response.output_item.added",
  "item": {
    "type": "message",
    "role": "assistant",
    "content": []
  }
}

Item de handover¶

Emitido quando o controle é transferido de um Agente Especialista para outro.

{
  "type": "response.output_item.added",
  "item": {
    "type": "handover",
    "from_specialist": "General Assistant",
    "to_specialist": "Technical Support",
    "reason": "User is asking about API integration details"
  }
}

Campo	Tipo	Descrição
`item.type`	`"handover"`	Identifica isso como uma notificação de handover
`item.from_specialist`	`string`	Nome de exibição do Agente Especialista que estava ativo
`item.to_specialist`	`string`	Nome de exibição do Agente Especialista que assumiu
`item.reason`	`string`	Explicação do motivo do handover

Caso de uso: Registrar informações de roteamento ou exibir um aviso "conectando você ao [Agente Especialista]".

Item OAuth required¶

Emitido quando uma tool precisa de credenciais OAuth que não estão presentes na request.

{
  "type": "response.output_item.added",
  "item": {
    "type": "oauth_required",
    "plugin_id": "plugin_abc123",
    "plugin_name": "Google Calendar",
    "provider_id": "google",
    "required_scopes": ["https://www.googleapis.com/auth/calendar.readonly"],
    "auth_url": "https://your-admin.example.com/oauth/google/authorize?state=xyz"
  }
}

Campo	Tipo	Descrição
`item.type`	`"oauth_required"`	Identifica isso como um prompt OAuth
`item.plugin_id`	`string`	Identificador interno do plugin
`item.plugin_name`	`string`	Nome legível do plugin
`item.provider_id`	`string`	Identificador do provedor OAuth (ex.: `"google"`)
`item.required_scopes`	`string[]`	Escopos OAuth necessários
`item.auth_url`	`string`	URL para iniciar o fluxo de autorização OAuth

Caso de uso: Redirecionar o usuário para auth_url e depois retentar a requisição com o token obtido em x-user-tokens.

`response.output_item.done`¶

Emitido quando um item de saída está completamente montado (após todos os eventos delta para aquele item).

{
  "type": "response.output_item.done",
  "item": {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "The complete assembled response text."
      }
    ]
  }
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.output_item.done"`
`item`	`object`	O item de saída completamente montado

`response.web_search_call.in_progress`¶

Emitido quando uma tool de busca na web é invocada e a busca vai começar.

{
  "type": "response.web_search_call.in_progress",
  "call_id": "ws_call_abc123"
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.web_search_call.in_progress"`
`call_id`	`string`	Identificador único para esta chamada de busca

`response.web_search_call.searching`¶

Emitido quando a query de busca foi determinada e submetida.

{
  "type": "response.web_search_call.searching",
  "call_id": "ws_call_abc123",
  "query": "latest AI regulation news 2024"
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.web_search_call.searching"`
`call_id`	`string`	Identificador para esta chamada de busca
`query`	`string`	A consulta de busca submetida

Caso de uso: Exibir "Buscando por: [consulta]" na sua interface.

`response.web_search_call.completed`¶

Emitido quando os resultados de busca estão disponíveis e sendo incorporados.

{
  "type": "response.web_search_call.completed",
  "call_id": "ws_call_abc123",
  "results_count": 5
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.web_search_call.completed"`
`call_id`	`string`	Identificador para esta chamada de busca
`results_count`	`number`	Número de resultados de busca encontrados

`response.completed`¶

Emitido quando a resposta completa está pronta e o stream está prestes a fechar. Contém o objeto de resposta completo.

{
  "type": "response.completed",
  "response": {
    "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
    "object": "response",
    "status": "completed",
    "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
    "output_text": "The complete response text.",
    "output": [
      {
        "type": "message",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "The complete response text."
          }
        ]
      }
    ],
    "created_at": 1700000000
  }
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.completed"`
`response.id`	`string`	ID único de resposta — salve para continuidade de conversas
`response.status`	`string`	`"completed"` ou `"requires_action"`
`response.output_text`	`string`	Campo de conveniência com texto completo montado
`response.output`	`array`	Array de saída estruturada completo
`response.created_at`	`number`	Timestamp Unix

requires_action em response.completed

Se response.status for "requires_action", o assistant chamou uma function tool do lado do cliente e está aguardando os resultados. Você deve executar a função e enviar uma request de acompanhamento. Confira Function Calling.

`response.error`¶

Emitido quando ocorre um erro fatal durante o streaming. O stream fecha após este evento.

{
  "type": "response.error",
  "error": {
    "type": "server_error",
    "code": "upstream_timeout",
    "message": "The LLM provider did not respond within the timeout period."
  }
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.error"`
`error.type`	`string`	Categoria do erro (ex.: `"server_error"`, `"invalid_request_error"`)
`error.code`	`string`	Código de erro legível por máquina
`error.message`	`string`	Descrição do erro legível por humanos

Confira Erros para todos os códigos de erro e seus significados.

Sequência Típica de Eventos¶

Resposta de texto simples¶

response.created
response.output_item.added    (type: message)
response.output_text.delta    (repetido N vezes)
response.output_item.done
response.completed
[DONE]

Resposta com busca na web¶

response.created
response.web_search_call.in_progress
response.web_search_call.searching
response.web_search_call.completed
response.output_item.added    (type: message)
response.output_text.delta    (repetido N vezes)
response.output_item.done
response.completed
[DONE]

Resposta com handover de Agente Especialista¶

response.created
response.output_item.added    (type: handover)
response.output_item.done
response.output_item.added    (type: message)
response.output_text.delta    (repetido N vezes)
response.output_item.done
response.completed
[DONE]

Resposta que requer function call¶

response.created
response.output_item.added    (type: function_call - geralmente não emitido separadamente)
response.function_call_arguments.delta  (repetido)
response.function_call_arguments.done
response.completed            (status: requires_action)
[DONE]

Resposta com raciocínio (modelos de raciocínio)¶

response.created
response.reasoning_summary_text.delta  (repetido)
response.output_item.added    (type: message)
response.output_text.delta    (repetido N vezes)
response.output_item.done
response.completed
[DONE]

Referência de Eventos SSE¶

Formato dos Eventos¶

Heartbeat¶

Índice de Eventos¶

Detalhes dos Eventos¶

response.created¶

response.status¶

response.output_text.delta¶

response.reasoning_summary_text.delta¶

response.function_call_arguments.delta¶

response.function_call_arguments.done¶

response.output_item.added¶