Docs›Prompt-Verwaltung

Prompt-Verwaltung

Prompt-Templates serverseitig speichern, versionieren und auflösen. Handlebars-Templating, Draft/Publish-Workflow und Header- oder SDK-basierte Auflösung.

Überblick

Mit der Prompt-Verwaltung speichern Sie Prompt-Templates in Grepture und lösen sie zur Laufzeit auf. Statt Prompts in Ihrer Anwendung hartzucodieren, definieren Sie sie im Dashboard mit Handlebars-Variablen, versionieren sie mit einem Draft/Publish-Workflow und lösen sie entweder proxy-seitig (per Header) oder SDK-seitig (per grepture.prompt.use()) auf.

• Versionierung — Draft frei bearbeiten, unveränderliche Versionen veröffentlichen (v1, v2, v3...), jede Version als "live" aktivieren, jederzeit zurückrollen
• Templating — {{variable}}-Interpolation, {{#if}}-Bedingungen, {{#each}}-Schleifen
• Auflösung — der Proxy ersetzt die Messages im Request mit dem aufgelösten Template, bevor er an das LLM weiterleitet
• Regel-Integration — Prompts durchlaufen standardmäßig Ihre Regel-Pipeline. Setzen Sie skip_rules, um die Pipeline für System-Prompts zu umgehen.

Prompt erstellen

Gehen Sie im Dashboard zu Prompts und klicken Sie auf New Prompt. Jeder Prompt hat:

Nach dem Erstellen gelangen Sie in den Editor, wo Sie Messages und Variablen definieren.

Messages und Variablen

Jeder Prompt enthält ein Array von Messages (system, user, assistant) mit Handlebars-Templates:

Du bist ein {{tone}} Support-Agent für {{company}}.

{{#if context}}
Hier ist der relevante Kontext:
{{context}}
{{/if}}

Bitte antworte auf folgendes Anliegen:
{{issue}}

Definieren Sie Variablen im Variables-Panel, um zu dokumentieren, was Ihr Template erwartet:

Versionierungs-Workflow

1. Draft — frei bearbeiten, mit dem Test-Panel testen, beliebig oft speichern
2. Publish — erstellt einen Snapshot des aktuellen Drafts als unveränderliche Version (v1, v2, v3...)
3. Activate — legt fest, welche veröffentlichte Version "live" ist (wird aufgelöst, wenn keine Version angegeben wird)
4. Rollback — jede ältere Version aktivieren, um sofort zurückzurollen

Der Draft wird niemals für Produktions-Traffic ausgeliefert, es sei denn, er wird explizit mit @draft angefordert.

Prompts per Header verwenden

Funktioniert mit jedem OpenAI-kompatiblen SDK. Setzen Sie zwei Header auf Ihren Request:

const res = await openai.chat.completions.create(
  { model: "gpt-4o", messages: [] },
  {
    headers: {
      "X-Grepture-Prompt": "support-reply",
      "X-Grepture-Vars": JSON.stringify({
        issue: ticket.text,
        tone: "friendly",
        company: "Acme",
      }),
    },
  },
);

Der Proxy löst das Template auf und ersetzt das messages-Array des Requests vor der Weiterleitung. Das messages-Array im Request-Body wird ignoriert.

Prompts per SDK verwenden

Das SDK stellt einen grepture.prompt-Namespace mit Methoden für jede Kontrollstufe bereit.

prompt.use() — Serverseitige Auflösung

Übergeben Sie grepture.prompt.use() direkt als messages-Feld. Der Proxy löst das Template serverseitig auf — keine zusätzlichen Roundtrips:

import OpenAI from "openai";
import { Grepture } from "@grepture/sdk";

const grepture = new Grepture({
  apiKey: process.env.GREPTURE_API_KEY!,
  proxyUrl: "https://proxy.grepture.com",
});

const openai = new OpenAI({
  ...grepture.clientOptions({
    apiKey: process.env.OPENAI_API_KEY!,
    baseURL: "https://api.openai.com/v1",
  }),
});

const res = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: grepture.prompt.use("support-reply", {
    variables: { issue: ticket.text, tone: "friendly" },
    // version: "draft",  // oder 3, oder weglassen für aktive Version
  }),
});

prompt.assemble() — Clientseitige Auflösung

Holt das Template und löst es lokal auf. Nützlich, wenn Sie Messages vor dem Senden prüfen oder modifizieren möchten:

const { messages } = await grepture.prompt.assemble("support-reply", {
  variables: { issue: ticket.text, tone: "friendly" },
});

// Zusätzlichen Kontext vor dem Senden anhängen
messages.push({ role: "user", content: additionalContext });

const res = await openai.chat.completions.create({
  model: "gpt-4o",
  messages,
});

prompt.get() + prompt.resolve() — Erweiterte Kontrolle

Template einmal abrufen, mehrfach mit verschiedenen Variablen auflösen:

const template = await grepture.prompt.get("support-reply");

const resolved1 = grepture.prompt.resolve(template.messages, vars1);
const resolved2 = grepture.prompt.resolve(template.messages, vars2);

prompt.list() — Prompts auflisten

const prompts = await grepture.prompt.list();
for (const p of prompts) {
  console.log(`${p.slug} (v${p.active_version})`);
}

SDK-Methodenreferenz

Alle Methoden akzeptieren eine optionale version-Option (number \| "draft"). Weglassen für die aktive (live) Version.

promptHeaders() (Low-Level)

Wenn Sie clientOptions() nicht verwenden, können Sie den promptHeaders()-Helper direkt nutzen, um Header auf beliebige Requests zu setzen:

import { promptHeaders } from "@grepture/sdk";

const res = await openai.chat.completions.create(
  { model: "gpt-4o", messages: [] },
  {
    headers: promptHeaders({
      slug: "support-reply",
      variables: { issue: ticket.text, tone: "friendly" },
    }),
  },
);

Prompt-Templates abrufen

Wenn Sie Templates client-seitig auflösen möchten, rufen Sie das rohe Template von der Proxy-API ab:

GET /v1/prompts/support-reply
GET /v1/prompts/support-reply@draft
GET /v1/prompts/support-reply@v3

Gibt die Template-Messages, das Variablen-Schema und Metadaten zurück. Erfordert einen gültigen API-Schlüssel im Authorization-Header.

Template-Syntax

Variablen-Interpolation

Hallo {{name}}, Ihre Bestellung {{order_id}} ist bereit.

Fehlende Variablen werden als leerer String aufgelöst.

Bedingungen

{{#if premium}}
Sie sind Premium-Kunde und haben Anspruch auf Priority-Support.
{{else}}
Standard-Support-Antwort.
{{/if}}

Werte sind falsy, wenn sie leer, "false" oder "0" sind.

Schleifen

{{#each items}}
- {{this}}
{{/each}}

Übergeben Sie Arrays als JSON-Strings im Variablen-Objekt: { items: '["item1", "item2"]' }.

Testen

Das Test-Panel im Prompt-Editor ermöglicht es Ihnen, Variablenwerte einzutragen und die aufgelöste Ausgabe zu sehen, ohne einen API-Aufruf zu machen. Nutzen Sie es, um Ihre Templates vor dem Veröffentlichen zu überprüfen.

Regel-Pipeline-Integration

Standardmäßig durchlaufen aufgelöste Prompts Ihre Guardrail-Regeln wie jeder andere Request. Das bedeutet, PII-Schwärzung, Injektionserkennung und andere Regeln werden auf die finalen aufgelösten Messages angewendet.

Setzen Sie Skip Rules auf einem Prompt, um die Pipeline vollständig zu umgehen. Verwenden Sie dies für System-Prompts, deren Inhalt Sie kontrollieren und bei denen Regeln nicht eingreifen sollen.