anhhung04/tracecat-automation-best-practices

Mejores Prácticas de Automatización en Tracecat

Para automatizaciones orientadas a Slack, usa /skill:tracecat-slackbot-best-practices. En el Chat del Espacio de Trabajo de Tracecat, carga primero /skill:tracecat-workspace-chat; su mapeo de herramientas específico del host anula los pasos MCP externos a continuación. Referencias bajo demanda: graph-shape, expressions, run-python, tables, trigger-inputs, case-triggers, secrets, agent-outputs, agent-presets, workflow-editing.

Flujo de Trabajo

Para una conexión MCP externa de Tracecat, comienza desde el contexto en vivo en lugar de adivinar:

1. Descubre el espacio de trabajo con list_workspaces.
2. Lee tracecat://platform/dsl-reference cuando se necesite sintaxis o ejemplos de DSL.
3. Usa get_workflow_authoring_context para esquemas de acciones, variables y secretos.
4. Para flujos de trabajo existentes, usa get_workflow, luego parches dirigidos con edit_workflow — consulta workflow-editing. Antes de agregar o editar cualquier run_if, depends_on o join_strategy, llama a get_workflow_graph donde el host lo exponga y lee primero cada acción upstream y su lista gated_by.
5. Valida con validate_workflow, ejecuta un borrador o una ejecución publicada cuando sea apropiado, luego inspecciona fallos con list_workflow_executions y get_workflow_execution.

Otros hosts pueden exponer una superficie de herramientas diferente. Sigue su adaptador en lugar de prefijar mecánicamente estos nombres MCP simples.

Aclara las decisiones de producción que cambian el contrato del flujo de trabajo: espacio de trabajo, integración/proveedor, fuente de secretos, comportamiento de publicación/ejecución, efectos secundarios destructivos, aprobaciones o criterios de aceptación. Si la solicitud ya es lo suficientemente específica, procede.

Forma del Grafo

Esboza la forma antes de crear y mantén el flujo lo más cercano posible a una línea según lo permita el trabajo. Prefiere lo lineal sobre lo paralelo, y lo legible sobre lo completamente conectado: menos aristas es la métrica.

• depends_on es orden de ejecución, no cableado de datos. Una acción puede leer ACTIONS.<ref>.result de cualquier ancestro, no solo de un padre directo — la validación verifica que la ref exista en el flujo de trabajo, no que sea un padre. Agrega una arista cuando la acción deba esperar, nunca para hacer que un valor sea alcanzable.
• Controla una vez. Un run_if en una acción también salta todas las acciones debajo de ella en la cadena, por lo tanto nunca lo repitas río abajo. Una cadena donde cada acción lleva la misma guarda TRIGGER.enabled && ... es incorrecta; solo la primera acción la necesita. Una acción río abajo obtiene su propio run_if solo para una condición nueva, escrita sola. La excepción es una unión, y es una trampa: una tarea con varios padres no se salta forzosamente mientras uno sobreviva, pero el join_strategy: all predeterminado entonces requiere que todos los padres hayan sido visitados, por lo que una rama saltada hace que la unión sea inalcanzable y falla el flujo de trabajo. Usa join_strategy: any, o repite la condición de la rama en la unión para que se salte primero.
• Por defecto, usa una sola cadena. Ramifica solo para trabajo genuinamente independiente que valga la pena ejecutar concurrentemente, y reúne solo cuando una acción posterior necesite resultados de más de una rama.
• Un padre es la norma. Más de uno significa una unión deliberada — elige join_strategy a propósito.
• Mantén cada run_if corto: una comparación legible para la única condición nueva. Una cadena larga de &&/|| generalmente reafirma controles upstream o pertenece a una transformación anterior.
• Mantén los flujos de trabajo ordinarios en alrededor de 20 nodos o menos y los flujos de trabajo agénticos en alrededor de 6 nodos o menos. Prefiere flujos legibles de arriba a abajo ordenados según como se lee el proceso, y referencias legibles para humanos. Tracecat MCP formatea automáticamente el lienzo cuando las acciones o aristas cambian, por lo tanto omite layout en lugar de colocar nodos manualmente.

Consulta graph-shape para una reescritura trabajada sobre conexiones excesivas, estrategias de unión, aristas de error y por qué dispersar no es ramificar.

Prioridad de Acciones

Elige la acción más específica que haga el trabajo:

1. Acciones de Integración (tools.<integration_slug>.*) para el producto al que se llama. Busca list_actions con una subcadena corta del nombre del producto o acción (por ejemplo query="okta"), o navega por un espacio de nombres conocido tools.<integration_slug>, antes de escribir una llamada API. La búsqueda coincide con subcadenas literales, no con palabras clave separadas. Sigue next_cursor mientras has_more sea verdadero cuando la primera página carezca de una acción adecuada. Inspecciona candidatos con get_action_context y compara sus credenciales y argumentos requeridos.
2. Acciones Principales: core.http_request / core.http_paginate para productos o endpoints sin acción de integración, core.transform.* para dar forma, y core.table.* / core.cases.* para datos de la plataforma.
3. core.script.run_python solo para un paso autocontenido que ninguna acción cubra. Nunca llames a una API desde Python cuando una acción de integración o HTTP pueda hacer la llamada.

Nunca inventes nombres tools.*. Si una solicitud genérica se ajusta a varias integraciones, muestra primero los candidatos.

Elegir entre un Agente y Python

Decide según el tipo de trabajo, y optimiza todo el flujo de trabajo para mantenibilidad y legibilidad — la menor cantidad de acciones y la menor cantidad de código que haga el trabajo.

• Trabajo agéntico → usa un agente (ai.agent / ai.preset_agent). Cualquier cosa que necesite juicio, investigación, enrutamiento, elecciones de enriquecimiento, resumen, composición de un mensaje o publicación en Slack. Concede las herramientas en la lista blanca de actions del preset o en metadata.tools de un skill, luego confía en el agente con ellas. Prefiere agentes, prompts y skills — llevan el pensamiento creativo con muchas menos partes móviles que un grafo de nodos deterministas.
• Plomería de datos determinista → usa Python (core.script.run_python). Transformar, normalizar, redactar, unir y agrupar filas en tablas. Esto es exactamente para lo que sirve Python — no es un mal olor. Una acción clara de run_python supera dispersar el mismo trabajo en muchos nodos. Las llamadas API no son plomería de datos: van en acciones de integración o core.http_* (consulta Prioridad de Acciones).

El mal olor es usar Python para la parte agéntica — por ejemplo, componer o enviar el mensaje de Slack de un agente desde un script en lugar de darle al agente la herramienta de Slack.

Barrera de protección de tamaño del prompt: empuja el comportamiento dentro del prompt hasta un tamaño razonable. Cuando un solo prompt crece demasiado para mantenerse legible, descompón en subagentes o un skill en lugar de inflar un mega-prompt.

Automatización Primero el Agente

Cuando el usuario solicite un flujo de trabajo agéntico, un preset de agente o diga que use agentes, convierte al agente en el propietario principal del trabajo. Dale las herramientas que necesita y confía en que investigue, decida, enrute, componga mensajes y actúe. Por defecto, usa una forma delgada: trigger -> reshape/redact -> upsert event record -> ai.agent (o ai.preset_agent).

Persiste el evento normalizado antes de que el agente se ejecute. Cuando los eventos se originan en un SIEM, plataforma de registros, flujo de webhook SaaS, rastro de auditoría o servicio en la nube, almacena primero la carga útil normalizada y el estado de revisión en una tabla de Tracecat, con un upsert determinista. Eso proporciona reintentos, webhooks duplicados y reproducción con una fuente de verdad duradera. Apunta al agente a la fila guardada, para que el flujo de trabajo — no el agente — posea el primer registro duradero del evento.

Un nodo determinista se gana su lugar al ser delgado, directo y fácil de auditar, y al hacer trabajo que el agente no debería poseer: redactar secretos antes de que el agente vea datos, normalizar esquema, hacer upsert de la fila del evento, proteger ejecuciones costosas del agente con una verificación de deduplicación, preparar lotes acotados o establecer un punto de control de estado duradero. Mantén el juicio, enrutamiento, enriquecimiento, composición de mensajes, decisiones de aprobación suave y comportamiento de notificación final en el agente. Cuando una pregunta de aprobación en sí misma requiera juicio, deja que el agente decida o redacte la solicitud.

Dos mecanismos diferentes cubren el riesgo, y no compiten con las herramientas propiedad del preset. Usa un control determinista para un efecto externo irreversible que el flujo de trabajo mismo realice — el grafo decide si ese nodo se ejecuta o no. Usa tool_approvals por herramienta en el preset para una herramienta riesgosa que el agente posee: el agente mantiene la herramienta, y la ejecución se pausa para un humano antes de que esa llamada específica se realice.

Favorece un agente bien instruido o un preset reutilizable sobre muchos nodos deterministas pequeños. Las herramientas de un agente normalmente viven en la lista blanca de actions del preset, o en metadata.tools de un skill adjunto cuando varios agentes comparten el grupo. De esa manera, el agente tiene las mismas herramientas en el Chat del Espacio de Trabajo y en cada flujo de trabajo que lo llame. Las instrucciones llevan el comportamiento en lugar de los permisos: contratos de salida, estilo de Slack, reglas de deduplicación, límites de inquilino y efectos secundarios permitidos van en las instrucciones del preset, que el agente lee en lugar de archivos del repositorio. Cuando el agente necesite una herramienta, conceder la herramienta estrecha allí generalmente supera envolver la misma llamada en una acción del flujo de trabajo.

Un nodo ai.preset_agent normalmente lleva solo preset y user_prompt, más un instructions opcional para contexto específico de la ejecución. Su argumento actions reemplaza las herramientas del registro del preset y sus skills para esa ejecución en lugar de agregarles — las herramientas MCP permanecen adjuntas, y una lista vacía se ignora — por lo que es adecuado para probar un preset con un conjunto de herramientas diferente en una prueba o evaluación. Una lista dejada allí en un flujo de trabajo en producción también elimina las herramientas del registro que los skills del preset contribuyen, lo que rara vez es lo que el autor quería.

Escribe las instrucciones del agente como metas, contexto y razones en lugar de prohibiciones. Una regla general puede cancelar una herramienta que se le dio al agente: un llamador añadió "Usa solo evidencia proporcionada" y el agente saltó la única consulta de política para la que se le había concedido una herramienta. Reserva reglas duras para acciones irreversibles o hacia el exterior, y pon tool_approvals o un control determinista detrás de ellas en lugar de confiar en la redacción de un prompt.

El tiempo de ejecución de un preset tiene más capacidad de lo que muestra list_actions: un shell real y herramientas de archivos, Python, curl, jq y DuckDB. Inspecciona el contexto del preset/tiempo de ejecución antes de agregar un ayudante de flujo de trabajo para compensar una limitación supuesta — consulta agent-presets.

Valores Predeterminados de Creación

• Para flujos de trabajo agénticos, empuja la mayor parte del comportamiento al prompt/preset del agente. Para flujos de trabajo impulsados por eventos, una sola acción de reshape/redact/upsert antes del agente suele ser el límite determinista correcto.
• Usa ai.agent / ai.preset_agent para el trabajo agéntico; la acción tools.* del producto (o core.http_request cuando no exista) para llamadas API deterministas; core.script.run_python para trabajo de datos determinista, una vez que se haya descartado una expresión en línea, run_if o una acción core.transform.* — consulta expressions y run-python.
• Para escrituras masivas en tablas, prefiere una acción nativa core.table.insert_rows cuando las filas ya estén formadas (hasta 1000 filas por lote). Si se necesita dar forma, dividir en fragmentos o escrituras mixtas de tablas/casos, usa core.script.run_python con ayudantes importados y lotes acotados en lugar de dispersar muchas acciones respaldadas por la base de datos.
• No le des core.http_request a un agente a menos que el usuario acepte explícitamente la amplia capacidad de red. Pon HTTP determinista en el grafo del flujo de trabajo o en un subflujo estrechamente delimitado.
• Divide en subflujos solo cuando haya un límite de orquestación real, flujo de trabajo hijo reutilizable, historial de ejecución separado, aprobaciones, acciones de larga duración o puntos de control independientes. Usa core.workflow.execute y prefiere workflow_alias sobre IDs codificados. Valores predeterminados de subflujo masivo: loop_strategy: batch, batch_size: 32, fail_strategy: isolated, wait_strategy: wait (usa detach solo cuando el padre no necesite resultados del hijo).
• Mantén las salidas de run-python y del agente pequeñas: filas río abajo, conteos de resumen, muestras de error acotadas.
• Prefiere un preset de agente reutilizable sobre ai.agent en línea, y el objeto model sobre los obsoletos model_name/model_provider de nivel superior — consulta agent-presets.

Errores Comunes

• Usar Python para la parte agéntica — componer o publicar el mensaje de Slack de un agente, o tomar decisiones de enrutamiento/juicio en un script. El agente posee la composición de mensajes, la publicación (a través de una herramienta de Slack) y el juicio; Python posee la plomería de datos determinista.
• Sobre-conectar el grafo: una arista desde cada productor hasta cada consumidor. Lee de ancestros y mantén una sola cadena (consulta graph-shape).
• Repetir un run_if a lo largo de una cadena, reafirmando una condición que un ancestro ya aplicó. El salto se propaga por sí solo — controla una vez en la parte superior, y da a una acción río abajo un run_if solo para una condición nueva que ella misma introduce (consulta graph-shape).
• Los nombres de acciones del flujo de trabajo no son nombres de herramientas MCP. Usa herramientas MCP como create_workflow para gestionar flujos de trabajo, y nombres de acciones como core.http_request solo dentro del YAML del flujo de trabajo.
• Inventar nombres de acciones tools.*. Descubre acciones con list_actions, luego inspecciona esquemas exactos con get_action_context.
• Llamar a la API de un producto desde core.script.run_python (requests, httpx) o un core.http_request simple cuando exista una acción tools.* adecuada. Busca y recorre páginas de list_actions para el producto primero.
• Usar for_each para la gestión ordinaria de bucles, o usar dispersión/recolección para lotes de datos pesados, filtrado, uniones o escrituras en tablas. Por defecto, usa dispersión para bucles a nivel de flujo de trabajo; agrega recolección solo cuando los pasos río abajo necesiten resultados combinados, y omítela en caso contrario. Ten especial cuidado con más de 10 acciones dispersas respaldadas por la base de datos de tablas/casos, que pueden agotar los espacios de conexión de Postgres. El intervalo opcional de dispersión puede escalonar el trabajo, pero no agrupa escrituras en la base de datos; usa una acción core.table.insert_rows para escrituras masivas en una sola tabla. Prefiere acciones nativas de tabla sobre dispersión para cualquier trabajo que se pueda expresar como una sola escritura.

[continue truncated]