Eventos do cliente para o servidor

Eventos do cliente para o servidor são mensagens que sua aplicação envia proativamente ao servidor para fornecer contexto adicional durante as conversas. Esses eventos permitem aprimorar a conversa com informações relevantes sem interromper o fluxo conversacional.

Visão geral

Sua aplicação pode enviar informações contextuais ao servidor para melhorar a qualidade e a relevância da conversa em qualquer momento. Isso não precisa ocorrer em resposta a um evento de cliente recebido do servidor. Isso é especialmente útil para compartilhar o estado da UI, ações do usuário ou outros dados do ambiente que talvez não sejam comunicados diretamente por voz.

Tipos de evento

Atualizações contextuais

As atualizações contextuais permitem que sua aplicação envie informações de segundo plano não interruptivas para a conversa.

Principais características:

• As atualizações são incorporadas como informações de segundo plano na conversa.
• Não interrompem o fluxo atual da conversa.
• São úteis para enviar o estado da UI, ações do usuário ou dados do ambiente.

// Contextual update event structure
{
  "type": "contextual_update",
  "text": "User appears to be looking at pricing page"
}

// Example sending contextual updates
function sendContextUpdate(information) {
  websocket.send(
    JSON.stringify({
      type: "contextual_update",
      text: information,
    })
  );
}
// Usage examples
sendContextUpdate("Customer status: Premium tier");
sendContextUpdate("User navigated to Help section");
sendContextUpdate("Shopping cart contains 3 items");

Mensagens do usuário

As mensagens do usuário permitem enviar texto diretamente para a conversa como se o usuário o tivesse falado. Isso é útil para interações baseadas em texto ou quando você deseja inserir um texto específico no fluxo da conversa.

Principais características:

• O texto é processado como entrada do usuário na conversa.
• Aciona o mesmo fluxo de resposta da entrada falada do usuário.
• É útil para interfaces baseadas em texto ou entrada programática do usuário.

// User message event structure
{
  "type": "user_message",
  "text": "I would like to upgrade my account"
}

// Example sending user messages
function sendUserMessage(text) {
  websocket.send(
    JSON.stringify({
      type: "user_message",
      text: text,
    })
  );
}
// Usage examples
sendUserMessage("I need help with billing");
sendUserMessage("What are your pricing options?");
sendUserMessage("Cancel my subscription");

Atividade do usuário

Os eventos de atividade do usuário servem como indicadores para evitar interrupções do agente.

Principais características:

• Redefinem o temporizador de tempo limite do turno.
• Não afetam o conteúdo nem o fluxo da conversa.
• São úteis para manter conversas longas durante períodos de silêncio.

// User activity event structure
{
  "type": "user_activity"
}

// Example sending user activity
function sendUserActivity() {
  websocket.send(
    JSON.stringify({
      type: "user_activity",
    })
  );
}
// Usage example - send activity ping every 30 seconds
setInterval(sendUserActivity, 30000);

Boas práticas

1. Atualizações contextuais

   • Envie informações contextuais relevantes, mas concisas.
   • Evite sobrecarregar o LLM com muitas atualizações.
   • Foque em informações que afetam o fluxo da conversa ou que são um contexto importante de atividades em uma UI inacessível ao agente de voz.

2. Mensagens do usuário

   • Use-as para entradas do usuário baseadas em texto quando o áudio não estiver disponível ou não for adequado.
   • Garanta que o conteúdo do texto seja claro e bem formatado.
   • Considere o contexto da conversa ao inserir mensagens programáticas.

3. Atividade do usuário

   • Envie pings de atividade durante períodos de interação do usuário para manter a sessão.
   • Use intervalos razoáveis (por exemplo, 30 a 60 segundos) para evitar tráfego de rede desnecessário.
   • Implemente a detecção de atividade com base no engajamento real do usuário (movimento do mouse, digitação etc.).

4. Considerações de tempo

   • Envie atualizações nos momentos adequados.
   • Considere agrupar várias atualizações contextuais em uma única atualização (em vez de enviar cada pequena alteração separadamente).
   • Equilibre a manutenção da sessão ativa com a prevenção de mensagens em excesso.