Pular para o conteúdo
Floopy Docs

Gerenciamento de Prompts

Visão Geral

O Floopy permite que você gerencie prompts diretamente no dashboard, em vez de deixá-los fixos no código da sua aplicação. Crie um prompt uma vez, referencie-o pelo nome nas suas chamadas de API e atualize-o a qualquer momento sem precisar fazer deploy novamente. O gateway resolve a versão mais recente no momento da requisição.

Criando Prompts

Acesse Prompts no dashboard e clique em Create Prompt. Dê um nome e escreva o corpo do prompt. Você pode criar prompts de sistema, templates de mensagens de usuário ou templates de conversa completos.

Os prompts suportam variáveis usando a sintaxe de chaves duplas:

Summarize the following {{document_type}} in {{language}}:


{{content}}

Quando o gateway processa uma requisição que referencia este prompt, ele substitui os valores das variáveis fornecidos na chamada de API. Se uma variável obrigatória estiver ausente, o gateway retorna um erro.

Histórico de Versões

Toda vez que você edita um prompt, o Floopy salva a versão anterior automaticamente. O histórico de versões exibe:

  • Todas as versões anteriores com timestamps.
  • Quem fez cada alteração.
  • Uma comparação lado a lado (diff) entre quaisquer duas versões.

Você pode reverter para uma versão anterior a qualquer momento selecionando-a e clicando em Restore.

Resolução em Tempo Real

Os prompts são resolvidos pelo gateway no momento da requisição. Quando você atualiza um prompt no dashboard, todas as requisições futuras usam imediatamente a nova versão — não há atraso de cache nem período de propagação. Isso significa que você pode iterar na qualidade dos prompts em produção sem alterar o código da sua aplicação.

Rastreamento de Feedback

Anexe feedback às respostas dos prompts para acompanhar a qualidade ao longo do tempo. O Floopy suporta:

  • Positivo / negativo — feedback binário simples de usuários finais ou revisores.
  • Dimensões customizadas — avalie as respostas em dimensões específicas como precisão, tom, utilidade, ou qualquer critério personalizado que você definir.

O feedback é vinculado à versão específica do prompt que gerou a resposta, para que você possa ver como a qualidade muda entre as versões.

Dimensões avançadas de feedback e analytics estão disponíveis no plano Pro e superiores.

Testes A/B

Divida o tráfego entre duas ou mais versões de prompt para comparar o desempenho. Defina uma porcentagem de divisão e deixe o Floopy rotear as requisições de acordo. Acompanhe feedback e métricas por variante para determinar qual versão tem melhor desempenho.

Consulte Testes A/B para detalhes completos sobre configuração de experimentos e aplicação dos vencedores.

Usando Prompts via Gateway

Em vez de incluir o prompt completo no body da requisição, referencie um prompt gerenciado enviando o header floopy-prompt-id. O gateway resolve o template do prompt e substitui as variáveis usando o objeto inputs no body da requisição.

HeaderDescrição
floopy-prompt-idO UUID do prompt a ser resolvido
floopy-prompt-versionFixar uma versão específica (omita para usar a mais recente)
Campo do BodyDescrição
inputsObjeto com pares chave-valor para substituir nas variáveis {{key}}

O campo inputs é removido da requisição antes de chegar ao provedor LLM — ele é usado apenas para substituição de variáveis.

Ordem de Resolução de Variáveis

  1. inputs do body da requisição — primeira prioridade
  2. Valores padrão do template da configuração do prompt no dashboard — fallback
  3. Sem correspondência — o placeholder {{key}} permanece no texto como está

Exemplo

Dado um template de prompt salvo no dashboard:

Summarize the following {{document_type}} in {{language}}:


{{content}}

Chame a API com o objeto inputs para preencher as variáveis:

import { OpenAI } from "openai";


const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});


const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "placeholder" }],
    inputs: {
      document_type: "legal contract",
      language: "English",
      content: "This agreement is entered into by and between...",
    },
  } as any,
  {
    headers: {
      "floopy-prompt-id": "e51a2820-8ab5-4d6a-96a0-cc7bb4759371",
      "floopy-prompt-version": "2",
    },
  },
);


console.log(response.choices[0].message.content);

O gateway substitui {{document_type}}, {{language}} e {{content}} no template do prompt pelos valores de inputs, e então envia o prompt final para o provedor LLM.

Usando Prompts Sem Inputs

Se o seu prompt não possui variáveis, você pode omitir o campo inputs inteiramente. O gateway resolve as mensagens do prompt e as utiliza diretamente:

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "placeholder" }],
  },
  {
    headers: {
      "floopy-prompt-id": "e51a2820-8ab5-4d6a-96a0-cc7bb4759371",
    },
  },
);

Sintaxe de Variáveis

O formato completo para variáveis de prompt é {{ fl:name:type }} onde:

  • fl: é um prefixo obrigatório que identifica a variável como uma variável de template do Floopy.
  • name é o nome da variável (ex: user_name, topic, language).
  • type é o tipo de dado: string, number, boolean, etc.

Exemplos:

Hello {{ fl:user_name:string }}, please summarize this text at a
temperature of {{ fl:temperature:number }}.


Include references: {{ fl:include_refs:boolean }}

O editor de prompts no dashboard destaca as variáveis automaticamente quando você as digita neste formato. Se você usar a sintaxe abreviada {{name}} (sem o prefixo fl: e o tipo), o gateway trata a variável como string por padrão.

Configuração do Modelo

Ao criar ou editar um prompt, você pode configurar parâmetros do modelo que são aplicados sempre que o prompt é resolvido pelo gateway:

  • Temperature (0—2) — Controla a aleatoriedade. Valores mais baixos produzem saídas mais determinísticas; valores mais altos aumentam a criatividade e variação.
  • Max Tokens — Número máximo de tokens que o modelo pode gerar na resposta.
  • Top P (0—1) — Limiar de amostragem por núcleo. O modelo considera apenas os tokens cuja massa de probabilidade acumulada atinge este limiar.
  • Frequency Penalty (-2 a 2) — Reduz repetição penalizando tokens que já apareceram. Valores positivos diminuem a repetição; valores negativos a encorajam.
  • Presence Penalty (-2 a 2) — Encoraja o modelo a falar sobre novos tópicos penalizando tokens que já apareceram, independentemente da frequência.
  • Stop Sequences — Strings separadas por vírgula que fazem o modelo parar de gerar quando encontradas.
  • Reasoning Effort — Controla quanto processamento o modelo dedica ao raciocínio antes de responder. Opções: None, Minimal, Low, Medium, High.
  • Response Format — O formato da resposta do modelo: texto simples ou modo JSON. O modo JSON restringe a saída a JSON válido.

Esses parâmetros são salvos com a versão do prompt. Se você não definir um parâmetro, o valor padrão do modelo é utilizado.

Boas Práticas

  • Use nomes de variáveis descritivos. Nomes como {{customer_name}} são mais claros do que {{x}} e tornam os prompts mais fáceis de manter.
  • Versione de forma intencional. Faça uma alteração lógica por versão para que o diff seja significativo e as reversões sejam limpas.
  • Colete feedback cedo. Mesmo um simples sinal de positivo/negativo ajuda a identificar regressões rapidamente.
  • Teste antes de publicar. Use o Playground para testar alterações nos prompts antes de colocá-los em produção.