> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiraa.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Playground

> Teste seus agentes em tempo real — voz com microfone ou chat por texto — antes de colocar em produção

O **Playground** é seu ambiente de testes para conversar com seus agentes antes de colocá-los em produção. Ele tem **dois modos** — **Voz** (chamada LiveKit com microfone) e **Texto** (chat stateless) — usando o **mesmo agente, as mesmas tools e a mesma base de conhecimento**.

<Info>
  Os agentes da Kiraa são **omnichannel**: o mesmo cérebro atende voz e WhatsApp em produção. O Playground reflete isso — você pode validar o agente em ambos os modos antes de ativá-lo.
</Info>

***

## Os dois modos

<CardGroup cols={2}>
  <Card title="Voz" icon="microphone">
    Conversa por **microfone** com LiveKit em tempo real. Reproduz exatamente o que acontece numa ligação real (com STT, TTS, detecção de fim de fala).
  </Card>

  <Card title="Texto" icon="keyboard">
    Chat **stateless** com o agente — útil para validar tom, escopo de respostas e tools que rodam em texto (como o agente WhatsApp em produção).
  </Card>
</CardGroup>

<Tip>
  **Texto** é o modo **padrão** ao abrir o Playground. Use-o para iterar rápido em prompts e validar respostas; use **Voz** quando quiser confirmar que tudo funciona em chamada real.
</Tip>

***

## Configuração inicial (Welcome View)

Ao acessar o Playground, você vê uma tela de configuração com:

* **Tabs Voz / Texto** — escolhe o modo de teste.
* **Seletor de Agente** — apenas agentes **ativos** aparecem.
* **Seletor de Cliente (opcional)** — vincula a sessão a um cliente do CRM. Útil para validar tools de [CRM Action](/tools), classificação de etapa pós-conversa e contexto do agente.
* **Detalhes do Agente** — voz selecionada, número de tools, base de conhecimento.
* **Botão Iniciar** — começa a sessão no modo escolhido.

<Warning>
  Apenas agentes **ativos** aparecem no seletor. Se você não vê seu agente, verifique se ele está ativo em **Studio de IA > Agentes**.
</Warning>

***

## Modo Voz (LiveKit + microfone)

### Como funciona

<Steps>
  <Step title="Selecione o modo Voz">
    Clique na aba **Voz** na tela inicial.
  </Step>

  <Step title="Escolha agente e (opcional) cliente">
    Selecione o agente e, se quiser, um cliente do CRM para anexar contexto.
  </Step>

  <Step title="Permita o microfone">
    O navegador solicita permissão na primeira vez — clique em **Permitir**.
  </Step>

  <Step title="Inicie a chamada">
    Clique em **Iniciar**. O Playground conecta na sessão LiveKit.
  </Step>

  <Step title="Comece a conversar">
    O agente fala a mensagem inicial (se configurada) e ouve o microfone. Não precisa pressionar nada para falar — o sistema detecta automaticamente.
  </Step>
</Steps>

### Interface da sessão de voz

* **Visualizador de áudio** — animação que responde à voz do agente.
* **Transcrição em tempo real** — histórico da conversa por escrito.
* **Barra de controles** — ativar/desativar microfone, mostrar transcrição, encerrar.

### Consumo de créditos

<Info>
  O modo Voz **consome créditos** da sua conta — usa os mesmos recursos de uma chamada real (STT, LLM, TTS, LiveKit). Veja consumo em **Uso**.
</Info>

***

## Modo Texto (chat stateless)

### Como funciona

<Steps>
  <Step title="Selecione o modo Texto">
    Clique na aba **Texto** na tela inicial (é o padrão).
  </Step>

  <Step title="Escolha agente e (opcional) cliente">
    Mesmo seletor da configuração de voz.
  </Step>

  <Step title="Inicie o chat">
    Clique em **Iniciar**. Sem permissão de microfone, sem LiveKit — abre direto o chat.
  </Step>

  <Step title="Digite e envie">
    O agente responde por texto. Cada mensagem aciona o LLM e tools normalmente.
  </Step>
</Steps>

### O que esperar

* **Conversa efêmera**: as mensagens não ficam salvas após encerrar (chat é **stateless**).
* **Tools rodam normalmente**: tools de tipo `endpoint`, `agendamento`, `crm_action` (move\_to\_stage, create\_task, schedule\_callback) funcionam em texto. Tools voice-only (handoff, encerrar chamada, mark\_\*, add\_client\_tag) **não** aparecem.
* **Anexos não suportados** ainda — diferente do agente WhatsApp em produção que aceita imagem e áudio.

<Tip>
  O modo Texto é ideal para **iteração rápida**: ajusta prompt → testa → ajusta de novo. Sem precisar gastar créditos de áudio.
</Tip>

### Por que existe um modo separado?

O agente WhatsApp em produção usa **OpenAI function calling** com schema diferente do agente de voz (LiveKit Agents). O Playground texto reproduz o comportamento do agente WhatsApp — assim você valida em ambiente parecido com o que o cliente final vai ver no WhatsApp.

***

## Vincular cliente do CRM à sessão

Tanto Voz quanto Texto aceitam um **cliente** opcional na configuração inicial. Quando você vincula:

* O agente recebe o **contexto do cliente** (nome, dados, custom fields, tags).
* **Tools CRM Action** (`move_to_stage`, `create_task`, `schedule_callback`, etc.) podem operar nesse cliente — útil para validar permissões, whitelist de etapas, criação de tarefa.
* **Classificação automática pós-call** (em modo Voz) é aplicada — o cliente pode ser movido de etapa quando a sessão termina.

<Warning>
  Em produção, o Playground move clientes reais. Se for testar `move_to_stage` ou `mark_converted`, **use um cliente de teste** ou crie um cliente dedicado para Playground.
</Warning>

***

## O que validar antes de produção

<CardGroup cols={2}>
  <Card title="Mensagem inicial" icon="message">
    Está correta? O tom é apropriado para o cenário?
  </Card>

  <Card title="Escopo do agente" icon="bullseye">
    Responde dentro do escopo definido nas Skills e Rules?
  </Card>

  <Card title="Tools" icon="wrench">
    Aciona as tools certas no momento certo? Ex: agendamento, CRM action.
  </Card>

  <Card title="Base de conhecimento" icon="book">
    Encontra informações dos documentos? Cita fontes corretas?
  </Card>

  <Card title="Tom e personalidade" icon="face-smile">
    Voz, velocidade, formalidade — combinam com a marca?
  </Card>

  <Card title="Transferência humana" icon="phone-arrow-right">
    Aciona handoff quando deve? (apenas em chamada real — não funciona no Playground)
  </Card>
</CardGroup>

<Warning>
  **Handoff NÃO funciona no Playground** — usa WebRTC, não SIP. Para validar transferência, faça uma chamada real para o número vinculado ao agente. Veja [Handoff em Tools](/tools#handoff).
</Warning>

***

## Resolução de Problemas

### Não consigo iniciar a sessão

| Problema                      | Solução                                              |
| ----------------------------- | ---------------------------------------------------- |
| Nenhum agente aparece         | Crie e ative um agente em **Studio de IA > Agentes** |
| Saldo insuficiente (modo Voz) | Adicione créditos em **Billing**                     |
| Botão desabilitado            | Selecione um agente no dropdown                      |

### Modo Voz não funciona

| Problema             | Solução                                           |
| -------------------- | ------------------------------------------------- |
| Microfone bloqueado  | Permita acesso nas configurações do navegador     |
| Sem áudio do agente  | Verifique volume do dispositivo e fones de ouvido |
| Muito ruído de fundo | Use fones com mic, ou troque para modo Texto      |

### Modo Texto não funciona

| Problema               | Solução                                                  |
| ---------------------- | -------------------------------------------------------- |
| Tool não acionada      | Verifique se a tool está vinculada e se não é voice-only |
| Resposta vazia         | Tente reiniciar a sessão; cheque logs do agente          |
| Erro `{code, message}` | Mostra erro estruturado — código indica a causa          |

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Adquirir Número" icon="phone" href="/phone-numbers">
    Conecte um número de telefone para receber chamadas reais
  </Card>

  <Card title="Tools (CRM Action)" icon="wrench" href="/tools">
    Configure tools que o agente usa para agir no CRM durante a conversa
  </Card>

  <Card title="Clientes (CRM)" icon="users" href="/clients">
    Crie clientes de teste para validar contexto de pipeline e custom fields
  </Card>

  <Card title="Board e Pipelines" icon="table-columns" href="/board">
    Configure descrições claras de etapa para classificação automática pós-call
  </Card>

  <Card title="Automações" icon="diagram-project" href="/automations">
    Conecte mudanças de etapa do Playground a réguas reativas
  </Card>

  <Card title="Acompanhar Uso" icon="chart-line" href="/insights">
    Monitore desempenho e uso após colocar o agente em produção
  </Card>
</CardGroup>