anhhung04/tracecat-automation-best-practices

Tracecat Automatisierungs-Best Practices

Verwenden Sie für Slack-orientierte Automatisierungen /skill:tracecat-slackbot-best-practices. Im Tracecat Workspace Chat laden Sie zuerst /skill:tracecat-workspace-chat; dessen host-spezifische Tool-Zuordnung überschreibt die unten stehenden externen MCP-Schritte. On-Demand-Referenzen: graph-shape, expressions, run-python, tables, trigger-inputs, case-triggers, secrets, agent-outputs, agent-presets, workflow-editing.

Workflow

Bei einer externen Tracecat MCP-Verbindung beginnen Sie mit dem Live-Kontext, anstatt zu raten:

1. Erkunden Sie den Arbeitsbereich mit list_workspaces.
2. Lesen Sie tracecat://platform/dsl-reference, wenn DSL-Syntax oder Beispiele benötigt werden.
3. Verwenden Sie get_workflow_authoring_context für Aktionsschemata, Variablen und Geheimnisse.
4. Für bestehende Workflows verwenden Sie get_workflow, dann gezielte edit_workflow-Patches – siehe workflow-editing. Bevor Sie run_if, depends_on oder join_strategy hinzufügen oder bearbeiten, rufen Sie get_workflow_graph auf, wo der Host dies bereitstellt, und lesen Sie zuerst jede vorgelagerte Aktion und deren gated_by-Liste.
5. Validieren Sie mit validate_workflow, führen Sie bei Bedarf eine Entwurfs- oder veröffentlichte Ausführung durch, und untersuchen Sie dann Fehler mit list_workflow_executions und get_workflow_execution.

Andere Hosts können eine andere Tool-Oberfläche bereitstellen. Folgen Sie deren Adapter, anstatt diese rohen MCP-Namen mechanisch voranzustellen.

Klären Sie Produktionsentscheidungen, die den Workflow-Vertrag ändern: Arbeitsbereich, Integration/Provider, Geheimnisquelle, Veröffentlichungs-/Ausführungsverhalten, destruktive Nebeneffekte, Genehmigungen oder Annahmekriterien. Wenn die Anfrage bereits spezifisch genug ist, fahren Sie fort.

Graph-Form

Skizzieren Sie die Form vor der Erstellung und halten Sie sie so nah wie möglich an einer Linie. Bevorzugen Sie linear gegenüber parallel und lesbar gegenüber vollständig verbunden: weniger Kanten ist die Metrik.

• depends_on ist die Ausführungsreihenfolge, nicht die Datenverkabelung. Eine Aktion kann ACTIONS.<ref>.result von jedem Vorfahren lesen, nicht nur von einem direkten Elternknoten – die Validierung prüft, ob die Referenz im Workflow existiert, nicht ob sie ein Elternknoten ist. Fügen Sie eine Kante hinzu, wenn die Aktion warten muss, niemals um einen Wert erreichbar zu machen.
• Einmalig absperren. Ein run_if auf einer Aktion überspringt auch jede darunter liegende Aktion in der Kette, also wiederholen Sie es niemals nachgelagert. Eine Kette, in der jede Aktion denselben TRIGGER.enabled && ...-Guard trägt, ist falsch; nur die erste Aktion benötigt ihn. Eine nachgelagerte Aktion erhält ein eigenes run_if nur für eine neue Bedingung, alleinstehend. Die Ausnahme ist ein Join, und das ist eine Falle: Eine Aufgabe mit mehreren Eltern wird nicht zwangsweise übersprungen, solange eine überlebt, aber der Standard join_strategy: all erfordert dann, dass jeder Elternteil besucht wurde, sodass ein übersprungener Zweig den Join unerreichbar macht und den Workflow zum Scheitern bringt. Verwenden Sie join_strategy: any, oder wiederholen Sie die Bedingung des Zweigs am Join, damit er sich zuerst selbst überspringt.
• Standardmäßig eine einzelne Kette. Verzweigen Sie nur für wirklich unabhängige Arbeit, die parallel ausgeführt werden soll, und führen Sie nur wieder zusammen, wenn eine spätere Aktion Ergebnisse von mehr als einem Zweig benötigt.
• Ein Elternteil ist die Norm. Mehr als einer bedeutet einen bewussten Join – wählen Sie join_strategy mit Bedacht.
• Halten Sie jedes run_if kurz: einen lesbaren Vergleich für die eine neue Bedingung. Eine lange &&/||-Kette wiederholt meist vorgelagerte Sperren oder gehört in eine frühere Transformation.
• Halten Sie gewöhnliche Workflows bei etwa 20 Knoten oder weniger und agentische Workflows bei etwa 6 Knoten oder weniger. Bevorzugen Sie lesbare Top-Down-Abläufe, die in der Reihenfolge des Prozesses angeordnet sind, und menschenlesbare Referenzen. Tracecat MCP formatiert die Leinwand automatisch, wenn sich Aktionen oder Kanten ändern, lassen Sie daher layout weg, anstatt Knoten von Hand zu platzieren.

Siehe graph-shape für eine ausgearbeitete Über-Verbindung-Umschreibung, Join-Strategien, Fehlerkanten und warum Streuung keine Verzweigung ist.

Aktionspriorität

Wählen Sie die spezifischste Aktion, die die Aufgabe erfüllt:

1. Integrationsaktionen (tools.<integration_slug>.*) für das aufgerufene Produkt. Durchsuchen Sie list_actions mit einem kurzen Produkt- oder Aktionsnamen-Teilstring (z.B. query="okta"), oder stöbern Sie in einem bekannten tools.<integration_slug>-Namespace, bevor Sie einen API-Aufruf schreiben. Die Suche findet wörtliche Teilstrings, keine separaten Schlüsselwörter. Folgen Sie next_cursor, während has_more wahr ist, wenn die erste Seite keine geeignete Aktion enthält. Untersuchen Sie Kandidaten mit get_action_context und vergleichen Sie deren erforderliche Anmeldeinformationen und Argumente.
2. Kernaktionen: core.http_request / core.http_paginate für Produkte oder Endpunkte ohne Integrationsaktion, core.transform.* für die Formgebung und core.table.* / core.cases.* für Plattformdaten.
3. core.script.run_python nur für einen eigenständigen Schritt, den keine Aktion abdeckt. Rufen Sie niemals eine API von Python aus auf, wenn eine Integrations- oder HTTP-Aktion den Aufruf tätigen kann.

Erfinden Sie niemals tools.*-Namen. Wenn eine generische Anfrage zu mehreren Integrationen passt, zeigen Sie zuerst die Kandidaten.

Auswahl zwischen einem Agenten und Python

Entscheiden Sie anhand der Art der Arbeit und optimieren Sie den gesamten Workflow für Wartbarkeit und Lesbarkeit – die wenigsten Aktionen und der wenigste Code, der die Aufgabe erfüllt.

• Agentische Arbeit → verwenden Sie einen Agenten (ai.agent / ai.preset_agent). Alles, was Urteilsvermögen, Untersuchung, Routing, Anreicherungsentscheidungen, Zusammenfassung, das Verfassen einer Nachricht oder das Posten an Slack erfordert. Gewähren Sie die Tools auf der Aktions-Whitelist des Presets oder auf den metadata.tools eines Skills, und vertrauen Sie dann dem Agenten damit. Bevorzugen Sie Agenten, Prompts und Skills – sie tragen das kreative Denken mit weitaus weniger beweglichen Teilen als ein Graph deterministischer Knoten.
• Deterministische Datenverkabelung → verwenden Sie Python (core.script.run_python). Transformieren, Normalisieren, Schwärzen, Zusammenführen und Stapeln von Zeilen in Tabellen. Genau dafür ist Python da – es ist kein Zeichen für schlechten Stil. Eine klare run_python-Aktion schlägt das Verteilen derselben Arbeit auf viele Knoten. API-Aufrufe sind keine Datenverkabelung: Sie gehören in Integrations- oder core.http_*-Aktionen (siehe Aktionspriorität).

Das Zeichen für schlechten Stil ist die Verwendung von Python für den agentischen Teil – zum Beispiel das Verfassen oder Senden einer Slack-Nachricht eines Agenten aus einem Skript, anstatt dem Agenten das Slack-Tool zu geben.

Prompt-Größen-Leitplanke: Treiben Sie das Verhalten bis zu einer angemessenen Größe in den Prompt. Wenn ein einzelner Prompt zu groß wird, um lesbar zu bleiben, zerlegen Sie ihn in Unteragenten oder ein Skill, anstatt einen Mega-Prompt aufzublähen.

Agenten-zentrierte Automatisierung

Wenn der Benutzer nach einem agentischen Workflow, einer Agentenvoreinstellung fragt oder sagt, Agenten zu verwenden, machen Sie den Agenten zum primären Eigentümer der Arbeit. Geben Sie ihm die benötigten Tools und vertrauen Sie ihm, zu untersuchen, zu entscheiden, zu routen, Nachrichten zu verfassen und zu handeln. Standardmäßig eine schlanke Form: trigger -> reshape/redact -> upsert event record -> ai.agent (oder ai.preset_agent).

Persistieren Sie das normalisierte Ereignis, bevor der Agent läuft. Wenn Ereignisse von einem SIEM, einer Log-Plattform, einem SaaS-Webhook-Stream, einem Audit-Trail oder einem Cloud-Dienst stammen, speichern Sie die normalisierte Nutzlast und den Überprüfungsstatus zuerst deterministisch in einer Tracecat-Tabelle mit einem Upsert. Das bietet Wiederholungen, doppelten Webhooks und Wiedergabe eine dauerhafte Wahrheitsquelle. Weisen Sie den Agenten auf die gespeicherte Zeile, sodass der Workflow – nicht der Agent – der erste dauerhafte Datensatz des Ereignisses ist.

Ein deterministischer Knoten verdient seinen Platz, indem er dünn, direkt und einfach zu prüfen ist und Arbeit erledigt, die der Agent nicht besitzen sollte: Schwärzen Sie Geheimnisse, bevor der Agent Daten sieht, normalisieren Sie das Schema, führen Sie den Upsert der Ereigniszeile durch, schützen Sie teure Agentenläufe mit einer Deduplizierungsprüfung, bereiten Sie begrenzte Batches vor oder setzen Sie einen Checkpoint für den dauerhaften Zustand. Behalten Sie Urteilsvermögen, Routing, Anreicherung, Nachrichtenkomposition, weiche Genehmigungsentscheidungen und das endgültige Benachrichtigungsverhalten im Agenten. Wenn eine Genehmigungsfrage selbst Urteilsvermögen erfordert, lassen Sie den Agenten entscheiden oder den Antrag entwerfen.

Zwei verschiedene Mechanismen decken Risiken ab, und sie konkurrieren nicht mit Tools des Presets. Verwenden Sie eine deterministische Sperre für einen irreversiblen externen Effekt, den der Workflow selbst ausführt – der Graph entscheidet, ob dieser Knoten überhaupt läuft. Verwenden Sie tool_approvals pro Tool auf dem Preset für ein riskantes Tool, das der Agent hält: Der Agent behält das Tool, und die Ausführung pausiert für einen Menschen, bevor dieser spezifische Aufruf durchgeht.

Bevorzugen Sie einen gut instruierten Agenten oder eine wiederverwendbare Voreinstellung gegenüber vielen kleinen deterministischen Knoten. Die Tools eines Agenten leben normalerweise auf der Aktions-Whitelist des Presets oder auf den metadata.tools eines angehängten Skills, wenn mehrere Agenten die Gruppe teilen. Dadurch hat der Agent dieselben Tools im Workspace Chat und in jedem Workflow, der ihn aufruft. Anweisungen tragen Verhalten anstelle von Berechtigungen: Ausgabeverträge, Slack-Stil, Deduplizierungsregeln, Mandantengrenzen und erlaubte Nebenwirkungen gehören in die Anweisungen des Presets, die der Agent anstelle von Repository-Dateien liest. Wenn der Agent ein Tool benötigt, schlägt die Gewährung des engen Tools dort normalerweise das Verpacken desselben Aufrufs in eine Workflow-Aktion.

Ein ai.preset_agent-Knoten trägt normalerweise nur preset und user_prompt, plus ein optionales instructions-Anhängsel für laufspezifischen Kontext. Sein actions-Argument ersetzt die Registry-Tools des Presets und seiner Skills für diesen Lauf, anstatt sie hinzuzufügen – MCP-Tools bleiben angehängt, und eine leere Liste wird ignoriert – daher eignet es sich, um ein Preset mit einem anderen Tool-Set in einem Test oder einem Eval zu testen. Eine Liste, die in einem ausgelieferten Workflow hinterlassen wird, entfernt auch die Registry-Tools, die die Skills des Presets beitragen, was selten das ist, was der Autor wollte.

Schreiben Sie Agentenanweisungen als Ziele, Kontext und Gründe, nicht als Verbote. Eine pauschale Regel kann ein Tool, das dem Agenten gegeben wurde, aushebeln: Ein Aufrufer fügte „Verwenden Sie nur vorgelegte Beweise“ an, und der Agent übersprang die einzige Richtlinienabfrage, für die ihm ein Tool gewährt worden war. Heben Sie harte Regeln für irreversible oder nach außen gerichtete Aktionen auf und setzen Sie tool_approvals oder eine deterministische Sperre dahinter, anstatt sich auf den Wortlaut eines Prompts zu verlassen.

Die Laufzeit eines Presets hat mehr Fähigkeiten, als list_actions zeigt: eine echte Shell und Datei-Tools, Python, curl, jq und DuckDB. Überprüfen Sie den Preset-/Runtime-Kontext, bevor Sie einen Workflow-Helfer hinzufügen, um eine vermeintliche Einschränkung auszugleichen – siehe agent-presets.

Autoren-Standards

• Drängen Sie bei agentischen Workflows das meiste Verhalten in den Agent-Prompt/das Preset. Bei ereignisgesteuerten Workflows ist eine einzelne Reshape-/Redact-/Upsert-Aktion vor dem Agenten normalerweise die richtige deterministische Grenze.
• Verwenden Sie ai.agent / ai.preset_agent für die agentische Arbeit; die tools.*-Aktion des Produkts (oder core.http_request, wenn keine existiert) für deterministische API-Aufrufe; core.script.run_python für deterministische Datenarbeit, nachdem ein Inline-Ausdruck, run_if oder eine core.transform.*-Aktion ausgeschlossen wurden – siehe expressions und run-python.
• Für Massentabellenschreibvorgänge bevorzugen Sie eine native core.table.insert_rows-Aktion, wenn Zeilen bereits geformt sind (bis zu 1000 Zeilen pro Batch). Wenn Formgebung, Chunking oder gemischte Tabellen-/Case-Schreibvorgänge benötigt werden, verwenden Sie core.script.run_python mit importierten Helfern und begrenzten Batches, anstatt viele DB-gestützte Aktionen zu verteilen.
• Geben Sie core.http_request nicht an einen Agenten, es sei denn, der Benutzer akzeptiert explizit die breite Netzwerkfähigkeit. Setzen Sie deterministisches HTTP in den Workflow-Graphen oder einen eng begrenzten Subflow.
• Teilen Sie nur dann in Subflows auf, wenn es eine echte Orchestrierungsgrenze gibt, einen wiederverwendbaren Child-Workflow, eine separate Ausführungshistorie, Genehmigungen, langlaufende Aktionen oder unabhängiges Checkpointing. Verwenden Sie core.workflow.execute und bevorzugen Sie workflow_alias gegenüber hartcodierten IDs. Subflow-Massen-Standardwerte: loop_strategy: batch, batch_size: 32, fail_strategy: isolated, wait_strategy: wait (verwenden Sie detach nur, wenn der übergeordnete Workflow keine Kind-Ergebnisse benötigt).
• Halten Sie Run-Python- und Agent-Ausgaben klein: nachgelagerte Zeilen, Zusammenfassungszahlen, begrenzte Fehlerbeispiele.
• Bevorzugen Sie eine wiederverwendbare Agentenvoreinstellung gegenüber einem Inline-ai.agent und das model-Objekt gegenüber den veralteten model_name/model_provider auf oberster Ebene – siehe agent-presets.

Häufige Fehler

• Python für den agentischen Teil verwenden – das Verfassen oder Posten einer Slack-Nachricht eines Agenten oder das Treffen von Routing-/Beurteilungsentscheidungen in einem Skript. Der Agent besitzt die Nachrichtenkomposition, das Posten (über ein Slack-Tool) und die Beurteilung; Python besitzt die deterministische Datenverkabelung.
• Übermäßige Verbindung des Graphen: eine Kante von jedem Produzenten zu jedem Verbraucher. Lesen Sie von Vorfahren und halten Sie eine Kette (siehe graph-shape).
• Wiederholen eines run_if in einer Kette, erneutes Angeben einer Bedingung, die ein Vorfahr bereits durchgesetzt hat. Das Überspringen breitet sich von selbst aus – sperren Sie einmal oben, und geben Sie einer nachgelagerten Aktion nur dann ein run_if, wenn es eine neue Bedingung gibt, die sie allein einführt (siehe graph-shape).
• Workflow-Aktionsnamen sind keine MCP-Toolnamen. Verwenden Sie MCP-Tools wie create_workflow, um Workflows zu verwalten, und Aktionsnamen wie core.http_request nur innerhalb von Workflow-YAML.
• Erfinden von tools.*-Aktionsnamen. Entdecken Sie Aktionen mit list_actions und überprüfen Sie dann genaue Schemata mit get_action_context.
• Aufrufen einer Produkt-API von core.script.run_python (requests, httpx) oder einem bloßen core.http_request, wenn eine geeignete tools.*-Aktion existiert. Durchsuchen und blättern Sie zuerst durch list_actions für das Produkt.
• Verwenden von for_each für die gewöhnliche Schleifenverwaltung oder von Streuung/Sammeln für datenintensive Stapelverarbeitung, Filterung, Joins oder Tabellenschreibvorgänge. Standardmäßig Streuung für Workflow-Schleifen; fügen Sie Sammeln nur hinzu, wenn nachgelagerte Schritte kombinierte Ergebnisse benötigen, und lassen Sie es andernfalls weg. Seien Sie besonders vorsichtig mit >10 gestreuten DB-gestützten Tabellen-/Case-Aktionen, die Postgres-Verbindungsslots erschöpfen können. Das optionale Intervall der Streuung kann Arbeit staffeln, aber es bündelt keine DB-Schreibvorgänge; verwenden Sie eine core.table.insert_rows-Aktion im Streu-Ziel oder eine einzelne core.script.run_python, die Batches für Sie handhabt. Discard nicht verwendete Streudaten mit run_if: false auf dem Sammel-Knoten.