# 에이전트 워크플로우 사용 가이드

여러 에이전트가 **서로 일을 넘겨가며(핸드오프)** 하나의 작업을 완성하는 기능입니다.
예: 리서치 에이전트가 자료를 조사하고 → 작성 에이전트가 보고서를 쓰고 → 리뷰 에이전트가
검토해서 최종본을 내놓는 흐름을, 캔버스에 그려서 실행합니다.

> **워크플로우와의 차이**
> - **워크플로우**: 연결한 순서대로 모든 노드가 반드시 실행되는 파이프라인. 매번 같은 단계가
>   필요할 때(예: 기사 분석 → 키워드 추출 → 제목 생성).
> - **에이전트 워크플로우**: 에이전트가 상황을 보고 **다음 단계를 스스로 선택**. 결과에 따라
>   경로가 달라질 때(예: 리뷰가 미흡하면 작성으로 되돌리기).

---

## 핵심 개념 3가지

| 개념 | 의미 |
|---|---|
| **노드 = 에이전트** | 이름·설명·모델·프롬프트·도구·첨부문서를 가진 하나의 일꾼 |
| **연결(엣지) = 핸드오프 허용 경로** | A→B 연결은 "A가 일을 마치면 B에게 넘길 수 있다"는 뜻. 넘길지는 A가 판단 |
| **노드 설명 = 라우팅 힌트** | 넘기는 쪽 에이전트는 대상 노드의 **이름과 설명**을 보고 선택합니다. 설명을 구체적으로 쓸수록 정확하게 넘깁니다 |

시작·종료는 노드 옵션에서 지정합니다:
- **시작 노드**: 실행 입력을 받는 진입점 (워크플로우당 1개)
- **종료 노드**: 최종 결과를 출력하는 종착점. 결과가 만족스러우면 여기서 끝나고,
  수정이 필요하면 연결된 노드로 되돌릴 수 있습니다(리뷰 패턴)

---

## 예제 따라하기 — 리서치 · 작성 · 리뷰

**목표**: 주제를 주면 웹을 조사해 짧은 보고서를 만들고, 리뷰까지 마친 최종본을 받는다.

### 1. 만들기 시작
나의 에이전트 → **[에이전트 워크플로우]** → **[새 에이전트 워크플로우]**.
상단 제목을 "리서치 에이전트"로 바꿉니다.

### 2. 노드 3개 추가
하단 바의 **[에이전트 추가]**를 3번 누르고, 각 노드를 클릭해 오른쪽 설정 패널에서 입력합니다.

| | 노드 이름 | 역할 체크 | 노드 설명 | 프롬프트 | 관련 도구 |
|---|---|---|---|---|---|
| ① | ResearchAgent | ☑ **시작 노드** | 주제를 웹에서 조사해 핵심 사실을 정리 | 주어진 주제를 조사해 핵심 사실을 bullet 로 정리하세요. | ☑ web_search |
| ② | WriteAgent | — | 조사 내용으로 보고서 초안 작성 | 조사 내용을 바탕으로 구조화된 보고서를 작성하세요. | — |
| ③ | ReviewAgent | ☑ **종료 노드** | 보고서를 검토하고 최종본 확정 | 보고서를 검토해 승인하거나, 부족하면 수정을 요청하세요. | — |

모델은 노드마다 선택할 수 있습니다(비워두면 기본 모델).
⚠ **모든 노드는 같은 제공자(provider) 계열 모델**이어야 합니다 (예: 전부 OpenAI).

### 3. 연결
노드 **오른쪽 점(출력)** 을 다음 노드의 **왼쪽 점(입력)** 으로 드래그합니다.

```
ResearchAgent → WriteAgent → ReviewAgent
                WriteAgent ← ReviewAgent   (리뷰가 미흡하면 되돌리는 경로)
```

되돌리기(순환) 연결은 에이전트 워크플로우에서만 허용됩니다. 연결 상태는 노드 설정 패널의
**핸드오프 대상**에서 확인할 수 있습니다.

### 4. 저장 후 실행
상단 **[저장]** → 하단 실행 입력에 작업을 적고 **[실행]**:

> 전기차 배터리 재활용에 대한 짧은 보고서를 만들어줘

- 실행 입력은 **시작 노드**에게 전달됩니다. "무엇을 해달라"는 작업을 적으세요
  (에이전트의 역할 정의는 노드 프롬프트에 적는 것).
- 실행은 버튼으로만 됩니다. 입력창의 Enter 는 줄바꿈입니다.

### 5. 진행 확인 → 결과
- 실행 바 **바로 위 패널**에 현재 진행이 표시됩니다: 어느 에이전트가 뛰는지,
  도구 실행(🔧 web_search 실행 중…), 답변 타이핑, 핸드오프 이동까지 실시간으로 보입니다.
- 캔버스 노드에도 상태가 표시됩니다: 파란 테두리(실행 중) → 초록(완료).
- 완료되면 최종 결과가 **아티팩트 패널**(마크다운 문서 뷰)로 열립니다 — PDF 저장 가능.
  닫았다면 진행 패널의 **[결과 보기]**로 다시 열 수 있습니다.

---

## 실행 기록

- 실행할 때마다 **채팅 기록에 세션 하나**로 저장됩니다(제목 자동 생성, 🔀 아이콘).
  사이드바에서 클릭하면 입력/결과를 다시 볼 수 있습니다.
- 빌더 상단 **[기록]** 버튼은 이 워크플로우의 실행들만 모아 보여주며, 클릭하면
  결과가 아티팩트로 열립니다.
- 저장하지 않은(새) 워크플로우의 실행은 기록되지 않습니다 — 실험 후 저장하세요.

## 자주 걸리는 것들

| 증상 | 원인 / 해결 |
|---|---|
| "시작 노드를 정할 수 없습니다" | 노드 설정 → 역할에서 **시작 노드**를 1개 지정 |
| "같은 제공자 모델이어야 합니다" | 노드들의 모델을 한 계열(OpenAI 등)로 통일 |
| 엉뚱한 노드로 핸드오프됨 | 대상 노드의 **설명**을 구체적으로 (선택 기준이 됨) |
| 실행 버튼이 눌리지 않음 | 실행 입력(필수)이 비어 있음 |
| 특정 단계가 실행 안 됨 | 에이전트 워크플로우는 경로를 스스로 정합니다. 매번 전 단계 실행이 필요하면 **워크플로우**(파이프라인 모드)를 사용 |

## 팁

- **설명이 절반**입니다. 각 노드의 "노드 설명"은 다른 에이전트가 핸드오프 대상을 고르는
  기준이자, 그 노드 자신의 정체성으로 자동 주입됩니다.
- 참고 규정·양식이 있으면 노드의 **첨부문서**로 올리세요(파싱돼 프롬프트에 포함됩니다).
- 상단 모드 뱃지(⇄)를 누르면 워크플로우 ↔ 에이전트 워크플로우를 전환할 수 있습니다.
  그린 그래프는 유지됩니다.