> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Testes de Agentes

Os testes de agentes permitem verificar respostas conversacionais, uso de ferramentas e resultados completos com múltiplos turnos antes da implantação. Crie testes do zero ou a partir de conversas existentes e execute-os pelo painel, CLI ou API.

## Guia em Vídeo

## Visão geral

O framework inclui três tipos de teste complementares:

* **Teste de Simulação** — Executa conversas completas com múltiplos turnos e um usuário simulado
* **Teste de Próxima Resposta (Cenário)** — Valida a próxima resposta do agente com base em critérios de sucesso
* **Teste de Chamada de Ferramenta** — Garante que o agente chame a ferramenta certa com os parâmetros corretos

### Quando usar cada teste

| Tipo de teste                  | Use quando precisar de                                                                     |
| ------------------------------ | ------------------------------------------------------------------------------------------ |
| **Simulação**                  | Verificar se uma conversa completa alcança um resultado definido                           |
| **Próxima Resposta (Cenário)** | Verificar se a próxima mensagem do agente atende a critérios de qualidade, tom ou política |
| **Chamada de Ferramenta**      | Verificar se o agente chama uma ferramenta específica com os parâmetros esperados          |

## Como criar testes a partir de conversas

Transforme conversas reais em casos de teste ao identificar uma interação em que o agente teve um desempenho abaixo do esperado.

![Como criar um teste a partir de uma conversa](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/7b0762965b7edb46ed6b693c126c00e9aa3e7c98dae7aa89a981b5465b949750/assets/images/conversational-ai/agent-test-from-conv.gif)

1. Abra a conversa no histórico de chamadas
2. Clique em **Criar teste a partir desta conversa**
3. Revise o contexto preenchido automaticamente e defina o comportamento esperado
4. Adicione o teste à sua suíte para detectar falhas semelhantes depois

## Teste de Simulação

O teste de simulação avalia seu agente ao longo de uma conversa completa com múltiplos turnos e um usuário de IA simulado. Diferentemente dos testes de Próxima Resposta, esse tipo verifica se a interação completa alcança o resultado definido.

### Como criar um Teste de Simulação

![Interface de criação de teste de simulação](/docs/_fern-img/ec2b27db7da62af2d82be756b2f830f0d0257a304d7c5ccb674c0a02ee8854ae.webp)

#### Defina o cenário

Descreva o contexto, a intenção e o comportamento do usuário em linguagem natural. O simulador usa esse
cenário para conduzir a conversa.

**Exemplo de cenário:**

> "Um turista que não fala inglês fluentemente está tentando fazer um pedido em um restaurante."

#### Defina a condição de sucesso

Defina o resultado que deve ser considerado uma aprovação. Esse prompt é usado para avaliar se a
conversa completa foi bem-sucedida.

**Exemplo de condição de sucesso:**

> "O agente confirmou os detalhes do pedido, lidou com perguntas de esclarecimento e concluiu o pedido sem mal-entendidos."

#### Defina o máximo de turnos

Escolha por quanto tempo a simulação pode ser executada antes de parar. Use um valor menor para verificações
focadas e um valor maior para workflows complexos.

* Mínimo: `1`
* Máximo: `50`
* Padrão: `5`

#### Execute e revise o resultado

Execute o teste e examine a transcrição da conversa gerada. Revise o resultado de aprovação/reprovação
com base na sua condição de sucesso e, então, ajuste seu prompt, suas ferramentas ou a configuração do agente.

### Configuração opcional

Você pode refinar o comportamento da simulação no painel de configuração do teste:

* **Ambiente**: Selecione o ambiente a ser testado quando seu agente tiver vários ambientes configurados. Se apenas um ambiente estiver disponível, esse seletor ficará oculto.
* **Histórico de chat**: Comece com uma conversa parcial em vez de um estado em branco. Isso é útil para testar conversas em andamento e comportamentos de recuperação.
* **Variáveis dinâmicas**: Insira valores específicos do teste nas variáveis do seu agente (por exemplo, nomes de usuários ou IDs de pedidos) sem alterar a configuração base do agente.

### Simulação de ferramentas

Os testes de simulação aceitam simulação de ferramentas para que seu agente possa receber respostas controladas durante uma execução, em vez de chamar sistemas ativos.

#### Estratégia de simulação

* **Não simular nenhuma**: Nenhuma ferramenta é simulada.
* **Simular todas as ferramentas**: Todas as ferramentas que podem ser simuladas retornam uma resposta simulada.
* **Simular ferramentas selecionadas**: Apenas as ferramentas que você escolher explicitamente são simuladas.

Ferramentas de sistema e ferramentas de workflow nunca são simuladas.

#### Comportamento de fallback

Se uma ferramenta simulada for chamada e nenhuma resposta simulada correspondente for encontrada, escolha um destes comportamentos:

* **Chamar ferramenta real**: Executa a chamada da ferramenta real.
* **Finalizar com erro**: Retorna uma resposta de erro da ferramenta em vez de chamar a ferramenta real.

A configuração de fallback aparece apenas quando pelo menos uma ferramenta é simulada.

## Teste de Próxima Resposta (Cenário)

O teste de Próxima Resposta (Cenário) avalia apenas a próxima mensagem do agente, não um resultado completo com múltiplos turnos. Forneça o histórico da conversa que antecede a resposta que você quer avaliar e, depois, avalie essa resposta com base em critérios de sucesso.

Para resultados completos com múltiplos turnos, use o [Teste de Simulação](#simulation-testing).

### Como criar um Teste de Próxima Resposta

![Interface de Teste de Próxima Resposta (Cenário)](/docs/_fern-img/62de63965584fd1b2368edfb204bd90495d03ba87fe137889a5f396859dc4dbc.webp)

#### Defina o histórico de chat

Forneça o histórico da conversa que antecede a resposta que você quer avaliar. Pode ser uma
única mensagem do usuário ou vários turnos de contexto.

**Exemplo de histórico de chat:**

```
User: "I'd like to cancel my subscription. I've been charged twice this month and I'm frustrated."
```

#### Defina os critérios de sucesso

Descreva em linguagem simples o que a resposta do agente deve alcançar. Seja específico sobre o
comportamento, tom e ações esperados.

**Exemplo de critérios de sucesso:**

* O agente deve reconhecer a frustração do cliente com empatia
* O agente deve se oferecer para investigar a cobrança duplicada
* O agente deve fornecer próximos passos claros para cancelamento ou resolução
* O agente deve manter um tom profissional e prestativo

#### Forneça exemplos

Apresente exemplos de sucesso e de falha para ajudar o avaliador a entender as nuances dos seus
critérios.

**Exemplo de sucesso:**

> "Entendo como cobranças duplicadas podem ser frustrantes. Vou verificar isso para você imediatamente. Vejo que houve realmente duas cobranças neste mês — vou processar o reembolso da cobrança duplicada agora. Você ainda gostaria de prosseguir com o cancelamento ou prefere continuar após a resolução disso?"

**Exemplo de falha:**

> "Você precisa entrar em contato com o departamento de cobrança para questões de reembolso. Sua assinatura será cancelada."

#### Execute o teste

Execute o teste. Um avaliador de LLM compara a próxima resposta do agente com seus critérios
e exemplos de sucesso para determinar o status de aprovação/reprovação.

## Teste de Chamada de Ferramenta

O teste de chamada de ferramenta verifica se seu agente usa as ferramentas corretamente e passa os parâmetros certos em situações específicas. Isso é fundamental para ações como transferências de chamadas, consultas de dados ou integrações externas.

### Como criar um Teste de Chamada de Ferramenta

![Interface de Teste de Chamada de Ferramenta](/docs/_fern-img/291c48ac70376efa1991014f7b3ff90eb9910c9adffe250f2bf521c707c5c755.webp)

#### Selecione a ferramenta

Escolha qual ferramenta você espera que o agente chame no cenário informado (por exemplo,
`transfer_to_number`, `end_call`, `lookup_order`).

#### Defina os parâmetros esperados

Especifique quais dados o agente deve passar para a ferramenta. Você tem três métodos de validação:

#### Métodos de validação

**Correspondência exata**\
O parâmetro deve corresponder exatamente ao valor especificado.

```
Transfer number: +447771117777
```

**Padrão Regex**
O parâmetro deve corresponder a um padrão específico.

```
Order ID: ^ORD-[0-9]{8}$
```

**Avaliação por LLM**
Uma LLM avalia se o parâmetro está semanticamente correto com base no contexto.

```
Message: "Should be a polite message mentioning the connection"
```

#### Configure variáveis dinâmicas

Ao testar em desenvolvimento, use valores de variáveis dinâmicas que correspondam aos valores reais
em produção. Exemplo: `{{ customer_name }}` ou `{{ order_id }}`

#### Execute e valide

Execute o teste para garantir que o agente chame a ferramenta correta com os parâmetros adequados.

### Casos de uso críticos

O teste de chamada de ferramenta é essencial para cenários de alto risco:

* **Transferências de emergência**: Garanta que emergências médicas sejam sempre encaminhadas para o número correto
* **Segurança de dados**: Verifique se informações confidenciais nunca são enviadas para ferramentas não autorizadas
* **Lógica de negócio**: Confirme que consultas de pedidos usam formatos e autenticação válidos

## Execução de testes

Escreva testes para comportamentos novos ou falhas conhecidas, execute-os enquanto ajusta prompts e configurações e, depois, salve-os quando forem aprovados.

#### Executar pelo painel

Acesse a aba Tests na interface do seu agente. Nela, você pode executar testes individuais, selecionar vários testes da sua biblioteca como um lote ou executar toda a sua suíte com **Run All Tests**.

![Execução de testes em um agente](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/b1becf589a1373a780dad1109fd25e0e910d7aa821b09b047133553b1895914b/assets/images/conversational-ai/testrun.gif)

#### Executar pela CLI

Integre testes ao seu pipeline de desenvolvimento:

```bash
elevenlabs agents test agent_7101k5zvyjhmfg983brhmhkd98n6
```

Isso permite:

* Testes automatizados a cada alteração no código
* Prevenção de regressões antes da implantação
* Comportamento consistente do agente em todos os ambientes

#### Executar pela API

Crie testes com [Criar teste](/docs/pt/api-reference/tests/create) e execute-os com [Executar testes no agente](/docs/pt/api-reference/tests/run-tests).

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

invocation = elevenlabs.conversational_ai.agents.run_tests(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    tests=[{"test_id": "<test-id>"}],
)

print(invocation)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const invocation = await elevenlabs.conversationalAi.agents.runTests("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  tests: [{ testId: "<test-id>" }],
});

console.log(invocation);
```

### Testes probabilísticos

As respostas do agente podem variar entre execuções. Uma única aprovação mostra que o agente *pode* ter sucesso; os testes probabilísticos mostram com que frequência ele *terá* sucesso ao executar o mesmo teste várias vezes e informar uma taxa de aprovação.

#### Executar um teste várias vezes

![Controle de execuções múltiplas em um teste que permite escolher quantas vezes executá-lo](/docs/_fern-img/15d5a18c384bc193de794bf8cd7bd5803b9543c8a98acac6ecb2f518b9fd1679.webp)

Ao acionar um teste pelo painel, use o controle de execuções múltiplas no botão de execução para escolher quantas vezes executá-lo (por exemplo, 3×, 5× ou 15×). Cada execução é independente: o agente recebe o mesmo histórico de chat, as mesmas variáveis dinâmicas e outras entradas, mas sua resposta é gerada novamente a cada vez.

A execução múltipla funciona para testes individuais, pastas e para a execução de toda a suíte de testes vinculada a um agente. Ela é compatível com os três tipos de teste — Simulação, Próxima Resposta (Cenário) e Chamada de Ferramenta — e costuma ser mais útil para testes de Simulação, em que a maior abrangência de uma conversa com múltiplos turnos torna a variação de respostas mais provável.

#### Taxas de aprovação e agrupamento de resultados

![Resultados de execuções múltiplas agrupados em categorias de aprovação e falha, com um selo de taxa de aprovação](/docs/_fern-img/17b73e8c8170162270519adad3c9d732dfabdafc820e47b4ab274ca5066fd7fc.webp)

Após a conclusão de uma execução múltipla, os resultados são resumidos como uma taxa de aprovação (por exemplo, **4/5 aprovados**) com um selo colorido:

* **Verde** — 100% aprovados
* **Âmbar** — pelo menos 80% aprovados
* **Vermelho** — menos de 80%

As execuções individuais são agrupadas por motivo de falha para que você possa ver *como* o agente falha, e não apenas *que* ele falha. Em vez de percorrer cinco transcrições separadas para identificar o que mudou, você vê grupos como *"Encaminhou corretamente para cobrança (4 execuções)"* e *"Inventou um número de suporte (1 execução)"*, cada um expansível para acessar as transcrições e a justificativa da avaliação.

#### Quando usar

* **Antes de lançar uma alteração** — Execute novamente os testes vinculados de forma probabilística para confirmar que a confiabilidade não caiu (por exemplo, de 95% para 60%).
* **Diagnóstico de comportamento instável** — Uma única falha pode ser ruído; uma falha em 1 de 5 execuções, com uma categoria de falha claramente identificada, é um problema reproduzível a ser corrigido.
* **Ajuste de prompts e ferramentas** — Faça ajustes na configuração e compare taxas de aprovação lado a lado, em vez de depender de execuções isoladas.

#### Execução probabilística pela API ou SDK

Passe `repeat_count` (entre `2` e `20`) na solicitação [run-tests](/docs/pt/api-reference/tests/run-tests) para executar cada teste essa quantidade de vezes. Definir `repeat_count` ativa automaticamente o agrupamento de falhas na resposta, portanto, a invocação retornada inclui o agrupamento por categoria e a taxa de aprovação que você veria no painel.

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

invocation = elevenlabs.conversational_ai.agents.run_tests(
    agent_id="<agent-id>",
    tests=[{"test_id": "<test-id>"}],
    repeat_count=5,
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const invocation = await elevenlabs.conversationalAi.agents.runTests(
  "<agent-id>",
  {
    tests: [{ testId: "<test-id>" }],
    repeatCount: 5,
  },
);
```

## Boas práticas

#### Avalie a consistência da persona do agente

Teste se seu agente mantém a personalidade, o tom e os limites comportamentais definidos em
diversos cenários de conversa e contextos emocionais.

#### Verifique raciocínios complexos com múltiplos turnos

Crie cenários que testem a capacidade do agente de manter o contexto, seguir lógica condicional
e lidar com transições de estado em conversas extensas.

#### Teste tentativas de injeção de prompt

Avalie como seu agente responde a tentativas de substituir suas instruções ou extrair informações
confidenciais do sistema por meio de entradas adversariais.

#### Avalie a resolução de intenções ambíguas

Teste com que eficácia seu agente esclarece solicitações vagas, lida com informações conflitantes e
conduz situações em que a intenção do usuário não está clara.

## Próximas etapas

* [Consulte a documentação da CLI](/docs/pt/eleven-agents/operate/cli) para configurar testes automatizados
* [Explore a configuração de ferramentas](/docs/pt/eleven-agents/customization/tools) para entender as ferramentas disponíveis
* [Leia o guia de prompting](/docs/pt/eleven-agents/best-practices/prompting-guide) para escrever prompts testáveis