---
title: Playground ao vivo
description: Rode o Agent na hora com uma entrada, acompanhe a trajetória em tempo real e salve o resultado como caso de teste — em modo sandbox.
---

# Playground ao vivo

O [Eval](/guia/agents/eval) pontua conversas que já aconteceram. O Playground resolve o outro lado: rodar o Agent **agora**, com uma entrada que você digitar, e ver o que ele faz acontecendo em tempo real — sem precisar de uma conversa real de cliente pra testar um cenário novo.

<Cuidado>

O Playground roda em **modo sandbox** (um ambiente de teste isolado): ferramentas de plataforma/CRM (ações que mexeriam em dados reais — criar contato, atualizar pipeline, enviar mensagem para um cliente de verdade, etc.) **não disparam efeitos reais** durante essa execução. É seguro testar qualquer entrada.

</Cuidado>

## Como funciona

1. Digite uma entrada (texto livre) e, opcionalmente, escolha a versão do Agent a testar (em branco, roda a versão atual).
2. Ao disparar, a plataforma inicia uma execução isolada do Agent e devolve um identificador dessa execução.
3. A tela conecta em um canal de atualizações em tempo real dessa execução específica e mostra o que está acontecendo ao vivo: mensagens do Agent, chamadas de ferramenta, resultados de ferramenta e guardrails acionados, nessa ordem.
4. Quando a execução termina (resposta final ou erro), a trajetória para de crescer e o botão de salvar como caso de teste fica disponível.

## Disparando uma execução (para times técnicos)

A execução também pode ser disparada por API, para quem for integrar o Playground em outra ferramenta ou automação:

```bash
curl -X POST https://sua-instancia/api/ai-agents/{agent}/playground/run \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
        "input": "Qual o prazo pra contestar uma multa de trânsito?",
        "agent_version_id": 3
      }'
```

| Campo | Obrigatório | Descrição |
|-------|-------------|-----------|
| `input` | Um dos dois | Texto livre da mensagem de entrada. |
| `session_input` | Um dos dois | Alternativa a `input` para cenários que precisem de uma entrada estruturada. |
| `agent_version_id` | Não | Número da versão do Agent a rodar. Em branco, roda a versão atual (rascunho). |

A resposta devolve o identificador da execução (`run_id`):

```json
{ "data": { "run_id": "01J0000000000000000000000D", "status": "queued" } }
```

**Permissão requerida:** gerenciar avaliações do Agent.

## Acompanhando a trajetória em tempo real

Com o identificador da execução em mãos, é possível se conectar a um canal de atualizações em tempo real (tecnicamente, um stream de eventos) para acompanhar o que está acontecendo. Cada evento que chega identifica o tipo de atividade:

| Tipo de evento | O que representa |
|--------|-------------------|
| Mensagem do Agent | Uma mensagem de texto do Agent (ou de um sub-agent). |
| Chamada de ferramenta | O Agent chamou uma ferramenta — nome e argumentos. |
| Resultado de ferramenta | O resultado que voltou dessa ferramenta. |
| Guardrail acionado | Um guardrail agiu sobre a entrada ou a resposta. |
| Erro | A execução falhou. |

Os eventos chegam em ordem. O último evento da execução sinaliza que ela terminou — é o sinal que a tela usa para parar o "Rodando…" e liberar o botão de salvar.

**Permissão requerida:** visualizar avaliações do Agent.

## Salvando o run como caso de teste

Depois que a execução termina, o botão **Salvar como caso de teste** grava um retrato dessa execução (a mesma lógica de "promover a caso" usada no Eval) como um novo caso de teste, direto em um conjunto de testes existente.

Isso é o inverso da ação de promover uma conversa real a caso de teste (ver [Avaliação de Agents](/guia/agents/eval#promovendo-uma-run-a-caso-de-teste)): aqui o conjunto de testes já foi escolhido antes, e a execução do playground vira imediatamente um caso que passa a ser verificado toda vez que você rodar o conjunto de testes.

**Permissão requerida:** gerenciar avaliações do Agent.

## Saiba mais

- [Avaliação de Agents (Eval)](/guia/agents/eval) — critérios de pontuação e como montar um conjunto de testes
- [Otimização de instruções (Optimizer)](/guia/agents/otimizacao) — reescrever a instrução automaticamente com base no Eval