anhhung04/tracecat-자동화-모범-사례

Tracecat 자동화 모범 사례

Slack 연동 자동화의 경우 /skill:tracecat-slackbot-best-practices를 사용하세요. Tracecat Workspace Chat에서는 먼저 /skill:tracecat-workspace-chat을 로드하세요. 호스트별 도구 매핑이 아래의 외부 MCP 단계를 재정의합니다. 필요 시 참조: graph-shape, expressions, run-python, tables, trigger-inputs, case-triggers, secrets, agent-outputs, agent-presets, workflow-editing.

워크플로

외부 Tracecat MCP 연결의 경우, 추측보다는 라이브 컨텍스트에서 시작하세요:

1. list_workspaces로 워크스페이스를 탐색합니다.
2. DSL 구문이나 예제가 필요할 때 tracecat://platform/dsl-reference를 읽습니다.
3. 액션 스키마, 변수 및 시크릿에 대해 get_workflow_authoring_context를 사용합니다.
4. 기존 워크플로의 경우 get_workflow를 사용한 다음, 대상 edit_workflow 패치를 사용하세요 — workflow-editing 참조. run_if, depends_on 또는 join_strategy를 추가하거나 편집하기 전에, 호스트에서 제공하는 경우 get_workflow_graph를 호출하고 모든 업스트림 액션과 그 gated_by 목록을 먼저 읽습니다.
5. validate_workflow로 검증하고, 적절할 때 초안 또는 게시된 실행을 수행한 다음, list_workflow_executions 및 get_workflow_execution으로 실패를 검사합니다.

다른 호스트는 다른 도구 표면을 노출할 수 있습니다. 이러한 기본 MCP 이름을 기계적으로 접두사로 붙이지 말고 해당 어댑터를 따르세요.

워크플로 계약을 변경하는 프로덕션 선택 사항을 명확히 하세요: 워크스페이스, 통합/공급자, 시크릿 소스, 게시/실행 동작, 파괴적 부작용, 승인 또는 수락 기준. 요청이 충분히 구체적이면 진행합니다.

그래프 모양

작성하기 전에 모양을 스케치하고 작업이 허용하는 한 한 줄에 가깝게 유지하세요. 병렬보다는 선형을, 완전 연결보다는 가독성을 선호하세요: 간선 수가 적을수록 좋습니다.

• depends_on은 실행 순서이지 데이터 연결이 아닙니다. 액션은 직접적인 부모뿐만 아니라 모든 조상의 ACTIONS.<ref>.result를 읽을 수 있습니다. 검증은 워크플로에 ref가 존재하는지 확인할 뿐, 부모인지 확인하지 않습니다. 액션이 대기해야 할 때만 간선을 추가하고, 값을 접근 가능하게 만들기 위해 절대 간선을 추가하지 마세요.
• 한 번만 게이트하세요. 액션의 run_if는 체인 아래의 모든 액션도 건너뛰므로, 절대 다운스트림에서 반복하지 마세요. 모든 액션이 동일한 TRIGGER.enabled && ... 가드를 가지고 있는 체인은 잘못되었습니다. 첫 번째 액션만 필요합니다. 다운스트림 액션은 새로운 조건에 대해서만 자체 run_if를 얻으며, 단독으로 작성됩니다. 예외는 조인이며, 이것은 함정입니다: 여러 부모가 있는 태스크는 하나가 살아있는 동안 강제로 건너뛰지 않지만, 기본 join_strategy: all은 모든 부모가 방문되었음을 요구하므로, 하나의 건너뛴 분기가 조인에 도달할 수 없게 만들어 워크플로를 실패시킵니다. join_strategy: any를 사용하거나, 분기의 조건을 조인에 반복하여 먼저 자체 건너뛰기를 하세요.
• 기본값은 단일 체인입니다. 진정으로 독립적인 작업(동시에 실행할 가치가 있는)에 대해서만 분기하고, 나중에 액션이 둘 이상의 분기에서 결과가 필요할 때만 다시 조인하세요.
• 하나의 부모가 표준입니다. 둘 이상은 의도적인 조인을 의미합니다 — 목적에 맞게 join_strategy를 선택하세요.
• 각 run_if를 짧게 유지하세요: 하나의 새로운 조건에 대한 하나의 읽기 쉬운 비교. 긴 &&/|| 체인은 일반적으로 업스트림 게이트를 다시 설명하거나 더 이른 변환에 속합니다.
• 일반 워크플로는 약 20개 노드 이하로, 에이전틱 워크플로는 약 6개 노드 이하로 유지하세요. 프로세스가 읽히는 순서대로 정렬된 읽기 쉬운 위에서 아래로 흐름과 사람이 읽을 수 있는 ref를 선호하세요. Tracecat MCP는 액션이나 간선이 변경될 때 캔버스를 자동으로 포맷하므로, 수동으로 노드를 배치하지 말고 layout을 생략하세요.

과도하게 연결된 재작성, 조인 전략, 오류 간선, 그리고 스캐터가 브랜칭이 아닌 이유에 대한 자세한 내용은 graph-shape를 참조하세요.

액션 우선순위

작업을 수행하는 가장 구체적인 액션을 선택하세요:

1. 통합 액션 (tools.<integration_slug>.*) — 호출되는 제품용. API 호출을 직접 작성하기 전에 짧은 제품 또는 액션 이름 하위 문자열(예: query="okta")로 list_actions를 검색하거나 알려진 tools.<integration_slug> 네임스페이스를 탐색합니다. 검색은 별도의 키워드가 아닌 리터럴 하위 문자열과 일치합니다. 첫 번째 페이지에 적합한 액션이 없을 때 has_more가 true인 동안 next_cursor를 따릅니다. get_action_context로 후보를 검사하고 필요한 자격 증명과 인수를 비교합니다.
2. 코어 액션: 통합 액션이 없는 제품이나 엔드포인트에는 core.http_request / core.http_paginate, 데이터 형성에는 core.transform.*, 플랫폼 데이터에는 core.table.* / core.cases.*.
3. core.script.run_python — 액션이 다루지 않는 자체 포함된 단계에만 사용합니다. 통합 또는 HTTP 액션이 호출을 수행할 수 있는 경우 Python에서 API를 호출하지 마세요.

tools.* 이름을 절대 임의로 만들지 마세요. 일반 요청이 여러 통합에 적합한 경우 먼저 후보를 보여주세요.

에이전트와 Python 중 선택

작업의 종류에 따라 결정하고, 유지 관리성과 가독성을 위해 전체 워크플로를 최적화하세요 — 작업을 수행하는 가장 적은 수의 액션과 최소한의 코드.

• 에이전틱 작업 → 에이전트 사용 (ai.agent / ai.preset_agent). 판단, 조사, 라우팅, 보강 선택, 요약, 메시지 구성 또는 Slack에 게시가 필요한 모든 것. 프리셋의 actions 허용 목록 또는 스킬의 metadata.tools에 도구를 부여한 다음 에이전트를 신뢰하세요. 에이전트, 프롬프트 및 스킬을 선호하세요 — 결정론적 노드 그래프보다 훨씬 적은 구성 요소로 창의적 사고를 수행합니다.
• 결정론적 데이터 플럼빙 → Python 사용 (core.script.run_python). 행을 테이블로 변환, 정규화, 편집, 조인 및 일괄 처리. 이것이 바로 Python의 용도입니다 — 냄새가 아닙니다. 하나의 명확한 run_python 액션이 동일한 작업을 여러 노드에 분산시키는 것보다 낫습니다. API 호출은 데이터 플럼빙이 아닙니다: 통합 또는 core.http_* 액션에 속합니다 (액션 우선순위 참조).

냄새는 에이전틱 부분에 Python을 사용하는 것입니다. 예를 들어, 에이전트에게 Slack 도구를 제공하는 대신 스크립트에서 에이전트의 Slack 메시지를 구성하거나 보내는 경우.

프롬프트 크기 보호 장치: 프롬프트를 합리적인 크기까지 동작으로 밀어 넣으세요. 단일 프롬프트가 너무 커져서 읽기 어려워지면, 하나의 거대 프롬프트를 부풀리지 말고 하위 에이전트 또는 스킬로 분해하세요.

에이전트 우선 자동화

사용자가 에이전틱 워크플로, 에이전트 프리셋을 요청하거나 에이전트를 사용하라고 말하면, 에이전트를 작업의 주요 소유자로 만드세요. 필요한 도구를 제공하고 조사, 결정, 라우팅, 메시지 구성 및 행동을 신뢰하세요. 얇은 형태를 기본값으로 사용하세요: 트리거 -> 변형/편집 -> 이벤트 레코드 upsert -> ai.agent (또는 ai.preset_agent).

에이전트가 실행되기 전에 정규화된 이벤트를 유지하세요. 이벤트가 SIEM, 로그 플랫폼, SaaS 웹훅 스트림, 감사 추적 또는 클라우드 서비스에서 발생하는 경우, 정규화된 페이로드와 검토 상태를 먼저 Tracecat 테이블에 결정론적 upsert로 저장하세요. 이렇게 하면 재시도, 중복 웹훅 및 재생에 내구성 있는 진실 공급원이 제공됩니다. 에이전트를 저장된 행으로 지정하여, 워크플로(에이전트가 아님)가 이벤트의 첫 번째 내구성 있는 레코드를 소유하도록 합니다.

결정론적 노드는 얇고, 직접적이며, 감사하기 쉽고, 에이전트가 소유해서는 안 되는 작업을 수행함으로써 그 자리를 얻습니다: 에이전트가 데이터를 보기 전에 시크릿 편집, 스키마 정규화, 이벤트 행 upsert, 중복 제거 검사로 비용이 많이 드는 에이전트 실행 보호, 제한된 배치 준비 또는 내구성 있는 상태 체크포인트. 판단, 라우팅, 보강, 메시지 구성, 소프트 승인 결정 및 최종 알림 동작은 에이전트에 유지하세요. 승인 질문 자체에 판단이 필요한 경우, 에이전트가 결정하거나 요청 초안을 작성하게 하세요.

두 가지 다른 메커니즘이 위험을 다루며, 프리셋이 소유한 도구와 경쟁하지 않습니다. 워크플로 자체가 수행하는 돌이킬 수 없는 외부 효과에 대해 결정론적 게이트를 사용하세요 — 그래프는 해당 노드가 실행되는지 여부를 결정합니다. 에이전트가 보유한 위험한 도구에 대해 프리셋에서 도구별 tool_approvals를 사용하세요: 에이전트는 도구를 유지하고, 특정 호출이 진행되기 전에 사람이 실행을 일시 중지합니다.

많은 작은 결정론적 노드보다 하나의 잘 지시된 에이전트 또는 재사용 가능한 프리셋을 선호하세요. 에이전트의 도구는 일반적으로 프리셋의 actions 허용 목록에 있거나, 여러 에이전트가 그룹을 공유할 때 첨부된 스킬의 metadata.tools에 있습니다. 이렇게 하면 에이전트가 Workspace Chat과 이를 호출하는 모든 워크플로에서 동일한 도구를 갖게 됩니다. 지침은 동작을 전달할 뿐 권한을 전달하지 않습니다: 출력 계약, Slack 스타일, 중복 제거 규칙, 테넌트 경계 및 허용된 부작용은 프리셋 지침에 포함되며, 에이전트는 저장소 파일 대신 이를 읽습니다. 에이전트가 도구가 필요할 때, 좁은 도구를 거기에 부여하는 것이 일반적으로 동일한 호출을 워크플로 액션으로 래핑하는 것보다 낫습니다.

ai.preset_agent 노드는 일반적으로 preset과 user_prompt만을 가지며, 실행별 컨텍스트를 위한 선택적 instructions 추가를 포함합니다. 해당 actions 인수는 해당 실행에 대해 프리셋 및 해당 스킬의 레지스트리 도구를 추가하지 않고 대체합니다 — MCP 도구는 계속 첨부되며, 빈 목록은 무시됩니다 — 따라서 테스트 또는 평가에서 다른 도구 세트로 프리셋을 시도하는 데 적합합니다. 배송 워크플로에 남겨진 목록은 프리셋의 스킬이 제공하는 레지스트리 도구를 삭제하며, 이는 작성자가 원했던 경우가 거의 없습니다.

에이전트 지침을 금지 사항보다는 목표, 컨텍스트 및 이유로 작성하세요. 포괄적인 규칙은 에이전트에게 제공된 도구를 취소할 수 있습니다: 한 호출자가 "제공된 증거만 사용"을 추가했고 에이전트는 부여된 단일 정책 조회 도구를 건너뛰었습니다. 엄격한 규칙은 되돌릴 수 없거나 외부 지향적인 작업을 위해 남겨두고, 프롬프트 문구에 의존하는 대신 그 뒤에 tool_approvals 또는 결정론적 게이트를 배치하세요.

프리셋의 런타임은 list_actions가 보여주는 것보다 더 많은 기능을 가지고 있습니다: 실제 셸 및 파일 도구, Python, curl, jq 및 DuckDB. 추정된 제한을 보완하기 위해 워크플로 도우미를 추가하기 전에 프리셋/런타임 컨텍스트를 검사하세요 — agent-presets 참조.

작성 기본값

• 에이전틱 워크플로의 경우, 대부분의 동작을 에이전트 프롬프트/프리셋으로 푸시하세요. 이벤트 기반 워크플로의 경우, 에이전트 앞의 단일 변형/편집/upsert 액션이 일반적으로 올바른 결정론적 경계입니다.
• 에이전틱 작업에는 ai.agent / ai.preset_agent를 사용하고, 결정론적 API 호출에는 제품의 tools.* 액션(또는 없을 때 core.http_request)을 사용하며, 결정론적 데이터 작업에는 core.script.run_python을 사용합니다(인라인 표현식, run_if 또는 core.transform.* 액션이 배제된 후 — expressions 및 run-python 참조).
• 대량 테이블 쓰기의 경우, 행이 이미 형성된 경우(배치당 최대 1000행) 기본 네이티브 core.table.insert_rows 액션을 선호합니다. 형성, 청킹 또는 혼합 테이블/케이스 쓰기가 필요한 경우, 여러 DB 지원 액션을 분산시키는 대신 가져온 도우미와 제한된 배치로 core.script.run_python을 사용하세요.
• 사용자가 명시적으로 광범위한 네트워크 기능을 수락하지 않는 한 에이전트에 core.http_request를 제공하지 마세요. 결정론적 HTTP를 워크플로 그래프 또는 엄격하게 범위가 지정된 하위 흐름에 배치하세요.
• 실제 오케스트레이션 경계, 재사용 가능한 하위 워크플로, 별도의 실행 기록, 승인, 장기 실행 액션 또는 독립적인 체크포인트가 있는 경우에만 하위 흐름으로 분할하세요. core.workflow.execute를 사용하고 하드 코딩된 ID보다 workflow_alias를 선호하세요. 하위 흐름 벌크 기본값: loop_strategy: batch, batch_size: 32, fail_strategy: isolated, wait_strategy: wait (부모가 하위 결과를 필요로 하지 않는 경우에만 detach 사용).
• run-python 및 에이전트 출력을 작게 유지하세요: 다운스트림 행, 요약 개수, 제한된 오류 샘플.
• 인라인 ai.agent보다 재사용 가능한 에이전트 프리셋을 선호하고, 더 이상 사용되지 않는 최상위 model_name/model_provider보다 model 객체를 선호하세요 — agent-presets 참조.

일반적인 실수

• 에이전틱 부분에 Python 사용하기 — 에이전트의 Slack 메시지를 구성하거나 게시하거나, 스크립트에서 라우팅/판단 호출을 하는 경우. 에이전트는 메시지 구성, 게시(Slack 도구를 통해) 및 판단을 소유하고, Python은 결정론적 데이터 플럼빙을 소유합니다.
• 그래프를 과도하게 연결: 모든 생산자에서 모든 소비자로의 간선. 조상에서 읽고 하나의 체인을 유지하세요 (graph-shape 참조).
• 체인 아래로 run_if를 반복하거나, 조상이 이미 적용한 조건을 다시 명시하는 경우. 건너뛰기는 자체적으로 전파됩니다 — 맨 위에서 한 번 게이트하고, 다운스트림 액션에는 자체적으로 도입하는 새로운 조건에 대해서만 run_if를 제공하세요 (graph-shape 참조).
• 워크플로 액션 이름은 MCP 도구 이름이 아닙니다. create_workflow와 같은 MCP 도구를 사용하여 워크플로를 관리하고, core.http_request와 같은 액션 이름은 워크플로 YAML 내에서만 사용하세요.
• tools.* 액션 이름을 임의로 만들기. list_actions로 액션을 탐색한 다음, get_action_context로 정확한 스키마를 검사하세요.
• 적합한 tools.* 액션이 존재할 때 core.script.run_python(requests, httpx) 또는 기본 core.http_request에서 제품의 API를 호출하는 경우. 먼저 list_actions에서 제품을 검색하고 페이지를 넘기세요.
• 일반 루프 관리에 for_each를 사용하거나, 데이터가 많은 일괄 처리, 필터링, 조인 또는 테이블 쓰기에 scatter/gather를 사용하는 경우. 워크플로 수준 루프에는 scatter를 기본값으로 사용하고, 다운스트림 단계가 결합된 결과가 필요할 때만 gather를 추가하고 그렇지 않으면 생략하세요. >10개의 분산된 DB 지원 테이블/케이스 액션에 특히 주의하세요. Postgres 연결 슬롯을 소진할 수 있습니다. Scatter의 선택적 간격은 작업을 지연시킬 수 있지만 DB 쓰기를 일괄 처리하지 않습니다. 하나의 core.table.insert_rows 배치 또는 run_python 배치를 사용하세요.
• 기본 join_strategy를 all로 남겨두면 건너뛴 분기가 조인에 도달할 수 없게 됩니다. any를 사용하거나 조인 자체에 조건을 게이트하세요 (graph-shape 참조).
• 프리셋 지침에서 금지 사항을 과도하게 사용하면 에이전트에 부여된 도구가 취소될 수 있습니다. 대신 tool_approvals 또는 결정론적 게이트를 사용하세요.
• ai.preset_agent 노드에서 프리셋의 레지스트리 도구를 대체하기 위해 actions 목록을 남겨두는 경우. 의도하지 않은 경우 비워두거나 생략하세요.
• 더 간단한 네이티브 액션(core.table.insert_rows) 또는 run_python 단일 배치 대신 분산된 core.table.* 호출을 사용하는 경우.
• 제품 이름과 다른 MCP 서버 도구 이름을 가정하거나, 정확한 도구 이름을 먼저 검색하지 않고 임의로 생성하는 경우.

참조

자세한 내용은 마크다운 참조 파일을 참조하세요:

• graph-shape: 과도하게 연결된 그래프 재작성, 조인 전략 선택, 오류 간선 및 스캐터 동작.
• expressions: 인라인 표현식, run_if 조건, transform 액션.
• run-python: run_python에서 tracecat 임포트 사용, 가져오기 가능한 것, 보안 경계.
• tables: 테이블 스키마, 고유 인덱스, upsert 동작, core.table.* 액션.
• case-triggers: 케이스 수명 주기, 트리거 페이로드, core.cases.* 액션.
• secrets: 시크릿 관리, OAuth 흐름, 워크플로에서 시크릿 참조.
• agent-outputs: 에이전트 결과 구조, 출력 스키마, 다운스트림 사용.
• agent-presets: 프리셋 생성, 도구 할당, model 객체, 런타임 기능 및 모범 사례.
• workflow-editing: 패치 워크플로, 변경 사항 병합, 버전 관리.
• trigger-inputs: 트리거 입력 스키마, 워크플로 시작 페이로드.