Gerenciamento de Prompts

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.

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.

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.

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.

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.

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.

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.

O campo inputs é removido da requisição antes de chegar ao provedor LLM — ele é usado apenas para substituiçã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á

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);

from openai import OpenAI
import os, httpx

# Using httpx directly since the OpenAI SDK doesn't support "inputs"
response = httpx.post(
    "https://api.floopy.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['FLOOPY_API_KEY']}",
        "Content-Type": "application/json",
        "floopy-prompt-id": "e51a2820-8ab5-4d6a-96a0-cc7bb4759371",
        "floopy-prompt-version": "2",
    },
    json={
        "model": "gpt-4o",
        "messages": [{"role": "user", "content": "placeholder"}],
        "inputs": {
            "document_type": "legal contract",
            "language": "English",
            "content": "This agreement is entered into by and between...",
        },
    },
)

print(response.json()["choices"][0]["message"]["content"])

curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "floopy-prompt-id: e51a2820-8ab5-4d6a-96a0-cc7bb4759371" \
  -H "floopy-prompt-version: 2" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "placeholder"}],
    "inputs": {
      "document_type": "legal contract",
      "language": "English",
      "content": "This agreement is entered into by and between..."
    }
  }'

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.

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",
    },
  },
);

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

curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "floopy-prompt-id: e51a2820-8ab5-4d6a-96a0-cc7bb4759371" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "placeholder"}]
  }'

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.

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.

• 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.