Registro de Templates

Intenção

Guardar os prompts como artefatos versionados, com nome, variáveis declaradas, histórico e um processo de publicação. Serve para sistemas com vários prompts em produção, editados por mais de uma pessoa ou por mais de um time.

Problema

Henrique lidera a plataforma de IA de uma empresa de varejo. São 23 prompts em produção, espalhados por quatro serviços: SDR, atendimento, descrição de produtos e resumo de avaliações. Alguns ficam em constantes no código, outros numa tabela de configuração editada por um painel.

Três problemas aparecem toda semana. Ninguém sabe qual versão gerou a resposta da reclamação. O time de marketing quer ajustar o tom sem esperar deploy, mas não há como testar antes de publicar. E dois serviços usam cópias diferentes da mesma persona, que divergiram com o tempo.

Na terça, um cliente reclama no Procon de uma mensagem do SDR que prometeu desconto de Pix na primeira conversa. Henrique abre o trace: tem o texto gerado, o modelo, a hora. Não tem o prompt. O painel de config foi editado na quarta de manhã. O texto de terça sumiu.

O que falta não é um prompt melhor. É um lugar para os prompts, com as mesmas garantias que o código tem: versão, revisão, teste e rollback.

A pergunta que este padrão responde: como gerenciar dezenas de prompts em produção com rastreabilidade e segurança para mudar?

Solução

Crie um registro de templates. Cada template tem:

• Nome estável e versão imutável: publicar uma mudança cria uma versão nova; as antigas nunca mudam.
• Variáveis declaradas, com tipo, para que o código não consiga montar o prompt pela metade.
• Metadados: modelo alvo, autor, motivo da mudança, resultado do eval.
• Etiquetas de ambiente: production, staging, canary, que apontam para versões específicas.

O código pede o template pela etiqueta (ou por versão fixa), renderiza com as variáveis e registra nome e versão no trace. Publicar em produção é mover a etiqueta, depois de o eval passar. Voltar atrás é mover a etiqueta de volta.

Isso trata Prompt Sem Versão e Prompt Espalhado. A refatoração que chega aqui é Extrair Template Versionado.

Estrutura

flowchart LR
  E((("1. Autor edita"))):::human --> V["2. Nova versão imutável"]:::tool
  V --> EV["3. Eval roda na versão nova"]:::tool
  EV --> R[("4. Registro: versões e etiquetas")]:::store
  R -->|"etiqueta production"| S["5. Serviço renderiza com variáveis"]:::tool
  S --> M(["6. Modelo"]):::llm
  M --> T[("7. Trace com nome e versão")]:::store

1. Alguém propõe uma mudança no texto ou nas variáveis.
2. A mudança vira uma versão nova; a anterior continua existindo.
3. O eval roda automaticamente na versão nova.
4. O registro guarda todas as versões e quais etiquetas apontam para quais.
5. O serviço carrega a versão da etiqueta e preenche as variáveis declaradas.
6. O modelo recebe o prompt renderizado.
7. Cada execução registra o template e a versão usados.

Exemplo trabalhado

A reclamação do Procon aponta a conversa conv-4412, terça às 16h. O trace agora tem prompt.name=sdr_first_message e prompt.version=14. Henrique abre o registro:

# prompts/sdr_first_message/labels.yaml
production: 14
staging: 15

A versão 14, imutável, ainda está no disco. O corpo diz: “Não ofereça desconto na primeira mensagem. Se o lead perguntar preço, encaminhe para a tabela vigente.” A versão 15, em staging, relaxou essa regra para um teste de conversão. O eval de 15 caiu 0,3 na rúbrica de tom e ainda não ganhou a etiqueta de produção.

Henrique responde ao jurídico com o texto exato que o modelo recebeu. Marketing continua o teste em staging. Ninguém reescreveu o passado.

Compare os dois jeitos de mudar:

Pseudocódigo

schema Template { name: string, version: int, model: string, variables: map[string, type],
                  body: string, author: string, reason: string, eval_result: EvalSummary? }

function publish(name, body, variables, author, reason):
    v = registry.create_version(name, body, variables, author, reason)   # 2. imutável
    v.eval_result = eval_harness.run(name, v)                            # 3
    if v.eval_result.regressed(baseline=registry.get(name, label="production")):
        return reject(v)
    registry.set_label(name, "staging", v.version)
    return v

function promote(name, version):
    registry.set_label(name, "production", version)                      # rollback = apontar de volta

function render(name, label, values):
    t = registry.get(name, label=label)                                  # 5
    assert set(values) == set(t.variables)                               # nada faltando ou sobrando
    trace.span("prompt", name=t.name, version=t.version)                 # 7
    return t.render(values)

Cenários reais

• SDR de vendas. As mensagens de prospecção têm um template por segmento, versionado. O time comercial propõe mudanças de tom, o eval roda e a etiqueta só muda com aprovação.
• Pipeline de conteúdo. Cada etapa (pesquisa, rascunho, revisão de marca) tem seu template; o post publicado guarda as versões de todos.
• Bot de suporte com escalonamento humano. Os prompts de cada rota vivem no registro, e cada conversa no trace aponta para a versão que respondeu.

Aplicabilidade

• Vários prompts em produção, em mais de um serviço.
• Pessoas fora da engenharia precisam propor mudanças de texto.
• Reclamações e incidentes precisam ser rastreados até a versão do prompt.
• Você quer trocar de modelo rota a rota, com comparação e rollback.

Quando não usar

• Um ou dois prompts, num serviço só, mantidos pelo mesmo time. O repositório com git e o hash do commit no trace já dão versão e histórico.
• Prompts gerados dinamicamente por outro modelo. Versione o gerador, não cada saída.
• Exemplos e conhecimento. Eles mudam por outro ciclo; veja Seletor de Exemplos e RAG.

Um registro não substitui o eval. Sem um Eval Harness na publicação, a etiqueta de produção vira um botão de “publicar e torcer”.

Como implementar

1. Inventarie os prompts em produção e onde cada um vive.
2. Defina o formato do template: nome, versão, variáveis tipadas, modelo, corpo, metadados.
3. Escolha onde guardar: um diretório versionado no repositório, uma tabela com versões imutáveis, ou uma ferramenta pronta de gestão de prompts.
4. Migre os prompts um a um, conferindo que o renderizado é igual ao montado antes.
5. Ligue a publicação ao eval: versão nova só ganha etiqueta de produção se não houver regressão.
6. Registre nome e versão em todo span de chamada ao modelo.
7. Documente o rollback (mover a etiqueta) e ensaie uma vez.

Comece pelo repositório. Arquivos YAML com labels.yaml e um vN.yaml por versão resolvem a maior parte dos casos. Só suba para um serviço com painel quando marketing ou jurídico precisarem editar sem esperar merge, e mesmo aí o eval continua sendo o portão.

Erros comuns

• Lógica no template. {{ "formal" if segment == "industria" else "proximo" }} parece inofensivo até ter oito ramos. Tire a decisão para o código, deixe o template com variáveis já resolvidas.
• Variável opcional de verdade opcional. Se cupom às vezes entra e às vezes não, declare duas versões ou um campo sempre presente (string vazia). Renderizar pela metade é o bug que o schema existe para pegar.
• Etiqueta apontando para versão sem eval. Trate como incidente, não como atalho de sexta-feira.
• Copiar o template entre serviços. Duas cópias divergem na segunda edição. Um nome, várias etiquetas.

Variações

• Registro no repositório. Arquivos YAML ou Markdown versionados pelo git, com a etiqueta como arquivo de configuração. Simples e auditável.
• Registro como serviço. Uma API com versões e etiquetas, editável por painel. Permite mudança sem deploy, com o eval como portão.
• Template por modelo. Uma versão do template para cada modelo suportado, para migrar e comparar sem quebrar.
• Canário. A etiqueta canary recebe uma fração do tráfego antes de virar production. Combina com a ideia de deploy sombra: a versão nova responde em paralelo, sem chegar ao cliente, até o eval de produção acompanhar o de staging.

Custo, latência e falhas

O eval na publicação não é barato, e não precisa ser. Rode o conjunto pequeno (casos que pegam tom, recusa de desconto, variáveis obrigatórias) em toda versão. O conjunto grande roda de noite, na etiqueta staging.

Como avaliar

• Eval por versão, guardado junto com a versão, para comparar o histórico.
• Rastreabilidade: escolha respostas ao acaso no trace e confira que a versão aponta para um template existente com eval.
• Tempo até corrigir: quanto tempo leva de uma reclamação até uma versão nova testada em produção.

{ "template": "sdr_first_message", "candidate": 15, "baseline": 14, "eval": "evals/sdr.jsonl", "block_if": "tom_rubrica < baseline - 0.2" }

Um caso concreto do eval: a mensagem não pode citar preço nem Pix na primeira fala. Se a versão 15 quebrar isso, a etiqueta de produção não se move.

Em produção

• Atributos prompt.name e prompt.version em todo span de modelo.
• Painel com a versão ativa de cada template e a data da última mudança.
• Alerta quando uma versão sem eval recebe a etiqueta de produção.
• Cache local das versões ativas, para o registro não ser ponto único de falha.

Ensaie o rollback. Mover production: 15 para production: 14 tem que ser um passo documentado, testado uma vez em staging, não uma invenção no meio do incidente.

Segurança

Templates são texto, e texto costuma receber atalho. Uma chave de API colada no corpo, “só para o modelo chamar o CRM”, vira o smell Segredo no Prompt. O registro não deve aceitar isso: variáveis de credencial não existem, ferramentas recebem segredo no backend. Veja Tirar Segredo do Prompt.

Quem pode publicar em produção é um papel separado de quem pode propor versão. O painel de marketing escreve em staging. Engenharia (ou um bot do eval) move a etiqueta.

Saída do template ainda vai para o modelo junto com dados do lead. Trate o corpo renderizado como o que é: instrução sua mais dados de fora. A Saída Estruturada no lado da resposta reduz o dano de um template que peça demais.

Prós e contras

Código

As duas abas implementam um registro simples em arquivos versionados, com etiqueta de produção e registro da versão no trace.

from dataclasses import dataclass
from pathlib import Path

import yaml
from jinja2 import Environment, StrictUndefined

ROOT = Path("prompts")
jinja = Environment(undefined=StrictUndefined)  # variável faltando vira erro


@dataclass(frozen=True)
class Template:
    name: str
    version: int
    model: str
    variables: tuple[str, ...]
    body: str

    def render(self, **values) -> str:
        missing = set(self.variables) - set(values)
        extra = set(values) - set(self.variables)
        if missing or extra:
            raise ValueError(f"{self.name}@{self.version}: faltando {missing}, sobrando {extra}")
        return jinja.from_string(self.body).render(**values)


def load(name: str, label: str = "production") -> Template:
    labels = yaml.safe_load((ROOT / name / "labels.yaml").read_text())  # {"production": 14, "staging": 15}
    version = labels[label]
    data = yaml.safe_load((ROOT / name / f"v{version}.yaml").read_text())  # arquivos nunca editados depois de criados
    return Template(name, version, data["model"], tuple(data["variables"]), data["template"])


# uso
tpl = load("sdr_first_message")
prompt = tpl.render(lead_name="Ana", company="Padaria Sol", segment="varejo",
                    pricing_policy="sem preço na primeira mensagem", campaign="lançamento")
span.set_attributes({"prompt.name": tpl.name, "prompt.version": tpl.version})  # 7

type Template = { name: string; version: number; model: string; variables: string[]; body: string };

const cache = new Map<string, { tpl: Template; fetchedAt: number }>();

export async function load(name: string, label = "production"): Promise<Template> {
  const key = `${name}:${label}`;
  const hit = cache.get(key);
  if (hit && Date.now() - hit.fetchedAt < 60_000) return hit.tpl;
  try {
    const res = await fetch(`${process.env.PROMPT_REGISTRY_URL}/templates/${name}?label=${label}`);
    if (!res.ok) throw new Error(`registro respondeu ${res.status}`);
    const tpl = (await res.json()) as Template;
    cache.set(key, { tpl, fetchedAt: Date.now() });
    return tpl;
  } catch (err) {
    if (hit) return hit.tpl; // registro fora do ar: usa a última versão conhecida
    throw err;
  }
}

export function render(tpl: Template, values: Record<string, string>): string {
  const missing = tpl.variables.filter((v) => !(v in values));
  const extra = Object.keys(values).filter((v) => !tpl.variables.includes(v));
  if (missing.length || extra.length) {
    throw new Error(`${tpl.name}@${tpl.version}: faltando ${missing}, sobrando ${extra}`);
  }
  return tpl.body.replace(/\{\{\s*(\w+)\s*\}\}/g, (_, k: string) => values[k]);
}

Teste seu entendimento