핵심 개념

Braidrun의 모든 기능(캔버스, YAML, 예약, 승인, 모니터링)은 매우 제한된 핵심 개념 세트를 중심으로 이루어집니다. 이 페이지에서는 "나중에 어떤 기사를 읽어도 좌표를 알 수 있도록" 이러한 개념을 그림으로 표현합니다.

작업흐름 · 작업흐름

워크플로는 이 플랫폼의 최상위 개체입니다. 다음으로 구성된 "버전 지정 가능한 비즈니스 프로세스 다이어그램"으로 생각할 수 있습니다.

• YAML 문서(구조 정의)
• 메타데이터 세트(트리거, 매개변수 사전 설정, 권한, 태그)
• 여러 과거 실행 기록(감사 및 디버깅용)

로 구성됩니다. 같은 workflow는 Web UI에서 DAG 캔버스로 표시되며, 캔버스와 YAML은 동일한 정의의 두 가지 뷰입니다. Git의 diff는 정상적인 YAML diff이지 뒤죽박죽인 JSON dump가 아닙니다.

워크플로는 다섯 가지 방식으로 트리거될 수 있습니다:

1. 매뉴얼 — 편집기에서 "실행"을 클릭하거나 목록에서 배치를 시작하십시오.
2. 스케줄 — cron 표현식, 고정 간격, 일회성 스케줄, 또는 "상류 워크플로 완료 후 N초 지연"의 체인 트리거.
3. 웹훅 — 외부 시스템의 POST 트리거로, API Key 인증(HMAC 서명 호환).
4. API — v1 API의 트리거 엔드포인트로 귀하 자신의 시스템에서 실행을 개시합니다.
5. 상위 워크플로에 의해 삽입됨 — sub_workflow 단계를 통해 다른 워크플로에서 블랙박스로 호출됩니다.

스텝 · 스텝

단계는 워크플로에서 가장 작은 실행 단위입니다. 각 단계에서는 하나의 "기본 모드"만 선택해야 하며 선택할 수 있습니다.

• single — 단일 에이전트는 하나의 작업 설명을 수행합니다. 가장 가벼운 LLM 호출 기본 요소입니다.
• group_chat — 여러 상담원이 차례로 토론하고 서로의 상황을 참조합니다. 브레인스토밍 및 비판적 검토에 적합합니다.
• agent_based — 오케스트레이터 에이전트는 작업을 읽고 하위 작업을 작업자 에이전트에 동적으로 디스패치합니다.
• code — 代码脚本（Python / JavaScript / TypeScript / Bash / Ruby / Lua / CLI 共 7 种），在隔离沙箱中执行。确定性 > LLM 的场景首选。
• classifier — LLM이 입력에 카테고리 라벨 하나를 붙이고, 결과를 output_variable로 지정한 변수에 써서 이후 step이 condition으로 분기하게 합니다.
• state_machine — 다중 상태 + 상태 전이 조건. 소규모 프로세스가 포함된 여러 반복 또는 워크플로에 적합합니다.
• sub_workflow — 계약 확인, 루프 감지 및 변수 격리를 통해 다른 워크플로를 블랙박스로 호출합니다.
• workflow_output_read — 다른 워크플로 실행이 발행한 출력(publish_outputs)을 읽어 로컬 변수에 저장합니다.

기본 모드 외에도 거의 모든 단계에서 다음과 같은 공통 향상 필드를 오버레이할 수 있습니다.

• depends_on / condition — 선행 의존성 + 건너뛰기 조건(condition은 최상위 && 와 || 를 지원)
• manual_approval — 인적 승인 게이트: 실행을 일시 중지하고, 승인 후 계속 실행
• parallel / timeout_seconds — 병렬 실행 설정 / 단계 타임아웃
• retry — 일시적인 오류에 대한 백오프 재시도 전략
• repeat_until / iterate_over — 조건이 충족될 때까지 반복 / 컬렉션을 항목별로 순회 실행
• extract / aggregate — 출력에서 필드 선택/여러 입력 병합
• publish_outputs — 단계 아티팩트를 명명된 출력으로 발행하여 workflow_output_read가 소비하게 함
• idempotent — "같은 입력 → 같은 출력, 부작용 없음"을 선언하며, 서비스 재시작 후 자동 재개 시 중단된 단계부터 다시 실행할 수 있는지 판단하는 데 사용됩니다
• on_success / on_failure — 성공/실패 후 추가 조치(공지사항 발송, 감사서 작성 등)

에이전트·에이전트

Agent는 "한 번의 LLM 세션 + 그것이 사용할 수 있는 도구 + 그 실행 정책"을 캡슐화한 것입니다. Braidrun에서는 system prompt를 직접 작성하는 일이 거의 없습니다 — 19개 내장 preset 중 하나를 선택하고(universal / coder / researcher / data_analyst / web_scraper / writer ……) 필요에 따라 몇 개 필드를 overrides하면 충분합니다.

agents:
  planner:
    preset: universal              # 选一个基线模板
  analyst:
    preset: data_analyst
    overrides:                     # 按需覆盖
      llm_config:
        temperature: 0.2
      tool_set: [file_system, csv, database]

에이전트는 여러 단계에서 참조될 수 있습니다. 각 단계 실행은 새로운 세션 인스턴스를 엽니다(문자열 메모리 없음). 세부정보 보기 Agent 구성에 대한 자세한 설명.

모듈 · 모듈

모듈은 "WorkflowModuleContract를 선언하는 워크플로"입니다. 즉, 입력/출력 계약을 노출하고 sub_workflow를 통해 다른 워크플로에서 호출할 수 있는 재사용 가능한 워크플로입니다.

모듈이 가져오는 가치:

• Typed+필드레벨 계약검증, "필드 변경 시 모든 다운스트림 문제" 발생하지 않음
• 블랙박스 실행 - 호출자는 내부 단계를 볼 수 없으며 내부 논리는 독립적으로 발전할 수 있습니다.
• "A는 B를 참조하고 B는 A를 참조합니다"를 방지하기 위해 런타임 + 릴리스 시간에 이중 루프 감지
• 모듈 라이브러리에서 원클릭 승격(모듈로 단계 추출)/강등(모듈을 인라인 단계로 복원)

모듈 라이브러리에는 120개 이상의 내장 모듈(플랫폼 로그인, 시간창 계산, ASA 리포트 가져오기, Excel 리포트, Slack 전달 등)이 딸려 있으며, 자세한 내용은 내장 모듈 라이브러리;자신만의 모듈 만들기 참조 모듈화 및 재사용.

실행·실행

실행은 워크플로의 특정 실행 인스턴스입니다. 수명주기는 상태 머신입니다.

PENDING → RUNNING → COMPLETED / FAILED / CANCELLED / INTERRUPTED

승인 게이트를 만나면 실행은 승인 대기 상태에서 멈추고, 승인 후 상태 머신을 계속 진행합니다.

각 실행에는 다음이 포함됩니다.

• 트리거 소스(manual/schedule/webhook/api/sub_workflow)
• 시작 시간, 종료 시간, 총 소요 시간, 단계당 소요 시간
• 모든 단계 입력/출력/중간 이벤트(SSE 이벤트 스트림)
• 누적된 토큰/비용
• 생성된 아티팩트 목록

서비스가 비정상 재시작되면 진행 중인 execution은 INTERRUPTED로 표시됩니다. recovery.autoResumeOnRestart를 켜면 중단된 단계부터 자동으로 재개할 수 있으며, 자세한 내용은 서비스 재시작 후 자동 재개.

자격증 · 자격증

자격 증명은 "API 키, 웹훅 비밀, OAuth 토큰"과 같은 민감한 정보의 통합 저장소입니다. 모든 값은 AES-256-GCM으로 암호화되어 서버 측에 저장됩니다. 일단 기록되면 다시 읽을 수 없습니다(덮어쓰거나 삭제만 가능).

구문 분석 링크는 순서대로 검색되며 첫 번째 적중이 적용됩니다.

1. 현재 사용자의 개인 네임스페이스
2. 사용자 팀의 네임스페이스
3. 시스템 네임스페이스(관리자가 구성한 공개 키)

에이전트/코드 단계는 런타임 시 요청 시 구문 분석되고 로그에 기록되지 않으며 YAML 내보내기에 표시되지 않으며 호출자의 다른 단계에 표시되지 않습니다.

기술/도구 · 기술 및 도구

에이전트의 "손" - LLM 추론 중에 호출할 수 있는 기능입니다. 세 가지 범주로 나누어집니다.

• 내장 도구 세트 — file_system / shell / web / browser / code_execution 잠깐, 기본적으로 사전 설정과 연결됩니다.
• MCP 확장 도구 — MCP 서버에 의해 노출되는 모든 도구를 등록할 수 있습니다.
• 스킬 마켓 — "스킬마켓"에서 공개된 스킬을 선택하고 한 번의 클릭으로 활성화하세요.

변수 및 표현식

모든 동적 값은 이중 중괄호를 통해 전달됩니다. {{ ... }} 를 참조합니다. 세 가지 작성법:

• {{var:name}} — workflow 최상위 변수
• {{steps.plan.output}} — 상류 단계의 출력(권장하는 완전 한정 형태)
• {{plan}} — 생략 형태: 먼저 단계명으로 출력을 찾고, 이어서 변수명으로 값을 찾습니다

classifier의 분류 결과는 그 output_variable로 지정한 변수에 기록되며, 하류 단계가 condition으로 어느 분기로 갈지 판단합니다. 자격 증명은 템플릿 변수를 거치지 않습니다: 실행 시 provider별로 자격 증명 센터에서 파싱하여 주입되고, code 단계가 받는 변수는 WF_VAR_* 환경 변수로 주입됩니다.

전체 구문(JSONPath, 필터, 조건 표현식)은 다음을 참조하세요. 변수 및 표현식.

함께 사진으로 담아보세요

       ┌──────────── Workflow ────────────┐
       │                                  │
Trigger→─────►  Step 1 (single, agent=A) ◄─── Credential (解析给 A)
       │         │                        │
       │         ▼                        │
       │      Step 2 (classifier)         │
       │         │                        │
       │   ┌─────┴─────┐                  │
       │   ▼           ▼                  │
       │ Step 3       Step 4 (sub_workflow ──► Module)
       │ (code)       │                   │
       │              ▼                   │
       │      manual_approval 门控        │
       │              │                   │
       └──────────────┴──► Execution (记录状态 / 产物 / token / cost)

당신은 이미 어디를 봐야할지 알고 있습니다.

• 실제 전투: 첫 번째 작업흐름 — 위의 개념을 실제 작업 흐름에 연결
• 8단계 유형 — 메인 모드 전용의 권위 있는 참조 자료
• 변수 및 표현식 — 단계 간 데이터 연결
• 어휘 — 다른 문서를 읽다가 새로운 단어가 나오면 다시 찾아보세요.