Eventos do cliente para o servidor
Nesta página
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.updateconfigura a sessão e pode ser enviado várias vezes - O
conversation.item.createpermite 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.cancelpermite interromper o agente quando o utilizador volta a falar