Prompts

Os prompts de cada agente do Hub vivem no Langfuse — não no banco do Hub. A API e o LangGraph buscam o prompt em runtime, com cache curto, e o agente passa a usar a versão marcada como production em até cinco minutos. Esta página descreve a estrutura, as labels, o ciclo de teste e as boas práticas que mantêm a operação estável.

Estrutura de prompts

Cada agente do Hub aponta para um prompt no Langfuse via o campo langfuse_prompt_name no configurable do assistant. O nome segue uma convenção fixa para garantir unicidade entre agentes:

hub-<client_slug>-<agent_id>

• client_slug — nome do agente slugificado (ex.: lia-brasal). Omitir se o agente não tiver nome.
• agent_id — UUID do agente no Hub. Sempre presente, garante unicidade quando o slug se repete.

Exemplos válidos:

hub-lia-brasal-c17c7fcc-816e-4c0f-acb2-a26915ee072f
hub-a1b2c3d4-5e6f-7890-abcd-ef0123456789

Cada prompt deve ter o campo config preenchido. Sem ele, o UI do Langfuse não exibe os metadados do modelo e o agente não consegue derivar provider / temperatura corretamente:

{
  "model": "openai/gpt-4o",
  "temperatura": 0.7,
  "reasoning_model": false,
  "reasoning_effort": "",
  "provider": "openai"
}

Versionamento via Langfuse

Toda atualização de prompt cria uma nova versão imutável no Langfuse. O agente não busca a "última" versão por número — busca pela label aplicada. Isso permite reverter trocando o destino da label, sem reescrever o prompt.

Fluxo de criação de um novo prompt:

curl -X POST https://langfuse.simplafy.com.br/api/public/v2/prompts \
  -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hub-lia-brasal-c17c7fcc-816e-4c0f-acb2-a26915ee072f",
    "type": "text",
    "prompt": "Você é a Lia, assistente da Brasal...",
    "labels": ["production", "latest"],
    "config": {
      "model": "openai/gpt-4o",
      "temperatura": 0.7,
      "reasoning_model": false,
      "reasoning_effort": "",
      "provider": "openai"
    }
  }'

curl -X PATCH https://hub.simplafy.com.br/api/v1/assistants/{assistant_id} \
  -H "Authorization: Bearer $HUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configurable": {
      "langfuse_prompt_name": "hub-lia-brasal-c17c7fcc-816e-4c0f-acb2-a26915ee072f"
    }
  }'

Labels e ambientes

O agente busca exclusivamente prompts marcados com a label production. Labels são o mecanismo de promoção entre ambientes.

Para promover uma nova versão para produção, mover a label production da versão antiga para a nova diretamente no UI do Langfuse ou via API:

curl -X PATCH https://langfuse.simplafy.com.br/api/public/v2/prompts/{name}/versions/{version} \
  -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"newLabels": ["production"]}'

Testar no Lab

Antes de aplicar a label production, validar o prompt em um cenário controlado. O fluxo recomendado:

Boas práticas

Sempre preencher config. Sem ele o agente pode acabar usando um provider/modelo diferente do esperado. O config do Langfuse sobrescreve o model definido no configurable do assistant.

Manter um latest separado de production. A label latest é automática. Não usar como destino do agente — usar production explícita para evitar deploys acidentais ao criar uma nova versão.

Não deletar versões antigas. O custo é zero e elas servem de rollback imediato. Para descontinuar, apenas remover labels.

Variáveis no prompt seguem o padrão {{VAR_*}}. O LangGraph faz substituição textual antes de enviar ao modelo. Variáveis sem valor viram string vazia, não erro.

Cache de 5 minutos é por pod. Em um deploy multi-réplica, a propagação não é simultânea. Para testes precisos de uma versão recém-promovida, reiniciar o deployment simplafy-hub-langgraph força refresh imediato em todas as réplicas.

Um agente, um prompt. Não compartilhar langfuse_prompt_name entre agentes diferentes — quebra rastreabilidade no Langfuse e impede ajustes isolados.