Eigene Agenten erstellen

Ein eigener Agent ist ein Helfer, den du selbst schreibst: Du legst seine Anweisungen fest, wann er läuft und was er ändern darf. Bau einen, wenn kein herunterladbarer Agent das tut, was du willst. Ist ein installierter Agent nah dran, zeig im Panel Agents (Agenten) auf seine Karte und klick auf Copy agent (Agent kopieren). So bekommst du eine bearbeitbare Kopie.

Bevor du loslegst: Lies Agenten: KI-Helfer für deine Chats. Ein Agent, den du baust, läuft noch nicht von allein. Du fügst ihn anschließend einem Chat hinzu. Eigene Agenten funktionieren in allen Chat-Modi.

Einen eigenen Agenten erstellen

  1. Öffne das Panel Agents.
  2. Klick oben auf New (Neu), das Plus-Symbol. Der ganzseitige Agent-Editor öffnet sich.
  3. Trag im Titelfeld einen Namen ein, zum Beispiel Weather Reporter.
  4. Fülle Description (Beschreibung) und Author (Autor) aus.
  5. Wähle eine Pipeline Phase (Pipeline-Phase; siehe Pipeline Phase).
  6. Schalte unter Custom Agent Abilities (Fähigkeiten eigener Agenten) die Fähigkeiten ein, die der Agent braucht.
  7. Wähle einen Result Type (Ergebnistyp), der zu dem passt, was der Agent erzeugt. Bist du unsicher, nimm Context Injection. Dieser Typ braucht keine Fähigkeit und kein festes Ausgabeformat.
  8. Schreib die Anweisungen des Agenten unter Prompt Template (Prompt-Vorlage).
  9. Klick oben in der Leiste auf Save (Speichern). Ein grünes Saved-Badge erscheint.

Der Agent erscheint jetzt im Bereich Custom Agents (Eigene Agenten) des Panels Agents. Zum Einsetzen öffnest du einen Chat, gehst zu Chat Settings (Chat-Einstellungen), schaltest Enable Agents (Agenten aktivieren) ein und fügst den Agenten aus Custom Agents hinzu.

Pipeline Phase

Die Pipeline Phase legt fest, wann der Agent läuft.

Manche Ergebnistypen erzwingen eine Phase. Text Rewrite stellt auf Post-Processing um. Prompt Patch und Character Activity stellen auf Pre-Generation um.

Agenten in der Phase Post-Processing bekommen zusätzlich den Bereich Turn Data Access (Zugriff auf Zugdaten) mit zwei Schaltern: Pre-generation injections und Parallel agent results. Schalte sie ein, damit der Agent lesen kann, was andere Agenten im selben Zug erzeugt haben.

Custom Agent Abilities

Fähigkeiten sind Befugnisse, die du bewusst freischaltest. Jede bleibt gesperrt, bis du ihren Schalter einschaltest.

Schaltest du Edit lorebooks ein, erscheint der Bereich Lorebook Writer. Schalte dort Allow lorebook entry writes ein und wähle unter Target lorebook ein Lorebook aus. Der Agent darf nur in dieses Lorebook schreiben.

Result Type

Der Result Type sagt Marinara, wie die Antwort des Agenten zu lesen ist. Die meisten Typen erwarten JSON, ein Textformat mit geschweiften Klammern und Anführungszeichen. Ein Typ bleibt ausgegraut, bis du die Fähigkeit einschaltest, die er braucht.

Typen, die keine Fähigkeit brauchen:

Typen, die Edit messages brauchen:

Typen, die Edit trackers brauchen:

Weitere Typen, jeweils mit eigener Fähigkeit:

Steuerelemente für Bildagenten in einem Chat

Ein Agent mit der Fähigkeit Image generation erhält unter Chat Settings → Agents → Custom Agents zwei zusätzliche Steuerelemente.

Activation Keywords

Standardmäßig läuft ein Agent in seinem normalen Takt (der Takt bestimmt, wie oft er läuft). Mit Activation Keywords (Aktivierungs-Schlüsselwörter) wird der Agent übersprungen, solange die Szene nicht dazu passt. Das spart Tokens.

  1. Trag unter Activation Keywords ein Schlüsselwort oder eine Wendung pro Zeile ein, etwa tavern oder secret door.
  2. Stell Scan Depth (Scan-Tiefe) auf die Anzahl der letzten Nachrichten, die durchsucht werden. Der Standard ist 5, das Maximum 200.

Der Agent läuft dann nur, wenn in diesen Nachrichten ein Schlüsselwort vorkommt. Lass das Feld leer, um den Filter auszuschalten. Takt und eine eventuelle Aktivierungsfrage gelten weiterhin.

Tools anhängen

Ein Agent kann Tools aufrufen: Funktionen, die die KI ausführt, um etwas abzurufen oder zu ändern, und deren Ergebnis sie anschließend zurückliest. Das nennt sich auch Function Calling.

  1. Öffne im Agent-Editor Tools / Function Calling und schalte jedes Tool ein, das du willst. Die Liste enthält mitgelieferte Tools und deine eigenen. Wie du eines baust, steht unter Eigene Tools.
  2. Öffne in den Chat Settings den Bereich Function Calling und schalte Enable Tool Use (Tool-Nutzung aktivieren) ein. Ohne diese Einstellung bleiben die Tools des Agenten aus.

Importierte Agenten bekommen nie Tool-Zugriff. Sieh dir einen importierten Agenten an und wähle seine Tools dann selbst aus.

Ein Agent bekommt pro Lauf höchstens 16 Runden mit Tool-Aufrufen (weniger, wenn MAX_TOOL_ROUNDS auf dem Server niedriger ist) und antwortet danach mit dem, was er hat. Ein Modell, das jeweils nur ein Tool aufruft, verbraucht für jeden Aufruf eine Runde. Ein Agent, der viele Einträge speichert, sollte deshalb mehrere Aufrufe in einer Antwort absetzen. Ein Backfill-Lauf für Lorebooks bekommt bis zu 64 Runden.

Named prompt options

Ein Agent kann mehrere Prompt-Varianten enthalten. So wählt jeder Chat eine davon aus, ohne dass du den Agenten bearbeitest.

  1. Suche unter Prompt Template den Bereich Named prompt options (benannte Prompt-Varianten).
  2. Klick auf Add option (Variante hinzufügen).
  3. Gib der Variante einen Namen und eine kurze Beschreibung und schreib dann ihren vollständigen Prompt.

Fügt jemand den Agenten einem Chat hinzu, listet ein Dropdown-Menü Prompt Mode deine Varianten auf. Gibt es keine, erscheint nur der Standard-Prompt.

Weitere Einstellungen

Makros wie {{user}} und {{char}} funktionieren in der Prompt Template. Siehe Makros.

Ein durchgespieltes Beispiel

Dieser Agent schreibt jede Antwort in britisches Englisch um.

  1. Nenn ihn British English Editor.
  2. Schalte unter Custom Agent Abilities die Fähigkeit Edit messages ein.
  3. Wähle unter Result Type den Typ Text Rewrite. Die Phase springt auf Post-Processing.
  4. Füge das hier in die Prompt Template ein:
   You are a copy editor. Rewrite the latest reply into British English.
   Change spelling and vocabulary only. Do not change the meaning, tone, or events.
   Return JSON with an "editedText" field holding the full rewritten reply,
   and a "changes" array of short notes describing what you changed.
  1. Klick auf Save.
  2. Öffne einen Roleplay-Chat, schalte in den Chat Settings Enable Agents ein und füge den Agenten aus Custom Agents hinzu.

Nach jeder Antwort liefert der Agent JSON wie dieses:

{"editedText":"The colour of the harbour caught her eye.","changes":[{"description":"color to colour, harbor to harbour"}]}

Marinara setzt editedText in die Antwort ein. Die Notizen aus changes erscheinen als kurze Zusammenfassung.

Agenten importieren und exportieren

Um einen Agenten zu exportieren, klickst du im Editor oben in der Leiste auf Export agent (Agent exportieren), das Upload-Symbol. Die Datei enthält Prompt und Einstellungen des Agenten, aber nie Definitionen eigener Tools. Für mehrere Agenten nutzt du Select agents (Agenten auswählen) im Panel Agents, markierst sie und exportierst sie.

Externe Importe sind standardmäßig gesperrt.

  1. Öffne Settings → Advanced → Danger Zone und schalte Allow custom Agent imports (Import eigener Agenten erlauben) ein. Eine Änderung an der .env ist nicht nötig.
  2. Klick im Panel Agents auf Import agents (Agenten importieren) und wähle Agent-Dateien oder einen Ordner.
  3. Prüf die Liste der Berechtigungen, die Marinara anzeigt. Bestätige nur, was der Agent braucht. Nicht angehakte Fähigkeiten bleiben gesperrt.

Diese Sperre betrifft nur Agenten aus Dateien, Ordnern oder eigenen Repositories. Agenten, die du selbst anlegst, und offizielle Agenten aus Agent Organizer (Agentenverwaltung) funktionieren ganz normal. Jede importierte Datei bekommt eine neue eigene Identität und kann deshalb keinen offiziellen Agenten ersetzen.

Zur Sicherheit ignoriert Marinara mitgelieferte Funktionen, entfernt Tool-Auswahlen, bereinigt temporäres CSS und prüft die freigegebenen Fähigkeiten, bevor ein importierter Agent Nachrichten, Tracker, Lorebooks, Hintergründe, Sprites, Medien, haptische Geräte, About-Me-Daten, Prompts oder Bilder ändern darf. Importiere vertrauenswürdige Funktionen getrennt, sieh sie durch und häng sie dem Agenten selbst an. Schaltest du den Schalter in der Danger Zone wieder aus, laufen importierte Agenten nicht mehr.

Aktivierungsfragen

Eine Aktivierungsfrage prüft, ob die jüngste Szene deinen Agenten braucht. Sie erkennt Umschreibungen, die Schlüsselwörter übersehen. Dafür braucht sie ein Decision model (Entscheidungsmodell), ein kleines Modell, das Ja-Nein-Fragen beantwortet. Wähle es im Panel Connections aus. Siehe Decision-Modelle. Steht Decision model auf None, dem Standard, bleiben die Fragefelder deaktiviert, und ein Agent mit einer Frage läuft so, als hätte er keine.

  1. Öffne den eigenen Agenten.
  2. Gib eine Question (Frage) mit bis zu 500 Zeichen ein. Die Makros {{user}} und {{char}} funktionieren darin.
  3. Setze Run when probability is at least (ab dieser Wahrscheinlichkeit ausführen) auf die Schwelle für diesen Agenten. Der Agent läuft, wenn die Wahrscheinlichkeit für „ja“ die Schwelle erreicht; höhere Werte überspringen also mehr Läufe. Der Editor zeigt einen empfohlenen Wert für dein Modell: 0,5 für lokale Chat-Modelle und Decision-Konten oder 0,1 für die eingebauten Open-Jev-Modelle. Prüf ihn an deinen eigenen Chats, nachdem du das Modell gewechselt hast. Siehe Schwellenwerte.
  4. Optional: Setze Bypass the question after this many messages without a successful run (Frage nach dieser Anzahl Nachrichten ohne erfolgreiche Ausführung umgehen). Nach so vielen Nachrichten wird die Frage übersprungen, damit ein Modell, das immer wieder „nein“ antwortet, den Agenten nicht dauerhaft stilllegen kann. Schlüsselwörter und Takt gelten weiterhin.

Formuliere die Frage als Aussage über die neueste Nachricht, etwa The latest message moves the scene to a new place. Ein kleines Modell hat das zuverlässiger beantwortet als Did the scene change? Siehe Aussagen formulieren.

So läuft es ab:

Aktivierungsfragen gelten nur für eigene Agenten.

Decision-Bedingungen im Agenten-Prompt

Eine Aktivierungsfrage entscheidet, ob der Agent läuft. Eine Decision-Bedingung in der Prompt Template entscheidet, welche Anweisungen ein laufender Agent erhält. Die Syntax steht unter Bedingte Prompts:

{{#if decision:"In the latest message, the characters move to a different location"}}
Update the location field.
{{else}}
Leave the location as it is.
{{/if}}

Damit schickst du in ruhigen Zügen einen kleineren Prompt. Ein Tracker kann den Ort nur dann aktualisieren, wenn er sich geändert hat. Ein Bildagent kann ein neues Bild nur dann beschreiben, wenn sich die Szene geändert hat. Ein Musikagent kann den Titel nur dann wechseln, wenn die Stimmung umgeschlagen ist. Um einen von mehreren Anweisungssätzen auszuwählen, nimm {{#if decision_choice:"The kind of scene in the latest message" == "combat"}}, dann {{else if decision_choice:"The kind of scene in the latest message" == "dialogue"}} und so weiter. Siehe Bedingte Prompts.

Agenten, die aus Marinara-Agents installiert wurden, verarbeiten ihre Prompts auf dieselbe Weise.

Verwandte Anleitungen