# Agentes de Voz

{% embed url="https://www.youtube.com/watch?v=gNpagpQSlis" %}
Prefere assistir? Veja no vídeo como criar um agente de voz.
{% endembed %}

O **Agente de Voz** conversa com o usuário por **voz, em tempo real**, direto no navegador. O usuário fala ao microfone, o agente responde falando, e a conversa acontece como uma ligação: sem digitar, sem esperar uma resposta completa em texto. É possível **interromper o agente** falando por cima dele, e a transcrição aparece na tela enquanto vocês conversam.

É diferente do **ditado por voz** do chat de texto, que só transforma a sua fala em texto para você revisar e enviar. No agente de voz, a conversa inteira é falada.

Exemplos de uso: atendimento ao cliente, recepção virtual, suporte técnico, treino de entrevistas e prática de idiomas.

{% hint style="info" %}
**O que fica salvo.** O Power Omni guarda a **transcrição em texto** e os dados da sessão (duração, motivo do encerramento). **Não há gravação nem reprodução de áudio.** Cada conversa fica visível apenas para o usuário que a realizou.
{% endhint %}

### Antes de começar

Para criar agentes de voz, confira os requisitos:

* **Projeto New Foundry.** A voz não está disponível em projetos do modelo antigo.
* **Modelo de voz cadastrado** em **Artefatos > Modelos** (veja [Modelos de voz e tarifas](agentes-de-voz.md#modelos-de-voz-e-tarifas)).
* **Região compatível.** A disponibilidade do modelo e da voz no seu projeto é confirmada ao **salvar** o agente.
* **Navegador com HTTPS e acesso ao microfone.** Quem usa o agente precisa permitir o microfone quando o navegador pedir.
* **Permissão para criar.** Administradores, Colaboradores e [Workspace Owners](../../workspace-owner.md) podem criar e editar agentes de voz.

{% hint style="success" %}
**Instalação automática.** Ao instalar o Power Omni por **Faturamento > Configuração**, há o passo opcional **Habilitar conversas por voz**, que já cadastra um modelo de voz. Se a região não oferecer voz, a opção vem desmarcada e o agente é criado sem voz; um administrador pode cadastrar o modelo depois, em **Modelos**.
{% endhint %}

### Como criar um agente de voz

{% stepper %}
{% step %}
#### Abra Agentes e clique em Novo agente

Vá em **Artefatos > Agentes**, clique em **Novo agente** e escolha **Criar um agente**.
{% endstep %}

{% step %}
#### Escolha o tipo: Texto ou Voz

Na janela **Criar um agente**, escolha **Voz** (conversa falada em tempo real, com escolha de voz e de idioma) e clique em **Próximo**. Se preferir partir de um exemplo, escolha **Novo agente > Com modelo de agente** para abrir a galeria de modelos.

<figure><img class="only-light" src="../../../.gitbook/assets/agente-voz-novo-agente-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/agente-voz-novo-agente-dark.png" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**O tipo não muda depois.** Um agente criado como **Voz** continua sendo de voz (e um de **Texto** continua sendo de texto). Para ter os dois, crie dois agentes.
{% endhint %}
{% endstep %}

{% step %}
#### Escolha um modelo de partida (opcional)

A galeria lista os modelos de agente, com **busca** e filtro **Todos / Texto / Voz**. Ao escolher um modelo, as instruções e as configurações dele são **copiadas** para o seu agente, que continua independente: alterar o modelo depois não muda o seu agente.

<figure><img class="only-light" src="../../../.gitbook/assets/agente-voz-galeria-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/agente-voz-galeria-dark.png" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="230">Modelo de voz</th><th>Para que serve</th></tr></thead><tbody><tr><td><strong>Atendimento ao cliente</strong></td><td>Conversas de suporte claras e curtas, com confirmação de ações importantes.</td></tr><tr><td><strong>Recepcionista virtual</strong></td><td>Atende chamadas, faz a triagem, coleta nome e motivo e encaminha.</td></tr><tr><td><strong>Suporte técnico</strong></td><td>Diagnóstico passo a passo, confirmando o entendimento a cada etapa.</td></tr><tr><td><strong>Assistente de vendas</strong></td><td>Entende o interesse do cliente e qualifica a oportunidade sem prometer o que não sabe.</td></tr><tr><td><strong>Professor de inglês</strong></td><td>Prática de conversação com paciência, correções breves e ritmo adaptável.</td></tr><tr><td><strong>Treinador de entrevistas</strong></td><td>Simula uma entrevista e dá um feedback curto após cada resposta.</td></tr><tr><td><strong>Assistente geral</strong></td><td>Um ponto de partida útil para conversar no idioma do usuário.</td></tr><tr><td><strong>Começar do zero</strong></td><td>Um agente em branco: você escreve as instruções e configura a conversa.</td></tr></tbody></table>
{% endstep %}

{% step %}
#### Preencha as etapas do assistente

O assistente tem cinco etapas, descritas a seguir: **Agente e modelo**, **Conversa**, **Conectores e toolboxes**, **Acesso** e **Revisar**.
{% endstep %}

{% step %}
#### Revise e salve

Na última etapa, confira o resumo e salve. **Salvar publica uma nova versão** do agente.
{% endstep %}
{% endstepper %}

### Etapa 1: Agente e modelo

<figure><img class="only-light" src="../../../.gitbook/assets/agente-voz-etapa-agente-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/agente-voz-etapa-agente-dark.png" alt=""><figcaption></figcaption></figure>

| Campo | Descrição |
| --- | --- |
| **Nome** | Como o agente aparece para os usuários. |
| **Descrição** | Opcional, mas recomendada: ajuda o usuário a entender para que serve o agente. |
| **Projeto** | Projeto Foundry em que o agente será criado (só na criação). Escolha um projeto New Foundry. |
| **Modelo** | Modelo de voz em tempo real compatível. Modelos sem voz homologada neste projeto aparecem como indisponíveis, com o motivo. |
| **Gestão** | Quem gerencia o agente: a **Organização** (só Administradores e Colaboradores alteram) ou um workspace (os owners dele também). Veja [Workspace Owner](../../workspace-owner.md). |
| **Instruções** | O comportamento do agente. Para voz, prefira frases curtas, uma pergunta por vez, e evite pedir que o agente leia links, tabelas ou código em voz alta. |

O botão **Melhorar com IA** reescreve as instruções pensando em conversa falada (para usá-lo, escolha antes um projeto). Revise o texto antes de seguir.

### Etapa 2: Conversa

Aqui você define como o agente soa e como a conversa se comporta.

<figure><img class="only-light" src="../../../.gitbook/assets/agente-voz-etapa-conversa-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/agente-voz-etapa-conversa-dark.png" alt=""><figcaption></figcaption></figure>

* **Voz:** escolha entre as vozes homologadas para o modelo. Clique em **Ouvir amostra** para comparar. As amostras são áudios pré-gravados: **não** abrem uma sessão, não usam o microfone e não aparecem no histórico.
* **Idioma da conversa:** o idioma em que o usuário fala. Alguns modelos oferecem **Detecção automática de idioma**.
* **Modelo de transcrição:** modelo que transcreve a fala do usuário para o histórico.
* **Saudação:** marque **O agente inicia a conversa** para que ele fale primeiro. Você pode pedir que ele **fale um texto exato** ou que **gere a saudação a partir das instruções**. Algumas vozes não falam um texto exato; nesse caso, use a saudação gerada ou desative a saudação.

#### Configurações avançadas da conversa


Os padrões atendem à maioria dos casos. Ajuste apenas se precisar:

| Opção | O que faz |
| --- | --- |
| **Detecção de turnos** | Como o agente percebe que o usuário terminou de falar: detecção de atividade de voz no servidor, detecção semântica Azure ou detecção semântica OpenAI. |
| **Limiar de fala, prefixo de áudio e duração do silêncio** | Sensibilidade para detectar o início e o fim da fala. |
| **Velocidade da fala** | Ritmo da voz do agente. |
| **Máximo de tokens de saída** | Limite do tamanho de cada resposta. |
| **Dicas de reconhecimento** | Termos que o agente deve reconhecer melhor (nomes de produtos, siglas), um por linha. |
| **Supressão de ruído e cancelamento de eco** | Melhoram a captação em ambientes ruidosos. |
| **Permitir interrupção pela fala** | Quando ativo, o usuário pode interromper o agente falando. |
| **Mensagens intermediárias** | Frases curtas que o agente fala enquanto espera uma ferramenta responder. |
| **Temperatura da voz** | Variação na entonação, nos modelos que oferecem a opção. |

### Etapa 3: Conectores e toolboxes

Dê ferramentas ao agente para que ele consulte sistemas durante a conversa. Há dois modos, mutuamente exclusivos:

* **Ferramentas individuais:** conectores **MCP**, **até 20** por agente.
* **Uma toolbox:** uma [toolbox](../toolboxes.md) do projeto. É o caminho para usar **busca na web, interpretador de código, OpenAPI, Logic Apps e skills** em um agente de voz.

<figure><img class="only-light" src="../../../.gitbook/assets/agente-voz-etapa-ferramentas-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/agente-voz-etapa-ferramentas-dark.png" alt=""><figcaption></figcaption></figure>

Trocar de modo remove a seleção atual. Se não quiser ferramentas, clique em **Pular**. Itens que a voz não pode usar aparecem **desabilitados, com o motivo**. As regras principais:

* Conectores que exigem **consentimento do usuário** ou que **enviam o e-mail do usuário** não funcionam na voz.
* O conector MCP precisa ter **URL HTTPS**. Conectores antigos, que só têm o nome da conexão, não são aceitos.
* A toolbox precisa estar **publicada** e ter ao menos uma ferramenta ou skill. Ferramentas MCP dentro da toolbox não podem exigir aprovação.
* Itens **suspensos** pela gestão não podem ser anexados.

{% hint style="warning" %}
**Versão fixada.** O agente de voz guarda uma cópia dos conectores e toolboxes na versão em que foi publicado. Por isso, enquanto um agente de voz usar um conector ou toolbox, **não é possível editá-lo** nem alterar suas ferramentas. Para mudar, edite o agente de voz ou remova o vínculo.
{% endhint %}

### Etapa 4: Acesso

Escolha quem poderá usar o agente: **usuários, grupos e Áreas de Trabalho**. Você pode pular esta etapa e compartilhar depois pelas ações de compartilhamento da lista de agentes. Workspace Owners compartilham apenas dentro dos seus workspaces (veja [Workspace Owner](../../workspace-owner.md)).

### Etapa 5: Revisar

Confira nome, modelo, voz, idioma, instruções e acesso. Use **Editar** em qualquer bloco para voltar à etapa correspondente e clique em **Salvar**.


### Editando e versões

Cada vez que você salva, o Power Omni publica uma **nova versão** do agente de voz no Foundry.

* **Novas sessões** usam a versão mais recente publicada.
* **Sessões em andamento** mantêm as configurações com que começaram, mesmo que você edite o agente.
* Se alguém alterou o agente diretamente no portal do Foundry, o Power Omni avisa que existe uma **versão mais recente no Foundry**. Revise e clique em **Adotar versão do Foundry** para trazê-la; isso substitui as configurações exibidas, inclusive alterações não salvas.

Agentes de voz podem ser **suspensos e reativados** pela gestão, como os demais agentes. Uma sessão em andamento é encerrada quando o agente, ou um item dele, é suspenso.

### Modelos de voz e tarifas

Os agentes de voz usam modelos de **voz em tempo real** (família **gpt-realtime**, como `gpt-realtime-2.1` e `gpt-realtime-2.1-mini`, e **azure-realtime**). Eles são cadastrados em **Artefatos > Modelos**, como os demais modelos.

* São **modelos de serviço gerenciado**: não há *deployment* nem cota no Azure. A cobrança é pelo **uso de áudio**.
* Se o modelo de voz não aparecer na etapa **Agente e modelo**, um administrador precisa cadastrá-lo em **Modelos**.
* Na instalação automática, o passo **Habilitar conversas por voz** já cadastra o modelo.

### Custos

Como a voz é cobrada pelo Azure, o custo depende do **tempo de fala** e do **modelo** escolhido, e é contabilizado por resposta do agente.

| O que pesa no custo | Detalhe |
| --- | --- |
| **Áudio** | Fala do usuário (entrada) e fala do agente (saída), em tokens de áudio. É o maior componente. |
| **Texto** | Instruções, contexto e ferramentas também consomem tokens de texto. |
| **Contexto em cache** | Tem tarifa reduzida, quando aplicável. |
| **Transcrição** | A transcrição da fala do usuário para o histórico tem tarifa própria, conforme o modelo de transcrição escolhido. |

Valores de referência (preço público do Azure, por 1 milhão de tokens, em USD):

| Modelo | Áudio de entrada | Áudio de saída | Texto de entrada | Texto de saída |
| --- | --- | --- | --- | --- |
| `gpt-realtime-2.1` | 32 | 31 | 4 | 24 |
| `gpt-realtime-2.1-mini` | 11 | 26 | 0,66 | 2,64 |

Como referência, uma estimativa só de áudio (300 tokens de entrada e 600 de saída por minuto de conversa) fica em torno de **US$ 0,03 por minuto** com o `gpt-realtime-2.1` e **US$ 0,02 por minuto** com o `gpt-realtime-2.1-mini`.

{% hint style="warning" %}
**São estimativas.** Os valores acima seguem a tabela pública da Microsoft e **não substituem a fatura do Azure**. O custo real varia com o tamanho das instruções, o uso de ferramentas e o ritmo da conversa. Para acompanhar o gasto real, use o [Monitoramento](../../monitoramento.md) e defina um [Orçamento](../../orcamento.md).
{% endhint %}

Dicas para controlar o custo:

* Prefira o modelo **mini** para atendimentos simples e de alto volume.
* Mantenha **instruções curtas** e conecte apenas as ferramentas necessárias.
* Reduza a **duração máxima** e o **tempo de inatividade** das sessões (veja a seção a seguir).
* Defina **orçamentos** por agente, grupo ou organização.

### Limites das sessões de voz

Em **Artefatos > Agentes**, o botão **Sessões de voz** abre as **Configurações de sessões de voz**, onde o administrador define os limites das sessões de toda a organização. Informe um valor entre **1 e 60 minutos**.

<figure><img class="only-light" src="../../../.gitbook/assets/agente-voz-sessoes-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/agente-voz-sessoes-dark.png" alt=""><figcaption></figcaption></figure>

| Limite | Padrão | Descrição |
| --- | --- | --- |
| **Duração máxima da sessão** | 30 minutos | A sessão é encerrada ao atingir este tempo. |
| **Tempo limite de inatividade** | 5 minutos | A sessão é encerrada se ninguém falar. O tempo do agente respondendo ou executando uma ferramenta **não conta** como inatividade. |

A inatividade não pode ser maior que a duração máxima. Além desses limites, a sessão também é encerrada quando:

* o **orçamento** disponível se esgota;
* o **acesso** do usuário ao agente é revogado, ou a licença deixa de ser válida;
* o agente ou um item dele é **suspenso**, ou um componente da versão é removido;
* o usuário **encerra**, sai do painel de voz ou a conexão é interrompida.

### Monitoramento e orçamento

Em **Monitoramento**, o custo e as requisições de voz aparecem **separados do texto**:

* **Total de Perguntas:** mostra a contagem de perguntas de texto e, abaixo, **+ N respostas de voz**.
* **Custo Médio / Pergunta:** considera **somente conversas de texto**.
* **Custo Total:** detalha **Texto** e **Voz** (por exemplo, "Texto US$ 12,21 · Voz US$ 0,01").
* Nas tabelas de uso, as linhas de agentes, usuários e modelos que tiveram voz trazem uma linha extra **Voz** com o valor correspondente.

O consumo de voz também entra nos [Orçamentos](../../orcamento.md), que são verificados durante a conversa.

<figure><img class="only-light" src="../../../.gitbook/assets/agente-voz-monitoramento-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/agente-voz-monitoramento-dark.png" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Consumo não conciliado.** Enquanto a Microsoft não confirma que o relatório de uso de áudio está completo, a sessão acumula os componentes que o serviço informou e marca o consumo como **não conciliado**. Nada é estimado nem lançado como zero. Em caso de divergência, a **fatura do Azure** é a referência.
{% endhint %}

### Boas práticas

* Escreva instruções para **conversa falada**: frases curtas, uma pergunta por vez, confirmação de nomes e números.
* Peça que o agente **confirme antes de ações com consequências** e que nunca diga que concluiu algo antes de a ferramenta responder.
* Escolha a voz **ouvindo as amostras** e o idioma que os seus usuários realmente falam.
* **Teste** o agente com o microfone e o navegador que os usuários vão usar.
* Habilite só os **conectores** necessários e prefira toolboxes para integrações como busca na web.
* Defina **limites de sessão** e **orçamento** antes de liberar para muitos usuários.

### Limitações

* Não há gravação nem reprodução de **áudio**; o histórico é somente em texto.
* Cada usuário pode ter **uma sessão de voz ativa por vez** na organização.
* Uma conexão interrompida **não é retomada**: o usuário inicia uma nova sessão, com contexto novo.
* Voz exige **HTTPS** e um navegador com microfone e AudioWorklet.
* Conectores que dependem da identidade do usuário (consentimento, envio do e-mail) não funcionam na voz.

Para ver como o usuário final conversa com o agente, consulte [Conversas por Voz](../../../portal-do-usuario/conversas-por-voz.md).

### Precisa de ajuda?

{% hint style="info" %}
<mark style="color:$primary;">Se tiver dúvidas sobre agentes de voz, modelos, custo ou limites de sessão, entre em contato com o suporte do Power Omni.</mark>
{% endhint %}
