# Versionamento de agente de IA: como publicar sem quebrar

Versionamento de agente de IA para quem entrega a clientes: edite em rascunho, teste antes de publicar, confira o diff e faça rollback sem parar canais.

Autor: Tiago Morelli (Fundador)
Publicado em 2026-11-19 · Tags: versioning, governanca, agencia, vibe-agent, crm

---

Quem entrega agentes para clientes trava na mesma hora: o atendimento já está rodando no WhatsApp ou no Instagram, o cliente pede um ajuste de regra na sexta-feira, e você precisa fazer **versionamento de agente de IA** sem derrubar o número que já atende. Quando a plataforma não separa rascunho de produção, qualquer edição vira roleta-russa em cima de conversas reais.

Na prática, quem pesquisa **versionamento de prompt** ou **como testar um agente de IA** antes de colocar no ar quer um fluxo previsível para mudar comportamento, validar ferramentas em ambiente privado, publicar com segurança e voltar atrás em segundos se uma resposta sair errada. Este guia mostra como estruturar esse ciclo na operação com clientes, o que entra no controle de versão e o que continua sendo dado vivo fora do deploy.

Se você quer o passo a passo específico de uma mudança no atendimento de WhatsApp sem Git nem fluxo colado, veja [como atualizar um agente de IA no WhatsApp](/blog/como-atualizar-agente-de-ia-whatsapp/). Para montar baterias de cenários com usuário simulado antes de entregar um projeto, leia [testes automatizados de agente](/blog/testes-automatizados-de-agente/) — aqui o foco é o **ciclo completo de draft, teste, publicação e rollback para quem opera clientes**.

## Versionamento de agente de IA, em resumo

**Versionamento de agente de IA** é o controle de ciclo entre rascunho e produção (`draft → test → deploy → rollback`) que permite alterar instruções, ferramentas e integrações sem interromper os canais ativos nem apagar o histórico do CRM. Na Zaia Endless, o **Versioning** é nativo no workspace: cobre **agents, squads, tools, MCPs, components e voices**, enquanto **Knowledge**, **Tables**, canais conectados e tickets permanecem como dados e filas operacionais fora do versionamento. A plataforma começa no Console a partir de R$125 por slot/mês no anual, com teste de 7 dias sem cartão.

## 1. Por que editar em produção quebra a confiança do cliente

Logo no início da operação, muita gente edita o prompt direto no ar e testa mandando um "oi" pelo próprio celular. Com dois, cinco ou dez clientes em produção, esse hábito gera três problemas que corroem a renovação da mensalidade:

- **Regressão silenciosa:** você ajusta uma regra de agendamento no prompt e, sem perceber, o agente para de abrir ticket quando o usuário pede um atendente humano.
- **Mistura entre regra e dado:** quando preço, horário e tabela de serviços ficam colados no texto do prompt, toda atualização semanal exige um novo deploy do agente inteiro.
- **Sem caminho de volta:** se uma mudança piora o atendimento no fim de semana, você perde horas tentando lembrar qual era o texto anterior do prompt ou qual tool estava ligada antes da alteração.

Quando sua agência separa rascunho, validação interna e publicação versionada, atualizar o agente deixa de ser risco e vira rotina cobrável dentro da mensalidade recorrente. Para entender como empacotar essa operação contínua, veja [como revender agente de IA](/blog/como-revender-agente-de-ia/).

## 2. O que entra no versionamento (e o que fica fora)

Um erro comum ao planejar **versionamento de prompt** é achar que tudo no workspace volta no tempo quando você faz rollback. Na arquitetura da Zaia Endless, comportamento versionado e dado operacional têm papéis distintos:

| Camada do workspace | Entra no Versioning? | O que acontece no deploy e no rollback |
|---|---|---|
| **Agents e Squads** | Sim | Prompt, role, temperature, planning, reasoning e hierarquia mudam apenas no Draft e só vão ao ar após Publish |
| **Tools, MCPs, Components e Voices** | Sim | Vínculos de ferramentas, +60 integrações nativas (MCPs), blocos reutilizáveis (`@`) e presets de voz seguem a versão publicada |
| **Knowledge e Tables** | Não (na interface) | Bases de conhecimento e tabelas nativas ficam sempre ativas; atualizar um documento muda a resposta sem novo deploy |
| **Canais, Conversas, Tickets e Tags** | Não | WhatsApp Official, Waha, Instagram, Widget, Telegram, API (**alpha**, sujeita a mudanças) e fila do CRM continuam no ar sem perda de histórico |

Essa separação evita que um rollback de prompt apague atendimentos em andamento no CRM ou desfaça uma atualização legítima na [base de conhecimento do agente](/blog/base-de-conhecimento-agente-de-ia/). A regra prática para quem opera clientes é direta: **comportamento e ferramentas ficam no agente versionado; catálogo, preços e FAQ ficam em Knowledge e Tables**.

## 3. Como testar um agente de IA antes de publicar para o cliente

Testar antes do deploy não precisa de ambiente paralelo em servidor externo nem de planilhas copiando respostas à mão. Na Zaia, o ciclo de validação acontece dentro do próprio **Draft** em duas camadas complementares:

### 3.1. Inspeção ao vivo no Internal Chat

O [Internal Chat](/docs/agents/agent-settings/internal-chat/) roda no **Agent Builder** usando exatamente o mesmo modelo, provider (inclusive com **BYOK** nos planos compatíveis), tools e MCPs configurados no rascunho. Antes de publicar qualquer ajuste para um cliente, valide três casos mínimos:

1. **Fluxo feliz do job:** confirme se o agente consulta Knowledge, Tables ou o MCP certo (por exemplo, Google Calendar ou Gmail) com os parâmetros esperados.
2. **Inspeção da execução:** abra a linha do tempo da resposta para conferir entradas e saídas em JSON de cada tool chamada, em vez de olhar apenas para a frase final.
3. **Caso de transbordo:** simule um pedido explícito de pessoa ou reclamação para garantir que a criação de ticket e o [handoff humano no WhatsApp](/blog/handoff-humano-whatsapp/) continuam funcionando.

Vale observar dois pontos operacionais: usar o Internal Chat consome créditos de execução normalmente (como uma conversa real), e a publicação de novas versões do mesmo agente **não consome um slot extra** do seu workspace.

### 3.2. Sessões de teste automatizado quando o projeto cresce

Depois de corrigir um erro no prompt no **Vibe Agent** ou no Agent Builder, você também pode abrir o painel de [testes automatizados de agente](/blog/testes-automatizados-de-agente/) direto pelo Internal Chat. Ele executa cenários salvos com um usuário simulado (com limite de até cinco mensagens por cenário) para comparar respostas antes do deploy — sem substituir o acompanhamento das conversas reais no CRM.

## 4. Ciclo passo a passo: draft, diff, deploy e rollback

Na entrega para clientes, padronize uma sequência curta de cinco passos para qualquer alteração de comportamento — seja via [Vibe Agent](/blog/como-criar-agentes-com-vibe-agent/) ou no modo avançado (**Agent Builder**):

1. **Edite no Draft isolado:** aplique uma mudança clara por vez (tom, regra de qualificação, parâmetro de tool ou componente `@`). O agente publicado continua atendendo os clientes finais sem interrupção.
2. **Valide no Internal Chat:** teste os cenários principais e confira no painel de inspeção se nenhuma tool deixou de ser chamada.
3. **Revise o Diff antes do Deploy:** ao clicar em **Publish**, confira o que foi adicionado, alterado ou removido para ter certeza de que nenhuma integração ou agente do squad foi desconectado por engano.
4. **Monitore as Executions pós-publicação:** acompanhe na aba **Executions** se as primeiras execuções reais aparecem como `completed` (e identifique rápido qualquer status `failed` ou `cancelled`), além de observar a fila de **Tickets** no [CRM nativo](/blog/agente-de-ia-com-crm/).
5. **Acione o Rollback se algo fugir do esperado:** em **Version History**, escolha a versão anterior validada e selecione **Edit this version** para trazê-la de volta ao Draft, revise e publique novamente.

Para consultar o detalhe técnico de telas e estados na plataforma, veja a documentação de [Visão Geral do Versioning](/docs/versioning/versioning-overview/).

## 5. Governança em equipe e operação multi-cliente

Quando a agência passa a operar vários workspaces no **Console**, o controle de versão se conecta com quem pode mexer no quê:

- **Separação de papéis em Members:** perfis `owner`, `admin` e `member` constroem e publicam no Studio, enquanto quem tem perfil `ops` atende apenas a fila de tickets no CRM sem visualizar nem alterar o Builder do agente.
- **Auditoria de alterações:** o histórico de mudanças do workspace mostra quem criou, atualizou ou publicou cada recurso, reduzindo atrito quando mais de uma pessoa da agência dá manutenção na conta.
- **Módulos em evolução sinalizados:** se a operação do cliente também envolve fluxos visuais (**Workflows**), métricas internas (**Analytics**), chat operacional (**Workers**) ou chaves externas (**API Keys**), alinhe na proposta que esses recursos estão em **beta**, assim como a **Developer Platform API** está em **alpha**, sujeita a mudanças.

Na Zaia, os planos no Console funcionam por **slots** (cada slot inclui 1 agente, 5 mil execuções, R$25 de crédito de IA e 12 mensagens do Vibe Agent por mês): o **teste de 7 dias sem cartão** libera 1 agente, R$15 de crédito de IA e 5 chamadas do Vibe Agent; depois, os planos começam **a partir de R$125 por slot/mês no anual** (ou **R$250 por slot/mês no mensal**, com condição especial de **1 slot por R$150/mês no mensal** para quem contrata durante o teste). Para agências com carteira maior que querem marca e domínio próprios, o **White Label** vem incluso nos planos **Partner** no anual (**Partner 10** por R$990/mês e **Partner 25** por R$2.062/mês). Confira a grade na página de [planos da Zaia](/planos/).

Como referência comercial na proposta ao cliente final, a calculadora do Programa de Aceleração usa agentes que valem **a partir de R$1.500/mês** — exemplo de precificação de serviço recorrente, e não promessa de receita. Para selecionar os primeiros contratos, leia [onde vender agente de IA](/blog/onde-vender-agente-de-ia/) e [chatbot para revender](/blog/chatbot-para-revender/).

## Perguntas frequentes

### O rollback volta também a base de conhecimento (Knowledge) e as Tables?

Não. Na Zaia Endless, o **Versioning** cobre agents, squads, tools, MCPs, components e voices. **Knowledge** e **Tables** ficam fora do versionamento na interface, assim como canais conectados, histórico de conversas e tickets — portanto, o rollback restaura o comportamento do agente sem apagar dados ou atendimentos no CRM.

### Publicar uma nova versão do agente consome mais um slot no meu plano?

Não. Os slots do Console limitam a quantidade de agentes distintos criados e o volume mensal de recursos, não o número de versões publicadas. Você pode editar no Draft, testar no Internal Chat, publicar e reverter versões do mesmo agente sem gastar slots extras.

### Qual a diferença entre Versioning e testes automatizados de agente?

O **Versioning** controla o ciclo entre rascunho, publicação e rollback (`draft → test → deploy → rollback`) para proteger a operação em produção. Já os **testes automatizados** são uma ferramenta de validação dentro do Internal Chat em que um usuário simulado roda cenários contra o seu agente antes de você apertar Publish.

### Preciso usar Git ou n8n para ter versionamento de prompt e agente?

Não. Embora times de engenharia possam versionar código externo no Git, na Zaia o versionamento de prompt, tools, MCPs, components, voices e squads é nativo no workspace, com histórico de versões publicadas e rollback sem precisar manter servidor ou pipeline separado.

## Como começar

Crie seu primeiro agente no **Vibe Agent**, separe regras fixas no prompt do conteúdo dinâmico em Knowledge e rode pelo menos três cenários no **Internal Chat** antes de publicar no canal do cliente. Você pode validar todo o ciclo de rascunho, teste, deploy e rollback nos 7 dias de teste sem cartão.

[Iniciar teste de 7 dias](https://endless.zaia.app/platform/authenticate) <!-- pragma: allowlist secret --> — sem cartão. Planos a partir de R$125 por slot/mês no anual.