모범 사례

이 글은 "밟힌 구덩이"를 요약한 것입니다. 10개 이상의 작업 흐름을 작성해 본 적이 있다면 공감할 수 있을 것입니다. 아직 작성하지 않았다면 먼저 저장하고 마주치면 다시 찾아오세요.

1. 프로덕션에 투입할 수 있는 워크플로를 작성하는 방법

템플릿에서 시작하기

귀하의 시나리오가 아무리 독특해 보여도 240개 이상의 템플릿 중 "절반은 떼어내고 절반은 고쳐서" 쓸 수 있는 것이 늘 하나쯤 있습니다. 템플릿에서 시작하면 처음부터 골격을 짜는 많은 시간을 절약합니다.

템플릿에서 인스턴스화 는 대부분 사용자의 첫 단계입니다.

"멍청한 버전"을 먼저 수행한 다음 "스마트 버전"을 수행하십시오.

새로운 워크플로의 첫 번째 버전:

• 변수에 대해 하드 코딩된 기본값
• 조건을 추가하지 말고 모두 실행하세요.
• 플랫폼의 통합 LLM 키를 사용하면 BYOK에 대해 걱정할 필요가 없습니다.
• 크론을 중단하지 말고 수동으로 실행하세요.

모든 과정을 거친 후 가변화, 분기, BYOK, 크론, 승인 등을 하나씩 "정제"합니다. 이렇게 하면 모든 단계에서 문제를 쉽게 찾을 수 있습니다.

변경할 때마다 테스트 실행

뭔가 변경 → DAG 구조 및 변수 흐름을 확인하기 위해 테스트 실행 → 다시 실행. 테스트 실행 비용은 0입니다. 점프하지 마세요.

2. 단계 유형 선택

우선 순위는 위에서 아래로입니다. 선택이 어려우면 순위가 더 높은 것을 선택하세요.

1. code — 결정론적 논리를 사용할 수 있다면 LLM을 사용하지 마세요. 빠르고 저렴하며 테스트 가능합니다.
2. classifier — LLM이 필요하지만 출력이 카테고리인 경우에 사용하십시오. 에이전트가 자유롭게 플레이할 수 있도록 싱글을 사용하지 마십시오.
3. single — 대부분의 "요약/추출/다시 쓰기" 작업.
4. sub_workflow — 同一段逻辑在多个 workflow 里复用，或单 workflow > 15 个 step。
5. group_chat — 여러 관점이 서로 논의해야 하는 작업에 사용합니다. 하나의 Agent가 독립적으로 완료할 수 있으면 single을 사용합니다.
6. agent_based — 작업에는 강력한 분기 특성이 있으며 각 분기에는 보낼 위치를 결정하기 위해 LLM이 필요합니다.
7. state_machine — 여러 라운드의 상호 작용/작업 주문 수명 주기와 같은 명확한 상태 전환이 있습니다.
8. manual_approval — 온라인/돈 지출/외부 당사자에 영향을 미치는 모든 단계 전에 추가해야 합니다.

3. 변수 및 데이터 흐름

큰 필드가 먼저 추출된 후 전달됩니다.

업스트림 단계가 100KB JSON을 반환하는 경우 이를 다운스트림 작업으로 직접 보내지 마세요. 추출을 사용하여 정말로 필요한 필드를 선택하세요.

- id: fetch_data
  type: code
  code: |
    // 返回一个很大的 JSON
    return await heavyFetch();
  extract:
    user_count: $.data.stats.total_users
    top_3: $.data.items[:3].name

사용 | default(...) 알아보기

비어 있을 수 있는 변수(조건에 따라 건너뛴 단계의 출력)를 참조할 때 기본값을 추가하세요.

- id: summarize
  type: single
  agent: writer
  condition: "length({{steps.classify.categories}} | default([])) > 0"
  task: "{{steps.classify.output | default('无内容可摘要')}}"

condition 분기 대 on_failure

섞지 마세요:

• 조건 제어는 "정상적인 상황에서는 이 단계를 수행할 수 없습니다" - 건너뛰기 = 건너뛰기(실패로 간주되지 않음)
• on_failure는 "오류 후 보상 조치"입니다. 알림을 보내거나 대체 데이터 소스로 다운그레이드합니다.

on_failure를 try-catch로 사용하지만 일반 분기로는 사용하지 마십시오. 일반적인 비즈니스 로직은 조건을 사용합니다.

4. 대리인 및 모델

tool_set 작을수록 좋습니다

기본 사전 설정에서 제공되는 도구는 대부분의 단계에서 사용되지 않습니다. 2~3개로 자르면 성공률이 높아지고 토큰 소모량이 줄어듭니다.

작업에 따라 모델을 선택합니다.

• 추론 / 코드 검토 → Claude Opus 4 / GPT-5 / DeepSeek-Reasoning
• 간략한 요약 / 카테고리 → Haiku / GPT-4.1-mini / DeepSeek-V3.5
• 한문 → Claude Sonnet / Kimi K2
• 긴 컨텍스트(32K+) → Kimi K2 / Claude 200K

온도 작업별 선택

• 0.0 – 0.3 – 추론/분류/추출(안정적)
• 0.4 – 0.7 – 요약/재작성(균형 조정)
• 0.7 – 0.9 – 창의적인 글쓰기/브레인스토밍(창의력을 발휘하세요)

5. 멱등성 및 자동 연속

순수 데이터 파이프라인의 모든 단계는 멱등성을 추가합니다: true - 다시 시작한 후에도 서비스가 계속 실행될 수 있습니다. 부작용(메시지 보내기/주문)이 포함된 단계를 추가하지 마세요.

세부정보 보기 자동 재개.

6. 분할 및 모듈화

1. 워크플로에는 15개 이상의 단계가 있으므로 분할해야 합니다.
2. 동일한 3~5단계 로직을 다른 워크플로에서도 사용해야 합니다. 모듈(sub_workflow)로 만들어야 합니다.
3. 모듈이 출시된 후 입력을 삭제하거나 타입을 변경하면 호환성이 깨지므로 MAJOR 버전을 업그레이드해야 합니다.

7. 비용 관리

• 먼저 테스트 실행 — 앞서 말했듯이 실제 실행을 한 번 헛돌리는 것이 낭비하는 비용이 가장 크므로, 이 항목이 가장 절약됩니다.
• 저렴한 모델을 사용한 분류 — 분류기 10개 중 9개에는 Opus/GPT-5가 필요하지 않습니다.
• 동시성에는 상한이 있습니다 — 일괄 처리의 경우 sub_workflow + max_parallel을 사용하여 동시성을 제어하고 TPM이 폭발하지 않도록 하세요.
• 캐시 RAG 인덱스 — 매번 동일한 말뭉치를 다시 삽입하고 결과를 제품에 유지하는 데 비용이 많이 듭니다.
• 예산 알람 바인딩 — 在通知设置里加"单 execution cost > $1"或"当日累计 > $50"告警。

8. 보안 및 규정 준수

• 절대로 YAML에 키를 쓰지 마세요. Credential Center를 사용하세요.
• 코드 단계의 자격 증명: 목록은 명시적이어야 합니다. 필요하지 않은 단계 자격 증명을 제공하지 마세요.
• 결제/외부 커뮤니케이션/고객 데이터베이스 작성 전 manual_approval을 추가합니다.
• 사용자 데이터와 관련된 워크플로 공개를 고려하세요. 승인자컴플라이언스팀이 입력할 승인자 목록입니다.
• Webhook에 사용하는 API Key(그리고 호환 모드의 signing secret)는 정기적으로 교체합니다.

9. 테스트 및 출시 프로세스

1. 새 워크플로는 테스트 워크플로 페이지에서 먼저 테스트 실행됩니다.
2. 출력을 보려면 로컬 노드/Python에서 별도로 코드 단계 스크립트를 실행하세요.
3. 중단점 디버거 + 작은 샘플을 사용하여 에이전트 동작을 10회 실행하여 안정성을 확인합니다.
4. 예약이 온라인으로 전환되기 전에 "즉시 한 번 트리거"를 사용하여 시간대/매개변수 사전 설정을 확인하세요.

10. 협업 및 버전

• 중요한 변경을 하기 전에 "YAML을 내보내고" 로컬 백업을 만드세요. 버전 기록을 모르더라도 로컬 복사본이 더 안정적입니다.
• 여러 사람 편집: 한 사람이 잠금을 잡고, 변경 사항을 저장하고, 잠금을 해제한 후 다음 사람이 가져갑니다. 병렬 변경을 하위 워크플로로 분할하세요.
• 주요 버전이 변경되기 전에 팀과 동기화하세요. 다른 사람들이 귀하의 모듈에 의존할 수도 있습니다.

11. 모니터링 및 경보

• 주요 워크플로의 실행 실패는 Slack/Feishu 알림과 연결되어 있습니다. 실패하면 즉시 알 수 있습니다.
• 데이터 대시보드를 정기적으로 확인하세요. 가장 비용이 많이 들고, 가장 느리고, 가장 자주 실패하는 워크플로는 무엇입니까? 최적화는 그것부터 시작됩니다.
• 한 달에 한 번씩 감사 로그를 확인하세요. 권한/자격 증명을 사용한 사람에 대한 예외가 있는지 확인하세요.

12. 워크플로 체크리스트를 완료했습니다.

1. 드라이런 통과
2. 성공적인 실행
3. 각 단계의 멱등성/재시도 전략이 확인됩니다.
4. 외부 부작용 이전에 manual_approval 또는 조건 명시적 제어가 있습니다.
5. 모든 자격 증명은 Credential Center에서 구문 분석되며 YAML에는 일반 텍스트 키가 없습니다.
6. cron/webhook가 연결되어 "다음 트리거 시간"을 확인했습니다.
7. 실패 알림 설정(적어도 Slack에 푸시 실행 실패)
8. 오프사이트 백업을 위해 YAML 사본을 git으로 내보내기

추가 자료 추천

• YAML 구문 참조 — 퍼지 필드는 정확하게 확인할 수 없습니다.
• 중단점 디버깅 — 복잡한 프로세스에서 문제를 찾는 도구
• 문제 해결 — 특정 증상 비교