Construa seu app conversando com o Harness

O Harness é um assistente de programação com inteligência artificial que mora dentro do painel da FlexPage. Você escreve em português o que quer — “crie uma página para a minha barbearia” — e ele cria e altera os arquivos do seu site para fazer aquilo acontecer.

A palavra harness significa “arreio” em inglês: aquilo que se coloca num cavalo para ele puxar a carroça na direção certa. É exatamente a ideia: a IA tem muita força, e o Harness é o arreio que a mantém trabalhando só no seu site, com regras e pedindo sua permissão.

O que ele consegue fazer

• Criar sites, páginas e apps completos (telas + a parte que roda no servidor).
• Alterar e consertar o que já existe, inclusive a partir de um print do erro.
• Criar rotinas que rodam sozinhas (ex.: “todo dia às 8h, faça tal coisa”).
• Ler planilhas, documentos Word, PDFs e imagens que você enviar.
• Criar agentes de IA para atender os seus clientes.

O que ele não faz (e por quê)

• Não mexe em sites de outras pessoas. Ele só enxerga as pastas do domínio que você selecionou.
• Não grava nada sem você ver, no modo recomendado. Cada alteração aparece num cartão para você permitir ou recusar.
• Não adivinha senhas nem dados de terceiros. Quando precisa de algo (a chave de um serviço, o número do WhatsApp), ele pergunta.
• Não substitui o seu olhar. Ele erra às vezes — por isso você testa o resultado, como faria com um funcionário novo.

Todo site na FlexPage tem quatro pastas. Entender cada uma resolve metade das dúvidas:

Domínio / URL

O endereço do site (ex.: barbearianavalha.com.br). No painel você escolhe em Selecionar URL em qual site vai trabalhar.

Sessão

Uma conversa com o Harness sobre um assunto. Fica guardada; você pode fechar e continuar outro dia.

Tipo de sessão

O foco da conversa: Site, App, Webhook, Rotina, Projeto ou Livre. Define o que o Harness lê primeiro.

Ferramenta

Uma ação que o Harness usa: read (ler arquivo), write (criar), edit (alterar), list (ver pasta). Aparecem como cartões na conversa.

Aprovação

O momento em que você permite ou recusa uma alteração.

Backend / API

A parte do app que roda no servidor (pasta script/). As páginas “pedem” coisas a ela, como “quais horários estão livres?”.

Frontend

As telas que o cliente vê (pasta www/).

Webhook

Um endereço que outro sistema chama para avisar algo (ex.: “o pagamento caiu”).

Token

A “moeda” da IA: pedaços de texto. Tudo que a IA lê e escreve é contado em tokens — é o que gera custo.

Contexto

A memória de curto prazo da sessão. Quando enche, o Harness fica lento e caro — aí você compacta.

Skill

Um manual que o Harness consulta antes de trabalhar (ex.: como fazer login com segurança).

Agente

Uma IA configurada para trabalhar dentro do seu app, atendendo seus clientes.

Automação

Uma mensagem que o Harness recebe sozinho num horário marcado ou quando outro sistema chama.

1. Entre no painel admin.flexpage.io.
2. Em Selecionar URL, escolha o site (ex.: barbearianavalha.com.br).
3. No menu lateral, clique em 🛠️ Harness.

• 1Nova: começa uma conversa nova.
• 2Ferramentas: Skills (manuais), Automações (horários), Projetos (arquivos para baixar) e Agentes (IA no app).
• 3Lista de sessões: clique para reabrir uma conversa antiga.
• 4Barra da sessão: quanto da memória já foi usada, desfazer alterações, compactar, parar o trabalho e encerrar.
• 5Conversa: suas mensagens, as respostas e os cartões de cada ação.
• 6Caixa de mensagem: escreva o pedido, anexe prints (📎 ou Ctrl+V) e envie com o botão ou Ctrl+Enter.

Clique em ➕ Nova. A janela Nova sessão do Harness pergunta: “O que vamos construir?”

O tipo não limita o que o Harness pode fazer — ele só define por onde ele começa e quais manuais lê primeiro. Na dúvida, use App para qualquer coisa que tenha tela + dados.

As outras opções da janela

Clique em 🛠️ Criar sessão. Pronto: a conversa está aberta e esperando seu primeiro pedido.

O Harness não conhece a sua barbearia. Um bom pedido responde a quatro perguntas:

1. O quê? O resultado que você quer ver.
2. Para quem? Quem vai usar (cliente no celular, você no computador…).
3. Com quais informações? Nomes, preços, horários, cores, textos reais.
4. Como saber que ficou bom? O que você vai testar.

Mais dicas que fazem diferença

• Um passo de cada vez. Primeiro a página; depois o formulário; depois o chat. Pedidos gigantes dão mais erros.
• Mostre em vez de descrever. Um print de um site que você gosta vale mais que um parágrafo (veja a lição 11).
• Diga o que não quer. “Não altere o painel do administrador.”
• Peça para ele perguntar. “Se faltar alguma informação, me pergunte antes de começar.”
• Corrija conversando. “O botão ficou pequeno no celular, aumente.” Não é preciso começar de novo.

Quando o Harness quer criar ou alterar um arquivo, a conversa para e aparece um cartão amarelo:

• O nome da ferramenta diz o tipo de ação: write cria ou substitui um arquivo inteiro; edit troca um trecho; append acrescenta ao final.
• O caminho diz onde: www/ é público, script/ é o servidor.
• Clique na área cinza para ver o conteúdo que será gravado.
• Permitir grava. Recusar não grava e o Harness fica sabendo — explique na próxima mensagem o que ele deve fazer diferente.

Deu errado? Use o Desfazer

O botão ↶ Desfazer mostra as mensagens que alteraram arquivos. Escolha a partir de qual mensagem quer voltar: tudo o que o Harness gravou dali em diante volta como estava. É a sua rede de segurança — use sem medo.

Crie uma sessão do tipo 🌐 Site, título “Página da barbearia”, aprovação “Perguntar”. Envie:

Abra o site. Não gostou de algo? Continue na mesma conversa:

Um app tem várias peças que conversam entre si. No FlexAgenda da barbearia:

Você não precisa decorar isso. O importante é saber que quase toda mudança mexe em duas pontas: a tela (o que o cliente vê) e a API (o que o servidor faz). Um bom pedido deixa claro qual das duas — ou as duas.

A barbearia quer que o cliente possa escrever uma observação ao agendar (“quero degradê baixo”). Isso mexe na tela, na API e no painel do dono. Para mudanças assim, marque ☐ Planejar primeiro antes de enviar.

No modo plano, o Harness só lê até você aprovar. Leia o plano com calma: é o momento mais barato para corrigir o rumo (“não precisa mudar o painel agora”). Depois de aprovado, ele executa e mostra a lista de tarefas no topo da conversa, riscando cada item concluído.

Como testar

1. No celular, faça um agendamento de teste com a observação “teste”.
2. No painel do dono, abra Agendamentos e confira se a observação aparece.
3. Cancele o agendamento de teste.

Um cliente reclama: “No sábado não aparece nenhum horário.” Para consertar bem, o Harness precisa das mesmas pistas que um técnico pediria:

• O que você fez (passo a passo), o que esperava e o que aconteceu.
• Um print da tela com o erro — cole com Ctrl+V.
• A mensagem de erro exata, se houver (copie o texto, não resuma).

Imagens e prints

• Cole um print com Ctrl+V na caixa de mensagem, ou use o 📎. Até 4 imagens por mensagem.
• Ele também abre imagens que já estão no site: “Olhe a foto www/img/fachada.jpg e crie o topo da página com ela.”
• Alguns modelos de IA não enxergam imagens. Se for o caso, o painel avisa antes de enviar.

Planilhas (.xlsx), Word (.docx) e PDF

Envie o arquivo pelo Gerenciar Arquivos para uma pasta do sandbox/ e peça:

• Ele lê planilhas, Word e PDF (com texto) e cria planilhas .xlsx com fórmulas e formatação de moeda e data.
• PDF escaneado (foto de papel) não tem texto: mande prints das páginas.
• Confira valores importantes: em PDF, colunas de tabela podem desalinhar.

Uma skill é um manual em texto que o Harness lê antes de trabalhar. Existem dois tipos, na janela 📚 Skills:

• Da plataforma: manuais técnicos da FlexPage (como fazer login seguro, como usar o banco de dados, como criar agentes…). Já vêm prontos.
• Deste site: manuais que você escreve sobre o seu negócio. Valem para todas as sessões deste site.

Exemplo: as regras da barbearia

Crie no seu computador um arquivo regras-barbearia.md (texto simples) e envie em 📚 Skills → Enviar .md:

# Regras da Barbearia Navalha

- Tom de voz: descontraído, sem gírias pesadas. Tratamos o cliente por "você".
- Cores: verde-sálvia #5C7C6B e dourado #C9A87C. Nunca usar vermelho.
- Serviços: Corte R$ 40 (30 min), Barba R$ 30 (20 min), Corte + Barba R$ 65 (50 min).
- Barbeiros: Rafa (não atende sábado) e Léo.
- Cancelamento: até 2 horas antes, sem custo.
- Nunca prometer desconto sem aprovação do dono.

Em ⏰ Automações você programa uma mensagem para ser enviada a uma sessão automaticamente. É como deixar um bilhete para o Harness: “toda segunda às 8h, faça isto”.

1. Configure os canais em 🔔 Canais de aviso: no Telegram, cole o token do seu bot, mande uma mensagem ao bot e clique em 🔍 Detectar para achar o seu chat. No e-mail, escolha o provedor e a senha de app.
2. Use 📨 Enviar teste para conferir se o aviso chega.
3. Crie a automação e use ▶ Rodar agora para testar sem esperar o horário.

O próprio Harness também sugere automações: se você pedir “me lembre na sexta de revisar os preços”, ele propõe o agendamento e você aprova.

Nem tudo é site. Às vezes você quer uma planilha, um texto ou um programa para levar embora. Para isso existe a sessão 📦 Projeto: tudo fica numa pasta separada (sandbox/_project/<nome>) que não aparece no site.

• Em 📦 Projetos: ⬇ .zip baixa tudo; você pode publicar com link público ou privado (pede uma chave).
• Arquivos que começam com ponto (.env) nunca saem pelo link público.
• O Harness escreve programas em qualquer linguagem, mas não os executa: ele explica no README como rodar no seu computador.

Cada mensagem que você manda reenvia a conversa inteira para a IA. Por isso uma sessão longa fica cara e lenta. No topo da conversa você vê o contexto (quanto da memória já foi usado) e os tokens gastos.

Todo o consumo aparece em 📊 Consumo de Tokens no menu do painel. O administrador pode definir um limite mensal por usuário em Usuários.

Na barbearia, um agente pode:

• Responder no chat do site: “Vocês abrem sábado? Quanto custa corte + barba?”
• Dizer os horários livres do Rafa amanhã (consultando o app).
• Classificar mensagens de suporte: “reclamação urgente” ou “dúvida simples”.
• Cancelar um agendamento — só depois de o cliente confirmar.
• Atender no WhatsApp com a mesma inteligência.

Por que o agente é seguro por padrão

• Ele não grava nada. Pode, no máximo, ler arquivos que você liberar.
• Tudo que tem efeito passa pelo seu app, através de funções (lição 19). O agente pede; o código do app decide e executa.
• Ele nunca vê chaves nem senhas. A chave de IA fica guardada pelo painel.
• Você liga e desliga quando quiser, e acompanha o consumo.

1. No Harness, clique em 🤖 Agentes.
2. Clique em ▶ Liberar e confirme.
3. Pronto: aparece “✅ Liberado · IA de voce@email.com (provedor · modelo) · limite…”.

Em 🤖 Agentes → ➕ Novo agente, preencha:

Clique em 💾 Salvar agente e depois em ▶ Testar. Faça perguntas como um cliente faria:

Como escrever boas instruções

• Quem é o agente e para quem fala.
• Os fatos que ele pode usar (preços, horários, endereço).
• O tom (curto, simpático, formal…).
• Os limites: o que ele não pode fazer ou prometer, e para onde encaminhar.

O recepcionista sabe os preços porque estão nas instruções. Mas horários livres mudam o tempo todo: só o app sabe. Para isso existem as funções: você declara “o agente pode pedir esta informação”, e o código do app responde.

Edite o recepcionista e, no campo Funções (JSON), coloque:

[
  {
    "nome": "horarios_livres",
    "descricao": "Lista os horários livres de um barbeiro num dia. Use sempre que o cliente perguntar por vagas.",
    "parametros": { "barbeiro": "string", "servico": "string", "data": "string" }
  }
]

• nome: como o agente chama a função.
• descricao: é por ela que o agente decide quando usar. Seja claro.
• parametros: o que ele precisa informar. "string" é texto; "string?" (com ?) torna o campo opcional. Também existem number, integer, boolean, array e object.

Testando no painel (você faz o papel do app)

No ▶ Testar, pergunte “Tem horário amanhã com o Léo para corte?”. O teste para em ⏸ requer_acao e mostra o pedido do agente:

No campo que aparece, digite o que o app responderia e clique em ↩ Enviar resultados:

{ "horarios": ["10:00", "10:30", "15:00"] }

O agente responde com esses horários. Para simular uma falha, digite erro: sistema fora do ar — ele deve pedir desculpas e não inventar horários.

O FlexAgenda recebe mensagens de suporte. Em vez de você ler uma por uma, um agente pode classificar cada mensagem. Para o app entender a resposta, ela precisa vir num formato fixo — é a saída estruturada.

Teste com: “Cheguei no horário e o barbeiro não estava, perdi a manhã!”. O resultado vem em dados, já conferido:

{ "assunto": "reclamação", "urgente": true, "resumo": "Cliente não foi atendido no horário marcado." }

Com isso, o app pode, por exemplo, mandar as urgentes para o seu WhatsApp e guardar as demais para ler depois.

Por padrão, cada pergunta ao agente é independente. Para um chat, ele precisa lembrar: se o cliente disse “sou o João, cliente do Léo”, na próxima mensagem o agente deve saber.

Isso se faz com um identificador de conversa: um nome único por cliente, como cliente-44999990000 (o celular do cliente logado). Mesma conversa = mesma memória.

Testando no painel

1. No ▶ Testar, marque Manter conversa.
2. Envie “Sou o João e sempre corto com o Léo”.
3. Envie “Com quem eu corto?” — ele responde Léo.
4. Clique em 🗑️ Esquecer conversa e pergunte de novo — ele não sabe mais.

• O histórico é guardado com segurança fora das pastas do site e apaga sozinho depois de um prazo sem uso (padrão: 30 dias; campo Guardar conversas no agente).
• Só uma mensagem por vez numa mesma conversa. No site, bloqueie o botão Enviar enquanto a resposta não chega.
• Ofereça ao cliente um botão “limpar conversa”: é dado pessoal dele.

Consultar horários não muda nada. Já cancelar um agendamento muda. Para funções assim, marque "confirmar": true: o agente pede, mas o app sempre mostra ao cliente o que vai acontecer e só executa depois do “sim”.

{
  "nome": "cancelar_agendamento",
  "descricao": "Cancela um agendamento do cliente logado pelo código.",
  "parametros": { "codigo": "string" },
  "confirmar": true
}

Quando um agente acumula muitas tarefas, ele erra mais. A solução é montar uma equipe: um agente principal que delega para especialistas.

1. Cadastre o agente agenda (descrição “Consulta horários livres”, com a função horarios_livres).
2. Cadastre o agente precos (descrição “Informa preços e combos”, com a tabela nas instruções).
3. Cadastre recepcao com as instruções: “Você é a recepção. Horários: delegue ao subagente agenda. Preços: ao subagente precos. Se precisar dos dois, delegue os dois na mesma resposta.” No campo Subagentes, escreva agenda, precos. Em Segundos, coloque 120.
4. Teste: “Tem horário sábado com o Léo e quanto custa corte e barba?”

• Delegações na mesma resposta rodam ao mesmo tempo — a resposta sai mais rápido.
• No resultado do teste aparecem as linhas ↳ agenda e ↳ precos com o consumo de cada um. O consumo total já vem somado.
• Uma função pedida pelo subagente (horarios_livres) chega ao app normalmente, marcada como “pedida pelo subagente agenda”.
• O subagente não vê a conversa: o principal passa para ele tudo o que precisa. Subagentes não têm subagentes próprios.
• Dica de economia: use um modelo mais barato (campo Modelo) nos subagentes de tarefas simples.

Com o agente testado no painel, peça ao Harness para criar o chat no site. Use uma sessão 📱 App nova (ela já conhece o manual de agentes):

O que conferir no código que ele propuser

Mesmo sem ser programador, você consegue checar estes pontos no cartão de aprovação do script/api.js:

Para quem programa, este é o coração do que ele escreve:

require('HarnessAgent');

function chatMensagem(body) {
    var cliente = clienteLogado();              // vem da sessão, nunca do agente
    if (!cliente) return erro(401, 'Faça login');

    var agente = new HarnessAgent('recepcionista');
    var r = agente.rodar({ texto: body.mensagem, conversa: 'cliente-' + cliente.celular }, {
        handlers: {
            horarios_livres: function (a) {
                return { horarios: horariosLivres(a.barbeiro, a.servico, a.data) };
            }
        }
    });

    if (r.status !== 'concluido') {
        logger('[chat] ' + r.status + ': ' + (r.erro || ''));   // o motivo vai para o log
        if (r.execucao && (r.status === 'requer_acao' || r.status === 'executando')) agente.cancelar(r.execucao);
        return erro(503, 'Atendimento indisponível agora. Tente de novo em instantes.');
    }
    return { success: true, resposta: r.texto };
}

O FlexAgenda já recebe mensagens do WhatsApp em script/whatsapp.js (é por ali que chegam as respostas “CONFIRMAR”). O mesmo recepcionista pode responder por lá:

• Mesmo agente, mesmas instruções: ajustou no painel, vale no site e no WhatsApp.
• A conversa do WhatsApp (wa-…) é separada da do site (cliente-…).
• Teste com o seu próprio número antes de divulgar.

Se a barbearia tem outro sistema (um app de celular próprio, um sistema de caixa), ele pode usar os mesmos agentes pela API HTTP.

1. Em 🤖 Agentes → Chaves da API HTTP, crie uma chave com um nome (“app do celular”). Copie na hora: ela não aparece de novo.
2. Guarde a chave só no servidor do outro sistema. Nunca em página de navegador ou no app instalado no celular.
3. Chame a API:

curl -X POST 'https://admin.flexpage.io/api.js?cmd=fp-agent-run' \
  -H "Authorization: Bearer $CHAVE" -H 'Content-Type: application/json' \
  -d '{"agente":"recepcionista","entrada":{"texto":"Vocês abrem domingo?","conversa":"app-123"}}'

A resposta traz status (concluido, requer_acao, executando, falhou, cancelado), texto, dados, acoes e consumo. Chave errada ou revogada devolve HTTP 401.

Em 🤖 Agentes → 📊 Uso do mês e conversas:

• Tabela de uso: chamadas e tokens do mês por agente e origem (script = site, api = outros sistemas, painel = seus testes). Linhas como recepcao > agenda são as delegações.
• Conversas: escolha o agente e veja as conversas guardadas. 👁 Ver mostra as trocas; 🗑️ apaga (por exemplo, quando o cliente pedir).

• Trabalhe no modo “Perguntar” até ter confiança. Leia o caminho de cada arquivo antes de permitir.
• Uma sessão por assunto, com título claro.
• Teste tudo como o cliente faria, de preferência no celular.
• Nunca cole senhas, chaves ou tokens na conversa. Configure-os pelas telas próprias do painel (Configurar IA, Canais de aviso, configurações de integrações).
• Nada de dados de clientes nas instruções dos agentes. Os dados vêm do app, na hora, só do cliente logado.
• Ações com efeito = confirmação ("confirmar": true).
• Avise na política de privacidade que as mensagens do chat são processadas por IA.
• Revise o consumo em 📊 Consumo de Tokens e no uso dos agentes.
• Guarde o que funciona numa skill do site: regras do negócio, tom de voz, cores.