Vorlagen-Vertrag Spec v1

Zweck

Diese Spezifikation definiert einen stabilen, agentenlesbaren Vertrag für das Entdecken, Beschreiben, Validieren und Erstellen von Office-Dokumenten aus Vorlagen. Sie ermöglicht es KI-Agenten, Benutzeranfragen wie „Welche Vorlagen gibt es?“ oder „Erstelle ein Schreiben auf Behoerdenbriefbogen“ zu beantworten, ohne Vorlagenwissen hart zu codieren.

Spezifikation vs. Implementierung

Dies ist eine vorausschauende Spezifikation. Die hier beschriebenen Tool-Namen, Parameternamen und Ausgabefelder sind aspirativ und können von den tatsächlich implementierten Tools abweichen. Prüfen Sie immer die Tools-Referenz für die realen, Zod-validierten Signaturen. Wesentliche Zuordnungen: onlyoffice_describe_template → onlyoffice_get_template_schema, onlyoffice_validate_template_data → onlyoffice_validate_data, onlyoffice_create_document → onlyoffice_generate_document.

Terminologie

Begriff	Definition
Vorlage	Agenten-orientierter Dokumenttyp, der aufgelistet, beschrieben, validiert und erstellt werden kann
Manifest	Deklarative JSON-Metadaten und Ausfüllvertrag für eine Vorlagenversion
Renderer	Interne Implementierung, die validierte Daten in ein Dokument umwandelt
Artefakt	Generiertes Dokument, zurückgegeben als URL, Base64 oder MCP-Ressource
Feld	Ein vom Benutzer ausfüllbarer Wert, der im Manifest beschrieben wird
Pflichtfeld	Ohne dieses Feld darf die Dokumenterstellung nicht fortgesetzt werden (sofern kein Standardwert existiert)
Optionales Feld	Kann weggelassen werden; das Manifest kann ein Standardverhalten definieren

Tool-Vertrag

1. Vorlagen auflisten

Gibt verfügbare Vorlagen mit ausreichend Details für die anfängliche Benutzerauswahl zurück.

Eingabe:

Parameter	Typ	Beschreibung
formats	string[]	Optionaler Formatfilter (docx, xlsx, pptx, pdf)
category	string	Optionaler Kategoriefilter
query	string	Optionale natürlichsprachliche Suche
language	enum	"de" oder "en" (Standard: "de")
includeFields	boolean	Feldzusammenfassungen einbeziehen (Standard: true)

Ausgabe: Array von Vorlagen-Listeneinträgen, jeweils mit id, name, description, category, primaryFormat, supportedFormats, requiredFields, optionalFields.

2. Vorlage beschreiben

Gibt den vollständigen Ausfüllvertrag für eine Vorlage zurück.

Eingabe:

Parameter	Typ	Beschreibung
templateId	string	Vorlagen-Bezeichner
version	string	Vorlagenversion (optional)
language	enum	"de" oder "en" (Standard: "de")

Ausgabe: Vollständiges Vorlagen-Manifest einschließlich JSON-Schema, Beispielen, Feldbeschreibungen, Validierungsregeln und vorgeschlagenen Rückfragen.

3. Vorlagendaten validieren

Validiert vom Benutzer bereitgestellte Daten vor dem Rendern.

Eingabe:

Parameter	Typ	Beschreibung
templateId	string	Vorlagen-Bezeichner
data	object	Zu validierende Daten
version	string	Vorlagenversion (optional)

Ausgabe:

{
  "valid": true,
  "errors": [],
  "missingRequiredFields": [],
  "suggestedQuestions": []
}

4. Dokument erstellen

Erstellt das Office-Artefakt nach der Validierung.

Eingabe:

Parameter	Typ	Beschreibung
templateId	string	Vorlagen-Bezeichner
data	object	Validierte Vorlagendaten
outputFormat	enum	docx, xlsx, pptx oder pdf
outputFilename	string	Benutzerdefinierter Dateiname (optional)
deliveryMethod	enum	url, base64 oder resource (Standard: url)

Ausgabe: success, jobId, templateId, format, filename, artifact (oder downloadUrl).

Vorlagen-Manifest v1

Hinweis

Dieses Manifestformat ist vorausschauend. Aktuelle Vorlagen verwenden schema.json + eine Vorlagendatei (template.docbuilder oder source.docx) anstelle von manifest.json. Das hier beschriebene Manifestformat ist das Zieldesign für die zukünftige Vorlagenerstellung.

Der geplante Manifest-Speicherort ist templates/<id>/<version>/manifest.json.

Pflichtfelder

Feld	Typ	Beschreibung
manifestVersion	const	Muss "1.0" sein
id	string	Vorlagen-Bezeichner
version	string	Vorlagenversion
names	object	Anzeigenamen (de erforderlich, en optional)
descriptions	object	Beschreibungen (de erforderlich, en optional)
category	string	Vorlagenkategorie
primaryFormat	enum	docx, xlsx oder pptx
supportedFormats	string[]	Array, das pdf enthält, wenn Export unterstützt wird
fields	Field[]	Felddefinitionen (siehe unten)
validation	object	JSON-Schema-Dateireferenz
examples	Example[]	Beispieldaten
renderer	object	Renderer-Typ + Vorlagendatei

Feldtypen

Typ	Beschreibung
string	Freitext
date	Datumsstring (DD.MM.YYYY)
email	E-Mail-Adresse
phone	Telefonnummer
address	Adressobjekt
person	Personenobjekt (Name, Position usw.)
object	Verschachteltes Objekt
array	Array von Werten
enum	Aufzählungswerte
richText	Mehrabsätziger Text

Felddefinition

{
  "key": "Positionstitel",
  "label": "Positionstitel",
  "type": "string",
  "required": true,
  "description": "Job title",
  "askIfMissing": "Welche Position soll besetzt werden?",
  "group": "position"
}

Beispiel

{
  "name": "Minimal Example",
  "description": "Minimal valid data",
  "data": {
    "Positionstitel": "Software Engineer",
    "Fachbereich": "IT"
  }
}

Vorgeschlagene Fragen

Das Manifest kann Rückfragen für fehlende Pflichtfelder deklarieren:

{
  "field": "Standort",
  "question": "An welchem Standort wird die Position angesiedelt?",
  "priority": "required"
}

Beispiel-Benutzerworkflow

User: "Erstelle eine Stellenbeschreibung fuer einen Software Engineer"
  |
  v
Agent calls: onlyoffice_list_templates({ query: "stellenbeschreibung" })
  |
  v
Agent calls: onlyoffice_describe_template({ templateId: "stellenbeschreibung" })
  -> Returns required fields + suggested questions
  |
  v
Agent asks user for missing required fields
  -> User provides: Fachbereich, Abteilung, Standort, etc.
  |
  v
Agent calls: onlyoffice_validate_template_data({ templateId, data })
  -> Returns: valid=true
  |
  v
Agent calls: onlyoffice_create_document({ templateId, data, outputFormat: "docx" })
  -> Returns: downloadUrl

Verwandte Themen

• Tools-Referenz — Tatsächlich implementierte Tool-Signaturen
• Vorlagen-Referenz — Verfügbare Vorlagen mit Feldschemata
• API-Übersicht — Tool-Kategorien und Protokoll-Details