02. 핵심 개념

이음새를 쓰다 보면 계속 나오는 네 단어가 있습니다. 워크플로우 · 노드 · 엣지 · 실행. 이 문서만 읽어두면 나머지 문서는 훨씬 쉽게 읽힙니다.

---

워크플로우 (Workflow)

자동화 하나를 뜻합니다. "매일 아침 매출을 요약해서 슬랙에 보낸다" 같은 것 하나가 워크플로우 하나입니다.

워크플로우는 노드를 엣지로 이은 그림이고, 지켜야 할 규칙이 하나 있습니다.

되돌아가는 길이 없어야 합니다. 화살표를 따라가다 원래 자리로 돌아오면 안 됩니다. (전문 용어로는 DAG — 방향성 비순환 그래프입니다.)

노드는 워크플로우당 최대 200개까지 넣을 수 있습니다.

노드 (Node)

워크플로우 안에서 실제로 뭔가를 하는 한 칸입니다. 여섯 종류가 있습니다.

타입	하는 일	들어오는 선	나가는 선
ENTRYPOINT	시작점. 웹훅이나 스케줄로 워크플로우를 깨웁니다	0개	1개 이상
CALL	일하는 노드. 외부 API 호출, AI 호출, 데이터 변환, 메시지 발송 전부 여기	1개	0개 이상
CONDITIONAL	조건 분기. 값에 따라 갈 길을 고릅니다	1개	2개 이상
JOINT	합류점. 갈라진 길이 다시 만나는 곳	2개 이상	0개 이상
LOOP_START	반복 시작. 배열을 하나씩 처리	1개	1개 이상
LOOP_END	반복 종료. 반복 결과를 모읍니다	1개	0개 이상

여기서 꼭 기억할 규칙 두 가지입니다.

1. ENTRYPOINT는 정확히 하나. 시작점이 둘이거나 없으면 저장이 거부됩니다.
2. 선이 여러 개 들어올 수 있는 건 JOINT뿐. 나머지 노드는 들어오는 선이 딱 하나여야 합니다. 길이 갈라졌다가 다시 만나야 한다면 그 자리에 JOINT를 놓으세요.

자세한 내용: 03. 트리거 설정하기 (ENTRYPOINT) · 04. 통합 카탈로그 (CALL) · 06. 흐름 제어 (CONDITIONAL / JOINT / LOOP)

통합 (Integration)

CALL 노드가 구체적으로 무슨 일을 할지 정하는 부품입니다. CALL 노드는 그 자체로는 아무것도 모릅니다. integration: llm_chat처럼 통합을 지정해야 비로소 "AI를 부르는 노드"가 됩니다.

- id: summarize
  name: AI 요약
  type: CALL
  integration: llm_chat     # ← 이게 무슨 일을 할지 정합니다
  input:                    # ← 통합이 요구하는 값을 채웁니다
    apiContract: OPENAI_CHAT
    model: gpt-4o-mini
    apiKey: "${secrets.OPENAI_API_KEY}"
    userPrompt: "다음 내용을 세 줄로 요약해줘: ..."

통합마다 요구하는 input 항목이 다릅니다. 전체 목록과 항목은 04. 통합 카탈로그에 있습니다.

엣지 (Edge)

노드와 노드를 잇는 선입니다. 두 가지 역할을 합니다.

1) 실행 순서 정하기

edges:
  - from: trigger
    to: fetch-orders     # trigger가 끝나면 fetch-orders를 실행

2) 값 넘기기 (선택)

선에 request.data를 달면, 앞 노드의 출력을 다음 노드가 쓰기 좋은 이름으로 바꿔 넘길 수 있습니다.

edges:
  - from: trigger
    to: send
    request:
      data:
        고객이름: "${nodes.trigger.response.body.customerName}"

이렇게 넘긴 값은 다음 노드에서 ${input.고객이름}으로 씁니다.

꼭 써야 하나요? 아닙니다. 다음 노드에서 ${nodes.trigger.response.body.customerName}으로 직접 참조해도 똑같이 동작합니다. 엣지 매핑은 "노드는 자기가 필요한 값 이름만 알고, 어디서 오는지는 선이 안다"는 식으로 정리하고 싶을 때 씁니다. 처음에는 직접 참조가 더 간단합니다.

실행 (Execution)

트리거가 깨어나면 실행 한 건이 만들어지고, 노드가 순서대로 돌아갑니다.

실행 전체의 상태는 네 가지입니다.

상태	뜻
RUNNING	돌고 있음
COMPLETED	끝까지 성공
FAILED	도중에 실패
CANCELLED	취소됨

노드 하나하나도 각자 상태를 가집니다 — PENDING · RUNNING · COMPLETED · FAILED · RETRYING · CANCELLED. 어느 노드에서 멈췄고 그때 값이 뭐였는지는 실행 이력에서 볼 수 있습니다. → 10. 실행과 모니터링

실행이 시작되면 정의는 얼어붙습니다

실행이 시작되는 그 순간의 워크플로우 모양이 사진처럼 저장되고, 그 실행은 끝까지 그 사진대로 돕니다. 그래서 오래 걸리는 실행이 도는 중에 워크플로우를 고쳐도 이미 돌고 있는 실행은 영향받지 않습니다. 수정한 내용은 다음 실행부터 적용됩니다.

---

전체 그림

지금까지 나온 것들이 어떻게 맞물리는지 한 장으로 보면 이렇습니다.

                    ┌──────────────────────────────────────────┐
   워크스페이스       │  연결(Connections)  변수(Variables)        │
   (공용 자원)        │  데이터셋(Datasets)                        │
                    └──────────────────────────────────────────┘
                                     ↓ 워크플로우가 가져다 씀
   ┌───────────────────────────────────────────────────────────┐
   │  워크플로우                                                  │
   │                                                            │
   │   [ENTRYPOINT] ──엣지──> [CALL] ──엣지──> [CALL]             │
   │    웹훅/스케줄            통합 지정        통합 지정            │
   └───────────────────────────────────────────────────────────┘
                                     ↓ 트리거가 깨우면
   ┌───────────────────────────────────────────────────────────┐
   │  실행 (RUNNING → COMPLETED / FAILED)                        │
   │  노드별 입력·출력·에러가 실행 이력에 남음                        │
   └───────────────────────────────────────────────────────────┘

• 연결: Slack 같은 외부 서비스 계정. 토큰을 YAML에 적지 않아도 되게 해줍니다. → 07번
• 변수: API 키나 설정값. ${secrets.KEY} / ${vars.KEY}로 꺼내 씁니다. → 08번
• 데이터셋: 워크플로우가 읽고 쓰는 표. → 09번

---

다음 → 03. 트리거 설정하기