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, mcp_call, handover, oauth_required)
`response.output_item.done`	Item de saída completo
`response.mcp_call.in_progress`	Uma chamada de tool de servidor está rodando (assistant ou especialista)
`response.mcp_call.completed`	Essa chamada retornou
`response.mcp_call.failed`	Essa chamada falhou
`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, o assistant decide chamar tools, uma tool executa, um especialista é consultado, a resposta é regenerada em um conector de fallback).

{
  "type": "response.status",
  "code": "tool_calling",
  "message": "Calling 2 tool(s)",
  "metadata": { "tools": ["get_forecast", "create_risk_alert"] }
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.status"`
`code`	`string`	Código de status legível por máquina (veja abaixo)
`message`	`string`	Descrição legível por humanos, para logs — não é localizada
`metadata`	`object`	Payload estruturado para os códigos que o carregam; ausente nos demais

Código	Significado
`tool_calling`	O modelo pediu tools nesta iteração. `metadata.tools` lista as tools de servidor pelo nome, uma entrada por chamada, na ordem das chamadas. Function tools do lado do cliente não aparecem aqui: elas chegam como itens `function_call`.
`tool_executing`	Uma tool de servidor está executando. `metadata.toolName` diz qual, `metadata.callId` identifica a chamada, `metadata.arguments` é o JSON que o modelo pediu. Repete enquanto uma tool lenta roda (keepalive). Uma tool executada por um especialista consultado traz `metadata.specialistId` / `specialistName`.
`tool_complete`	Essa chamada terminou. Mesmo metadata mais `metadata.outcome`: `success`, ou `error` com `metadata.error`. A mesma chamada também sai como um item `mcp_call`, que é a forma indicada para montar uma UI de progresso.
`generating`	O modelo está produzindo saída sem nada mais no fio (mantém a conexão viva)
`regenerating`	A resposta está sendo regenerada em um conector de fallback; descarte os itens `interim` recebidos até aqui
`iteration_limit`	O loop de tools atingiu o limite de iterações; a resposta é o que o modelo produziu

Medindo o que um turno fez

Um turno que consultou dados e um turno que só conversou ficam iguais no response.completed. Os eventos tool_calling distinguem os dois: junte metadata.tools ao longo do turno e você sabe quais tools rodaram, sem inspecionar o texto do usuário.

`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 chamada MCP¶

Uma chamada de tool de servidor do turno, no formato mcp_call da OpenAI Responses — o item para o qual uma UI de progresso no estilo ChatGPT desenha um card. Emitido para as tools do próprio assistant e para as tools que um especialista consultado executa: server_label diz quem rodou ("assistant", ou o nome do especialista), e a chamada de um especialista também traz specialist_id / specialist_name. O item é adicionado com status: "in_progress", seguido de response.mcp_call.in_progress enquanto roda e response.mcp_call.completed ou response.mcp_call.failed quando termina, e então response.output_item.done com o item final. output é sempre null: o resultado da tool é material do modelo, a resposta é o que o usuário recebe.

{
  "type": "response.output_item.added",
  "output_index": 1,
  "item": {
    "type": "mcp_call",
    "id": "mcp_01234567-89ab-cdef-0123-456789abcdef",
    "status": "in_progress",
    "server_label": "Analista de Operações Portuárias",
    "specialist_id": "55425e00-124f-4a9e-9148-9d596578b9bf",
    "specialist_name": "Analista de Operações Portuárias",
    "name": "ClosureStudyController_getRiskTiers",
    "arguments": "{\"port\":\"Santos\"}",
    "output": null,
    "error": null
  }
}

Campo	Tipo	Descrição
`item.type`	`"mcp_call"`	Identifica uma chamada de tool de servidor
`item.id`	`string`	Id do item (`mcp_<uuid>`), o mesmo em todos os eventos do seu ciclo de vida
`item.status`	`string`	`in_progress`, `completed` ou `failed`
`item.server_label`	`string`	Quem rodou a tool: `"assistant"` ou o nome do especialista consultado. Não é um identificador de servidor MCP hoje, então não condicione comportamento por servidor a ele
`item.name`	`string`	Nome técnico da tool, como o modelo a chamou (mapeie para o seu próprio rótulo)
`item.arguments`	`string`	Argumentos em JSON que o modelo produziu
`item.output`	`null`	Nunca enviado. O resultado da tool é material do modelo e a única superfície por onde um segredo buscado poderia vazar; a resposta é o que o usuário recebe
`item.error`	`string?`	Por que a chamada falhou, quando `status` é `failed`
`item.specialist_id`	`string?`	Presente quando um especialista consultado rodou a tool
`item.specialist_name`	`string?`	Presente quando um especialista consultado rodou a tool

Caso de uso: mostre uma linha de atividade por chamada ("Consultando risco de fechamento…") e atualize conforme os eventos do ciclo de vida chegam. No fim, response.completed.output lista todo mcp_call do turno, e é assim que você sabe o que o turno fez sem cruzar eventos. Function tools do lado do cliente não são itens mcp_call: continuam como itens function_call, já que quem as executa é você.

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.mcp_call.in_progress`¶

Emitido enquanto uma chamada de tool de servidor (um item mcp_call) está rodando. Repete a cada poucos segundos enquanto uma tool lenta executa, para a conexão continuar viva e a UI de progresso manter a linha ativa.

{
  "type": "response.mcp_call.in_progress",
  "item_id": "mcp_01234567-89ab-cdef-0123-456789abcdef",
  "output_index": 1
}

Campo	Tipo	Descrição
`type`	`string`	Sempre `"response.mcp_call.in_progress"`
`item_id`	`string`	O item `mcp_call` a que este evento pertence
`output_index`	`number`	Sua posição no array de saída

`response.mcp_call.completed`¶

Emitido quando essa chamada retornou. response.output_item.done vem em seguida com o item em status: "completed".

{
  "type": "response.mcp_call.completed",
  "item_id": "mcp_01234567-89ab-cdef-0123-456789abcdef",
  "output_index": 1
}

`response.mcp_call.failed`¶

Emitido quando essa chamada falhou, ou pediu uma tool que não existe. response.output_item.done vem em seguida com o item em status: "failed" e o mesmo error. O assistant segue com a resposta, então uma chamada falha é informação para a UI, não o fim da resposta.

{
  "type": "response.mcp_call.failed",
  "item_id": "mcp_01234567-89ab-cdef-0123-456789abcdef",
  "output_index": 1,
  "error": "HTTP request failed (404)"
}

`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."
          }
        ]
      }
    ],
    "usage": {
      "input_tokens": 12000,
      "input_tokens_details": { "cached_tokens": 10400 },
      "output_tokens": 350,
      "output_tokens_details": { "reasoning_tokens": 0 },
      "total_tokens": 12350
    },
    "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.usage.input_tokens`	`number`	Tokens de entrada de todas as chamadas de modelo do turno (loop de tools e consultas a especialistas incluídos)
`response.usage.input_tokens_details.cached_tokens`	`number`	A parte de `input_tokens` servida do cache de prompt do provedor. Presente só quando o provedor informou — ausente significa "não informado", nunca "nada cacheado"
`response.usage.output_tokens`	`number`	Tokens de saída, somados da mesma forma
`response.usage.output_tokens_details.reasoning_tokens`	`number`	Tokens de raciocínio dentro de `output_tokens`, quando o provedor informa
`response.usage.total_tokens`	`number`	`input_tokens + output_tokens`
`response.created_at`	`number`	Timestamp Unix

O mesmo objeto usage é retornado na resposta sem streaming. Os totais são os que a tela de uso mostra para o turno.

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¶