Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Eventos do cliente para o servidor

Aula 9 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. As mensagens que envia
  2. conversation.item.create
  3. conversation.item.delete
  4. response.create e response.cancel
  5. Pontos-chave

As mensagens que envia

A API do Agente de Voz funciona através da troca de eventos JSON via WebSocket. Nesta lição, vai analisar todos os eventos que a sua aplicação pode enviar para o servidor. Cada um desempenha um papel específico no ciclo da conversação.

Evento Descrição Quando utilizar
session.update Configurar a sessão No arranque e para alterar a configuração
input_audio_buffer.append Enviar um fragmento de áudio em base64 Continuamente durante a gravação
input_audio_buffer.commit Confirmar o buffer de áudio No modo «push-to-talk»
input_audio_buffer.clear Esvaziar o buffer sem processamento Para cancelar uma gravação
conversation.item.create Adicionar uma mensagem ou resultado de função Histórico, contexto, resultados de funções
conversation.item.delete Eliminar um item pelo ID Limpeza da conversação
response.create Solicitar uma resposta No modo manual (automático com VAD)
response.cancel Cancelar uma resposta em curso Quando o utilizador interrompe

conversation.item.create

Este evento permite-lhe injetar mensagens na conversação sem passar pelo fluxo de áudio. Abrange três casos principais.

Adicionar uma mensagem de texto do utilizador

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "What's the status of my order 12345?"
      }
    ]
  }
}

Injetar histórico da conversação

Antes de iniciar a conversação por voz, pode preencher previamente o histórico com trocas anteriores para fornecer contexto ao agente:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello, I'm your assistant. How can I help you?"
      }
    ]
  }
}

Devolver o resultado de uma função

Após a execução de uma chamada de função, envia o resultado de volta com este evento (consulte a lição 13 sobre chamada de funções):

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"status\": \"shipped\", \"tracking\": \"FR123456789\"}"
  }
}

conversation.item.delete

Elimina um item da conversação através do seu ID:

{
  "type": "conversation.item.delete",
  "item_id": "item_audio_001"
}

Isto é útil para remover uma mensagem incorreta ou para impedir que o histórico da conversação cresça demasiado.

response.create e response.cancel

O response.create solicita explicitamente ao servidor que gere uma resposta. No modo VAD, o servidor faz isto automaticamente assim que deteta o fim da fala:

{
  "type": "response.create"
}

O response.cancel interrompe uma resposta que está a ser gerada. É útil quando o utilizador fala por cima do agente:

{
  "type": "response.cancel"
}

Pontos-chave

  • Podem ser enviados oito tipos de eventos do cliente para o servidor
  • O session.update configura a sessão e pode ser enviado várias vezes
  • O conversation.item.create permite adicionar texto, histórico ou resultados de funções
  • O response.create é obrigatório no modo manual e automático no modo VAD
  • O response.cancel permite interromper o agente quando o utilizador volta a falar