혼자 공부하는 바이브 코딩 · 보충 자료

그래프 엔지니어링으로 AI 상담원 만들기

『혼자 공부하는 바이브 코딩 with 클로드 코드』 제7장 〈클로드 코드 AI 에이전트로 개발팀 구성하기〉 편을 마친 분들을 위해 보충 자료를 만들었습니다.

최근 주목받는 ‘그래프 엔지니어링’이란 각 에이전트간의 협업을 명시적으로 하게 하는 데 있습니다. 즉 에이전트에게 단순히 각각 할 일을 맡기는 것은 그냥 에이전트 방식, 여기에 다음에 뭘 할지를 에이전트가 스스로 정하고 반복 수행하게 한다면 루프 방식이 되지요. 그런데 이 다음 단계의 결정을 내부 에이전트가 아니라 미리 만든 밖의 코드가 한다면 이것은 그래프 엔지니어링이라는 방식이 됩니다.

이 두 방식의 가장 큰 차이는 다음 단계의 선택지를 내가 정의한 범위 안에서 하는가입니다.

루프 방식은 어디로 향할지 에이전트의 추론에 따라 정해지므로 미리 예측하기 어렵습니다. 하지만 그래프 방식은 이동 가능한 경로를 미리 정의하고 검토하며 책임질 수 있게 해줍니다.

이러한 사례를 예제와 함께 알아 보겠습니다. AI 상담원에게 환불을 요구하는 고객의 처리가 들어오면 이를 임의로 처리하지 않고 그래프 엔지니어링에 따라 반드시 사람의 승인을 구하는 AI 상담원 환불 모듈을 만들어 봅시다.

대화는 AI가, 결정은 사람이

먼저 그래프 방식을 이루는 주요 부품은 다음과 같습니다.

예를 들어 고객이 “ORD-1002 환불해 주세요, 사이즈가 안 맞아요”라고 입력할 경우 주문 조회 노드가 주문번호와 사유를 뽑고, 금액 확인이 금액을 주문 DB에서 조회한 뒤 조건으로 넘깁니다. 이때 미리 코드를 통해 정해진, 50만 원을 넘는지를 기준으로 자바스크립트 if 문이 다음 선택지를 판정하게 됩니다.

• 노드 5개 : 주문 조회 · 금액 확인 · 환불 처리 · 사람 승인 대기 · 환불 완료
• 엣지는 배열 하나 : [현재, 조건, 다음] 에 해당하는 배열
• 상태는 딕셔너리 하나 : 주문번호 → 금액 → 판정 → 결과. 노드를 지날 때마다 채워집니다.

준비

빈 폴더 하나

폴더에 마우스 오른쪽 버튼을 눌러 터미널에서 열기 > claude 를 입력해 시작합니다.

프롬프트

아래의 프롬프트를 차례로 입력합니다

1연습용 주문 데이터

먼저 예제에 쓸 주문 데이터를 만듭니다. 기준선인 50만 원보다 적은 주문과 많은 주문이 함께 있어야 나중에 경로가 갈라지는 것을 확인할 수 있습니다.

환불 상담 웹앱을 만들려고 해. 파일은 index.html 하나로만 구성하고,
외부 라이브러리는 사용하지 않고 순수 HTML과 자바스크립트로 작성해 줘.
연습용 주문 데이터는 코드 안에 네 건 넣어 주되,
50만 원보다 적은 주문과 많은 주문이 모두 포함되도록 해 줘.

2노드와 엣지 선언

화면보다 그래프를 먼저 만듭니다. 어떤 자리를 거치는지(노드)와 어디로 갈 수 있는지(엣지)를 배열 하나에 모아 두는 것이 시작입니다.

화면을 만들기 전에 그래프 구조부터 선언해 줘.
노드는 주문조회, 금액확인, 환불처리, 사람승인, 완료 다섯 개로 정의하고,
엣지는 [현재 노드, 조건 이름, 조건 함수, 다음 노드] 형태로 배열 하나에 모아 줘.
앱의 모든 흐름이 이 배열 하나만 읽으면 파악되도록 만들어 줘.

3판단을 조건 함수에

그래프 엔지니어링의 핵심입니다. “50만 원이 넘으면 사람에게”라는 규칙을 프롬프트가 아니라 조건 함수 안의 if 문에 둡니다.

결제 금액이 50만 원을 넘으면 사람승인으로, 그 이하면 환불처리로 이어지도록 연결해 줘.
이 기준은 AI에게 판단을 맡기지 말고, 엣지의 조건 함수 안에 if 문으로 직접 작성해 줘.
금액 역시 AI가 추측하지 않고 주문 데이터에서 조회해 가져오도록 해 줘.

4노드가 함께 쓰는 상태

노드들이 같이 들고 다니는 정보 꾸러미를 하나 둡니다. 노드는 이걸 채우기만 하고, 다음에 어디로 갈지는 정하지 않습니다.

state = { 주문번호, 금액, 사유, 판정, 결과 } 형태의 객체 하나를
모든 노드가 함께 사용하도록 만들어 줘.
각 노드는 state의 값을 채우는 일만 하고, 다음에 어느 노드로 갈지는 결정하지 않도록 해 줘.
다음 노드는 엣지 배열을 위에서부터 확인해 조건이 처음으로 맞는 줄을 따라가게 해 줘.

5흐름이 보이는 화면

이제 화면을 붙입니다. 상담이 진행될 때 그래프가 어느 자리를 지나는지 눈으로 따라갈 수 있게 합니다.

화면을 두 칸으로 구성해 줘. 왼쪽에는 상담 채팅을, 오른쪽에는 그래프 그림과 state를 보여 줘.
지금 실행 중인 노드와 이미 지나온 엣지에 색이 들어오게 해서,
상담이 진행되는 동안 어느 경로를 지나고 있는지 눈으로 따라갈 수 있게 만들어 줘.

6AI가 할 일은 해석까지

AI는 고객의 말을 알아듣는 데까지만 씁니다. 금액이나 승인 여부처럼 판단이 필요한 일은 맡기지 않습니다.

고객이 입력한 문장에서 주문번호와 환불 사유를 뽑아내는 데에만 AI를 사용해 줘.
결제 금액이나 승인 여부처럼 판단이 필요한 부분은 AI에게 묻지 않도록 해 줘.
API 키가 없는 환경에서도 동작해야 하니, 키가 없으면 정규식으로 대신 추출하게 해 줘.

7사람이 끼어드는 자리

50만 원이 넘으면 여기서 멈춥니다. 사람이 버튼을 누르면 멈춘 자리에서 이어서 실행됩니다.

사람승인 노드에 도달하면 실행을 멈추고 담당자의 판단을 기다리게 해 줘.
화면에 승인과 거절 버튼을 두고, 버튼을 누르면 멈춰 있던 자리에서 이어서 실행되도록 만들어 줘.

8두 갈래 확인

마지막으로 금액이 다른 두 주문을 각각 넣어, 경로가 실제로 갈라지는지 확인합니다.

50만 원보다 적은 주문과 많은 주문을 각각 입력해서 서로 다른 경로로 진행되는지 확인해 줘.
금액이 큰 쪽은 반드시 사람승인 노드에서 멈춰야 해.
의도한 대로 동작하지 않으면 정상적으로 동작할 때까지 계속해서 수정해 줘.

결과 보기

완성된 AI 상담원 환불 모듈

생성형 AI의 특성상 같은 프롬프트를 입력해도 결과는 조금씩 다르게 나올 수 있습니다. 아래 화면은 처음 만들어진 결과에 프롬프트를 몇 번 더해 UI를 조금 더 깔끔하게 다듬은 것입니다.

이미지를 누르면 완성본이 새 창에서 열립니다.

혼자 공부하는 바이브 코딩 · 보충 자료 · 그래프 엔지니어링