Estruturas de dados de sessão e evento - Qoder CN Series: Central de Documentação do Alibaba Cloud

Objeto Session

Os endpoints Crie, Get, List, Atualize e Archive Session retornam este objeto.

{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "Customer support assistant",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "Customer support conversation",
  "incremental_streaming_enabled": true,
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "credits": 12.5
  },
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T11:00:00Z"
}

Campo	Tipo	Sempre retornado	Descrição
`id`	string	Sim	ID da sessão com prefixo `sess_`.
`type`	string	Sim	Sempre `"session"`.
`identity_id`	string	Sim	ID da Forward Identity que identifica o usuário final associado a esta sessão.
`template`	object	Sim	Resumo do Forward Template. Consulte a tabela de resumo do template abaixo.
`source_type`	string	Sim	Origem da sessão: `api`, `im` ou `schedule`.
`status`	string	Sim	Status de execução da sessão: `idle`, `running`, `rescheduling`, `canceling` ou `terminated`. O campo `archived_at` indica o estado de arquivamento.
`title`	string	Sim	Título da sessão.
`incremental_streaming_enabled`	boolean	Sim	Indica se os eventos de streaming incremental estão ativados para esta sessão. O padrão é `false` quando omitido na criação. Não é possível alterar após a criação.
`metadata`	object	Não	Metadados de negócio definidos pelo chamador.
`config`	object	Não	Configuração da sessão. Omitido caso nenhuma configuração tenha sido fornecida.
`config.environment_variables`	object	Não	Variáveis de ambiente no nível da sessão como pares chave-valor.
`stats`	object	Não	Estatísticas de uso da sessão. Consulte a tabela de estatísticas da sessão abaixo.
`usage`	object	Não	Informações de uso. Pode ser omitido se o módulo de faturamento não estiver ativado.
`usage.credits`	number	Não	Créditos consumidos.
`archived_at`	string \	null	Sim	Timestamp de arquivamento. Retorna `null` se a sessão não estiver arquivada.
`created_at`	string	Sim	Hora de criação no formato RFC 3339.
`updated_at`	string	Sim	Hora da última atualização no formato RFC 3339.

Resumo do template

Campo	Tipo	Sempre retornado	Descrição
`id`	string	Sim	ID do Forward Template.
`type`	string	Sim	Sempre `"template"`.
`name`	string	Sim	Nome do template.
`model`	string	Sim	Camada ou identificador do modelo usado pelo template.
`version`	integer	Sim	Número da versão do template.

Estatísticas da sessão

Campo	Tipo	Sempre retornado	Descrição
`active_seconds`	integer	Não	Tempo de processamento ativo em segundos. Geralmente `0` para novas sessões.
`duration_seconds`	integer	Não	Duração total da sessão em segundos. Normalmente `0` para novas sessões.

Objeto Event

A API retorna eventos como objetos JSON cujo payload varia conforme o type. Todo evento contém o mesmo conjunto de campos comuns, além de campos de payload específicos do tipo.

{
  "id": "evt_xxx",
  "type": "agent.message",
  "session_id": "sess_xxx",
  "content": [
    {
      "type": "text",
      "text": "Here is the analysis result."
    }
  ],
  "processed_at": "2026-06-22T11:00:03Z"
}

Campo	Tipo	Sempre retornado	Descrição
`id`	string	Sim	ID do evento com prefixo `evt_`.
`type`	string	Sim	Tipo do evento.
`session_id`	string	Sim	ID da sessão à qual este evento pertence.
`processed_at`	string	Não	Hora de processamento do evento no formato RFC 3339. Pode estar ausente em certos eventos gerados pelo agente ou em eventos incrementais.

Os campos de payload permitidos para cada tipo de evento estão listados abaixo. A tabela não repete os campos comuns id, type, session_id e processed_at.

Tipo de evento	Campos permitidos
`user.message`	`content`
`user.interrupt`	Nenhum
`user.tool_confirmation`	`tool_use_id`, `result`, `deny_message`
`user.tool_result`	`tool_use_id`, `content`, `is_error`
`user.custom_tool_result`	`custom_tool_use_id`, `content`, `is_error`
`user.define_outcome`	`description`, `rubric`, `outcome_id`, `max_iterations`
`system.message`	`content`
`agent.message`	`content`
`agent.thinking`	Nenhum
`agent.message_start`	`message_id`, `message`
`agent.content_block_start`	`message_id`, `index`, `content_block`
`agent.content_block_delta`	`message_id`, `index`, `delta`
`agent.content_block_stop`	`message_id`, `index`
`agent.message_delta`	`message_id`, `delta`, `usage`
`agent.message_stop`	`message_id`
`agent.tool_use`	`name`, `input`, `evaluated_permission`
`agent.tool_result`	`tool_use_id`, `content`, `is_error`
`agent.custom_tool_use`	`name`, `input`
`agent.mcp_tool_use`	`mcp_server_name`, `name`, `input`, `evaluated_permission`
`agent.mcp_tool_result`	`mcp_tool_use_id`, `content`, `is_error`
`agent.artifact_delivered`	`file_id`, `original_filename`, `size`, `content_type`
`session.status_running`	Nenhum
`session.status_idle`	`stop_reason`
`session.status_terminated`	Nenhum
`session.error`	`error`
`session.updated`	`agent`, `metadata`, `title`

Tipos de evento graváveis pelo cliente

O endpoint POST /api/v1/forward/sessions/{session_id}/events aceita apenas os tipos de evento abaixo.

Tipo	Campos obrigatórios	Descrição
`user.message`	`content`	Mensagem do usuário. `content` deve ser um array não vazio de blocos de conteúdo e aceita tipos como `text`, `image` e `document`.
`user.interrupt`	Nenhum	Solicita a interrupção do turno atual.
`user.tool_confirmation`	`tool_use_id`, `result`	Confirmação de chamada de ferramenta. `result` deve ser `allow` ou `deny`. Em caso de negação, envie também `deny_message`.
`user.tool_result`	`tool_use_id`	Retorna o resultado de uma ferramenta integrada. `content` e `is_error` são opcionais.
`user.custom_tool_result`	`custom_tool_use_id`	Retorna o resultado de uma ferramenta personalizada definida pelo cliente. `content` e `is_error` são opcionais.
`user.define_outcome`	`description`, `rubric`	Define o resultado desejado e sua rubrica de avaliação. `max_iterations` é opcional.

Embora system.message seja um tipo de evento público, o Forward não o aceita como evento gravável pelo cliente.

Tipos de evento públicos

Ao consultar o histórico de eventos ou assinar o stream SSE, você pode receber qualquer um dos seguintes tipos de evento públicos:

user.message, user.interrupt, user.tool_confirmation, user.tool_result, user.custom_tool_result, user.define_outcome, system.message, agent.message, agent.thinking, agent.message_start, agent.content_block_start, agent.content_block_delta, agent.content_block_stop, agent.message_delta, agent.message_stop, agent.tool_use, agent.tool_result, agent.custom_tool_use, agent.mcp_tool_use, agent.mcp_tool_result, agent.artifact_delivered, session.status_running, session.status_idle, session.status_terminated, session.error e session.updated.

Eventos de streaming incremental

O campo incremental_streaming_enabled, definido na criação da sessão, controla a exposição dos eventos de streaming incremental. Parâmetros de requisição em consultas de histórico ou assinaturas SSE não afetam esse comportamento:

true: O stream de eventos retorna a saída parcial do assistente antes do agent.message final. Consultas de histórico também retornam esses eventos incrementais.
false ou omitido: Modo padrão. Retorna apenas eventos públicos completos, sem emissão de eventos incrementais.

Mesmo com o streaming incremental ativado, o sistema ainda retorna o agent.message completo ao final. Use os eventos incrementais para renderização imediata e considere o agent.message final como source de verdade para persistência e reconciliação de exibição.

Somente os seis tipos de evento de nível superior a seguir são incrementais:

Tipo de evento	Campos principais	Descrição
`agent.message_start`	`message_id`, `message`	Marca o início de uma mensagem do assistente.
`agent.content_block_start`	`message_id`, `index`, `content_block`	Indica o início de um bloco de conteúdo, como texto, raciocínio ou uso de ferramenta.
`agent.content_block_delta`	`message_id`, `index`, `delta`	Entrega um fragmento incremental do bloco de conteúdo no `index`.
`agent.content_block_stop`	`message_id`, `index`	Marca o fim do bloco de conteúdo no `index`.
`agent.message_delta`	`message_id`, `delta`, `usage`	Fornece incrementos no nível da mensagem, como `stop_reason`, `stop_sequence` e informações de uso.
`agent.message_stop`	`message_id`	Sinaliza o término de uma mensagem do assistente.

text_delta, thinking_delta, signature_delta, input_json_delta e tool_output_delta não são tipos de evento de nível superior. Eles aparecem apenas como valores de agent.content_block_delta.delta.type.

delta.type	Campo	Descrição
`text_delta`	`text`	Fragmento de saída de texto. Concatene `delta.text` para reconstruir o texto completo.
`thinking_delta`	`thinking`	Fragmento da saída de raciocínio do modelo ou provedor.
`signature_delta`	`signature`	Fragmento de assinatura para um bloco de raciocínio. Emitido apenas quando há uma assinatura presente.
`input_json_delta`	`partial_json`	Fragmento do json de entrada da ferramenta.
`tool_output_delta`	variável	Reservado para futuro streaming de saída de ferramenta. Atualmente, o `agent.tool_result` completo permanece como referência autoritativa.

Exemplo de agent.content_block_delta:

{
  "id": "evt_delta_xxx",
  "type": "agent.content_block_delta",
  "session_id": "sess_xxx",
  "message_id": "msg_xxx",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "Here"
  },
  "processed_at": "2026-06-22T11:00:01Z"
}

Regras para análise de eventos incrementais:

Tanto a linha SSE event: quanto o campo json data.type usam os tipos de evento públicos.
agent.content_block_delta.index distingue múltiplos blocos de conteúdo.
processed_at pode estar ausente em eventos incrementais. Trate-o como opcional.
Após uma interrupção de rede, use o cabeçalho Last-Event-ID com o último ID de evento recebido para retomar o stream.
Defina include_thinking=false filtra thinking_delta, signature_delta e eventos reconhecíveis de início ou fim de bloco de conteúdo de raciocínio.
Defina include_tool_calls=false filtra input_json_delta, tool_output_delta e eventos reconhecíveis de início ou fim de bloco de conteúdo de ferramenta.