Mil clientes falsos antes do lançamento

O que é e porque importa

Antes de um lançamento, normalmente vais às cegas. O preço está certo? A frase no topo da página percebe-se? O anúncio desperta curiosidade ou irrita? Descobres quando chegam os primeiros clientes reais, e nessa altura já gastaste tempo e dinheiro.

O MiroFish é um motor de simulação com muitos agentes, gratuito e open source no GitHub, com mais de 80.000 estrelas. Um agente, aqui, é uma personagem movida por um modelo de IA: tem uma idade, um carácter, uma memória e as suas próprias ideias. Tu dás-lhe um material de partida, a que o projeto chama semente: a página do teu produto, a tabela de preços, um anúncio, uma notícia. Ele constrói com isso um pequeno mundo, enche-o de agentes e deixa-os falar entre si em duas redes sociais simuladas, uma de feed como o Twitter e outra de comunidades como o Reddit. No fim escreve um relatório, e podes fazer perguntas a cada um deles.

É para quem está prestes a lançar algo sozinho. Não é uma bola de cristal, é um ensaio geral: mostra-te onde a tua página pode não agradar, e porquê, antes que um cliente real o descubra.

1. O que precisas

• Git, Node.js, Python e uv, um gestor de pacotes para Python. As versões certas estão na tabela Prerequisites do README: para o Python há também um limite máximo, por isso a mais recente pode não funcionar. Ou só Docker.
• Uma chave API de um modelo de linguagem que use o formato do SDK da OpenAI. O README recomenda o modelo qwen-plus na plataforma Bailian da Alibaba, mas serve qualquer serviço compatível.
• Uma chave da Zep Cloud, o serviço que guarda a memória do mundo simulado em forma de grafo, ou seja, um mapa de pessoas, coisas e ligações. Segundo o README, a quota gratuita mensal chega para um uso simples. O MiroFish só se liga à Zep Cloud.
• Os textos para ele ler, em ficheiros PDF, Markdown ou TXT.

Uma coisa a saber desde já: o programa corre no teu computador, mas o que carregas sai para o serviço do modelo e para a Zep Cloud. Não lhe dês documentos confidenciais nem dados dos teus clientes.

2. Instala-o e arranca-o

1. Descarrega o projeto com git clone https://github.com/666ghj/MiroFish e entra na pasta.
2. Copia o ficheiro de exemplo com cp .env.example .env. O ficheiro .env guarda as chaves e fica só no teu computador.
3. Abre o .env e preenche LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME e ZEP_API_KEY. No fim há três linhas LLM_BOOST, para um segundo modelo mais rápido e opcional: se não o usares, apaga-as. Quem o diz é o comentário do ficheiro, que está em chinês.
4. Instala tudo com npm run setup:all.
5. Arranca com npm run dev. A interface está em http://localhost:3000 e o backend responde em http://localhost:5001.

Com Docker, depois do passo 3 basta docker compose up -d: lê o mesmo .env e usa as mesmas portas. A interface abre em chinês: no menu de idiomas escolhe English. Só há chinês e inglês, e o idioma que escolhes aí é também o do relatório e das respostas dos agentes.

O Claude Code pode fazer quase todo o trabalho. A única coisa que faço eu são as chaves: escrevo-as à mão no .env e nunca as colo no chat.

Instala o MiroFish (https://github.com/666ghj/MiroFish) numa pasta nova, fora dos meus projetos.
Lê o README e o ficheiro .env.example, e verifica se o Git, o Node.js, o Python e o uv estão nas versões pedidas. Se faltar alguma coisa, diz-me como a instalar antes de o fazeres.
Cria o .env a partir do ficheiro de exemplo, tira as três linhas LLM_BOOST e deixa as chaves vazias: preencho-as eu.
Quando te disser que acabei, corre npm run setup:all e depois npm run dev, e diz-me se o frontend e o backend arrancam sem erros.

3. Prepara a semente do teu lançamento

O resultado depende do que lhe dás a ler. Para ensaiar um lançamento preparo um único ficheiro Markdown com:

• O texto da landing page de cima a baixo, tal como é.
• Os preços: os planos, o que inclui cada um, o período de teste gratuito se houver.
• O anúncio que queres pôr a circular: o texto e o que se vê na imagem ou no vídeo.
• Duas linhas sobre quem achas que são os teus clientes. Ajudam a criar agentes credíveis.

Lê a minha landing page (<caminho ou endereço>), a tabela de preços (<caminho>) e o texto do anúncio (<texto>).
Escreve um ficheiro semente-lancamento.md para o MiroFish: o texto da página tal como está, os preços numa tabela, o anúncio e duas linhas sobre os clientes em que penso (<quem são>).
Não melhores nada nem acrescentes promessas que a página não faz: tem de ser a versão que eu publicaria amanhã.

Depois há o segundo campo, o pedido: o que queres saber, em palavras normais. Quanto mais preciso for, mais o relatório responde à tua pergunta e não a outra. O meu, para um lançamento:

Simula as reações de <freelancers e pequenas equipas> à página e ao anúncio nos primeiros dias depois do lançamento. Quero saber: o que não se percebe, que objeções põem ao preço, quem o partilharia e porquê, e que frase da página é mais citada, para o bem ou para o mal.

4. Corre a simulação, com poucas rondas

Carregas o ficheiro, escreves o pedido e carregas em Start Engine. A partir daí o MiroFish passa por cinco fases, que vês uma a seguir à outra:

1. Graph Build: lê o documento e constrói o grafo na Zep.
2. Env Setup: cria os agentes, cada um com idade, país, carácter, uma biografia e memórias tiradas da semente. É aqui também que decides quantas rondas fazer.
3. Run Simulation: as duas redes correm ao mesmo tempo. Cada ronda é um bocado de tempo simulado em que os agentes publicam, comentam, dão like e se seguem.
4. Report Generation: um agente dedicado, o ReportAgent, reconstrói o que aconteceu e escreve o relatório, secção a secção.
5. Deep Interaction: conversas com o ReportAgent ou com qualquer agente do mundo, ou mandas a mesma pergunta a um grupo.

O dinheiro joga-se nas rondas. O MiroFish propõe um número sozinho, mas consome bastante: o README diz para experimentar primeiro com menos de 40 rondas, e o próprio ecrã recomenda passar para Custom da primeira vez. No Env Setup ativa Custom e baixa o cursor, que começa nos 10. Faz um teste pequeno, confirma que tudo funciona e que o relatório faz sentido, e só depois aumenta.

5. Lê o relatório e interroga os clientes falsos

Leio o relatório como leio os comentários debaixo de um post: não conto votos, procuro as frases que se repetem. Três perguntas: o que não se percebeu? Que objeção aparece mais vezes? Quem defendeu o produto, e com que palavras?

Depois, a parte mais útil, Deep Interaction. Escolhe um agente que criticou o preço e pergunta-lhe porquê, e o que o faria mudar de ideias. Com Send survey selecionas um grupo de agentes e mandas a todos a mesma pergunta. As minhas perguntas de sempre:

Viste a página: numa frase, o que faz este produto?
O que te fez duvidar mais?
A que preço o experimentavas, e o que esperavas ter?
O que dirias a um amigo que te pergunta se vale a pena?

Atenção: a simulação e as entrevistas só funcionam enquanto o ambiente está ligado. No histórico podes reabrir o grafo, o ambiente e o relatório, mas não a simulação nem as entrevistas. Faz as perguntas antes de fechar.

O relatório fica também num ficheiro, full_report.md, dentro de backend/uploads/reports. Aí o Claude Code pode lê-lo, ao lado da tua página:

Lê o último relatório do MiroFish (o ficheiro full_report.md mais recente em backend/uploads/reports) e a minha landing page.
Faz a lista das objeções que aparecem mais vezes, cada uma com a frase da página que a provoca.
Para cada uma propõe uma alteração à página. Separa o que parece um problema real do que pode ser só uma ideia da simulação: isso verifico eu com pessoas reais.

6. Os limites, ditos com clareza

• É um ensaio geral, não uma previsão. Os agentes são modelos de linguagem a fazer um papel: o relatório dá-te hipóteses para verificar com pessoas reais, não números de vendas.
• Custa. O programa é gratuito, mas cada ronda são muitas chamadas ao modelo, que o teu fornecedor cobra conforme o uso. Mais agentes e mais rondas, mais gastas. A Zep Cloud paga-se se passares da quota gratuita.
• Os teus textos saem do computador. Existe um fork, o MiroFish-Offline (github.com/nikmcfly/MiroFish-Offline), que substitui a Zep Cloud pelo Neo4j e o modelo na nuvem pelo Ollama, para tudo ficar local. Não é da equipa original, e o README dele pede uma máquina potente: pelo menos 16 GB de RAM, e recomenda uma placa gráfica.
• A licença é a AGPL-3.0. Usá-lo para ti é livre. Mas se alterares o código e deixares outros usar a tua versão através da rede, por exemplo como serviço online, tens de oferecer a esses utilizadores o código-fonte da tua versão alterada.

Os erros mais comuns

• Correr a primeira simulação com as rondas que o MiroFish propõe. Ativa Custom e começa baixo.
• Escrever um pedido vago, tipo «o que acham?». Pede coisas concretas: o que não se percebe, as objeções ao preço, quem o partilha.
• Tomar o relatório como uma previsão e refazer tudo. O que sai da simulação verifica-se com algumas pessoas reais.
• Fechar o ambiente antes de fazer as perguntas aos agentes.

Checklist

• No .env as quatro entradas do modelo e da Zep, sem linhas LLM_BOOST se não as usar
• Um ficheiro semente com a página, os preços e o anúncio tal como os vou publicar
• Um pedido preciso, com as perguntas que contam para o lançamento
• Primeiro teste em Custom, com poucas rondas
• Perguntas a pelo menos um crítico e um defensor antes de fechar o ambiente
• As principais objeções anotadas, para verificar com pessoas reais

Perguntas frequentes