소속팀: Developer팀 작성자: 유수영
🧭 이 글에서 다루는 것
상담 AI는 질문을 받았다고 언제나 긴 답변을 만들어야 할까요? 이벤트를 찾는 화면에서는 정확한 후보 목록이 먼저 필요합니다. 기존 상담 Agent의 짧은 검색 그래프를 중심으로 상태, 분기, 오류 처리를 살펴봅니다. 사람의 검토와 실행 재개는 앞으로 적용할 수 있는 확장안으로 구분합니다.
| 읽는 순서 | 함께 살펴볼 질문 |
|---|---|
| 사용자 흐름 | 검색과 상세 답변을 왜 나눴을까? |
| 상태와 노드 | 다음 단계에 무엇을 넘겨야 할까? |
| 조건부 분기 | 어떤 요청을 검색 전에 멈출까? |
| 운영과 검증 | 실패한 단계와 재시도 범위를 어떻게 찾을까? |
1. 개요 — 상담사가 지금 필요한 결과부터 💬
“이번 달 온라인 쇼핑 혜택을 찾아주세요.” 상담 화면에서 이런 질문을 받으면 먼저 이벤트 후보를 보여주면 됩니다. 상담사는 제목과 기간을 보고 적절한 항목을 고릅니다. 그다음 할인 조건이나 제외 대상을 자세히 묻습니다.
기존 프로젝트 설계도 이 순서를 따릅니다. 첫 검색은 문서 목록을 돌려줍니다. 선택한 문서에 대한 상세 질문은 별도의 답변 경로로 보냅니다. 두 요청은 비슷해 보여도 사용자가 기대하는 결과가 다릅니다.
이 구분이 LangGraph 설계의 출발점입니다. 검색 단계에는 검색에 필요한 책임을 둡니다. 답변 생성이 필요한 시점에 모델을 호출합니다. 그래프의 크기보다 각 단계가 끝났을 때 무엇을 보장하는지가 중요합니다.
그림 1. 상담사의 후보 탐색과 상세 확인을 돕는 AI Agent. 이해를 위한 AI 생성 일러스트입니다.
1.1 이번 글의 범위
이 글은 기존 원고의 검색 그래프와 문서 묶음 기반 질의 구조를 바탕으로 합니다. 설명을 위해 코드의 이름과 데이터는 일반적인 예제로 바꿨습니다. 실제 서비스의 설정값이나 운영 성과를 재현한 예제는 아닙니다.
| 구분 | 이 글에서의 위치 |
|---|---|
| 검색 → 응답 구성 | 기존 설계의 중심 흐름 |
| 선택한 문서 묶음 → 모델 답변 | 기존 그래프 밖의 별도 경로 |
| 입력 정책 → 허용·차단 분기 | 적용 방법을 보여주는 확장 예제 |
| 사람의 검토 → 실행 재개 | 추가 설계가 필요한 확장 항목 |
Python 예제는 위에서부터 이어서 읽을 수 있게 구성했습니다. 검색기는 작은 대역 객체로 바꿔 실행합니다. 실제 검색 엔진과 LLM에 연결하지 않아도 노드의 책임을 확인할 수 있습니다.
2. 먼저 짧은 그래프로 시작하기 🧩
기존 검색 흐름은 두 노드로 끝납니다. 검색 노드가 후보를 모읍니다. 응답 노드는 목록과 함께 보여줄 안내 문구를 만듭니다.

그림 2. 위쪽은 검색 그래프, 아래쪽은 별도 상세 질의 경로입니다. 두 경로 사이에는 상담사의 문서 선택이 있습니다.
2.1 검색 화면에서 답변 생성을 분리한 이유
검색 카드에는 제목, 적용 기간, 간단한 설명이 필요합니다. 처음부터 여러 문서를 섞어 답하면 어떤 이벤트를 설명하는지 모호해질 수 있습니다. 상담사가 아직 고르지 않은 항목의 조건이 답변에 포함될 수도 있습니다.
| 사용자 행동 | 필요한 처리 | 화면에 보여줄 결과 |
|---|---|---|
| 혜택 후보 찾기 | 질의 정제와 검색 | 이벤트 목록과 건수 |
| 한 이벤트 선택 | 선택한 문서 묶음 조회 | 본문과 관련 조건 |
| 적용 조건 질문 | 선택 근거를 넣어 답변 생성 | 설명과 근거 표시 |
이렇게 나누면 평가 기준도 정리됩니다. 검색은 원하는 문서를 찾았는지 봅니다. 답변은 선택한 문서의 조건을 정확히 설명했는지 봅니다. 모델 호출을 줄이는 효과는 있을 수 있지만, 지연 시간은 실제 요청으로 측정해야 합니다.
2.2 작은 그래프에도 상태 계약이 필요하다
상태는 노드 사이에 넘기는 작업 메모에 가깝습니다. 사용자 질문, 검색 문서, 응답 문구를 같은 흐름에서 확인할 수 있습니다. 다만 모든 값을 자유로운 사전에 넣으면 누가 무엇을 바꿨는지 흐려집니다.
먼저 필요한 필드를 명시합니다. 아래 문서는 이벤트 하나를 대표하는 간단한 카드입니다. 상태 타입은 개발자가 구조를 이해하도록 돕습니다. TypedDict 자체가 요청값을 실행 시점에 검증해 주지는 않습니다.
|
from typing import Literal, TypedDict |
|---|
상태를 만들기 전에 API 경계에서 입력을 검증합니다. 공백뿐인 질문은 검색 엔진까지 보내지 않습니다. 검색 건수도 서비스가 감당할 범위로 제한합니다. 다음의 상한 20은 예제 정책이며 공통 권장값은 아닙니다.
|
from pydantic import BaseModel, ConfigDict, Field, field_validator |
|---|
💡 상태를 새로 만드는 일도 설계의 일부입니다. 이전 요청의 답변이나 오류를 다음 검색에 넘기지 않아야 합니다. 검증된 요청값과 서버가 만든 추적 식별자부터 채우면 출발점이 분명해집니다. 요청 검증 방식은 Pydantic 모델 문서에서 확인할 수 있습니다.
3. 검색 노드에는 무엇을 남길까? 🔎
기존 검색 노드는 질의 정제와 검색 조건 구성을 담당합니다. 대표 문서와 부속 문서를 묶어서 찾고, 최신성 기준도 적용합니다. 외부에서는 하나의 노드지만 내부 서비스에는 여러 작업이 있습니다.
| 검색 안에서 할 일 | 남기면 좋은 기록 |
|---|---|
| 질의 정제 | 정제 규칙 버전, 실제 검색에 사용한 질의 |
| 검색 조건 확정 | 적용한 건수, 기간, 점수 기준 |
| 문서 묶음 조회 | 대표 문서와 부속 문서의 연결 관계 |
| 최신성 보정 | 기간 정책, 정렬 규칙 버전 |
| 결과 반환 | 문서 묶음 식별자, 결과 개수 |
3.1 질문의 뜻을 바꾸지 않는 정제
“이번 달 행사”에서 날짜를 제거하면 검색 범위가 달라집니다. “제외 대상”을 지우면 포함 조건을 찾게 될 수도 있습니다. 질의 정제는 문자열을 짧게 만드는 작업만은 아닙니다. 원문과 검색용 질문을 구분해 보관하는 편이 좋습니다.
아래 예제는 연속 공백만 정리합니다. 기간 추출과 최신성 보정은 검색 서비스의 책임으로 남겼습니다. 대표 문서와 부속 문서를 합치는 실제 검색 구현도 생략했습니다. 노드가 무엇을 받고 무엇을 반환하는지에 집중하기 위해서입니다.
|
from typing import Protocol |
|---|
3.2 상태 전체를 수정하지 않고 변경분을 반환하기
예제는 입력 상태를 직접 고치지 않습니다. 검색이 끝나면 바뀐 필드만 반환합니다. LangGraph는 상태 필드별 갱신 규칙에 따라 이를 반영합니다. 별도 reducer가 없는 필드는 새 값으로 대체됩니다.
여기서 metadata는 사전 전체가 하나의 상태 필드입니다. 새로운 키 하나만 반환하면 기존 추적 식별자까지 사라질 수 있습니다. 그래서 기존 사전을 복사한 뒤 검색 정보를 더했습니다. 이 동작은 LangGraph 상태와 reducer 설명과 연결됩니다.
문서 본문을 documents와 metadata에 중복 저장할 필요는 없습니다. 예제에서는 본문은 문서 목록에, 개수는 메타데이터에 둡니다. 문서 개정과 검색 인덱스 버전도 함께 기록하면 나중에 결과를 비교하기 좋습니다. 단, 같은 상태라도 원본 인덱스가 바뀌면 검색 결과까지 같아지는 것은 아닙니다.
3.3 병렬 노드로 늘릴 때 달라지는 점
지금은 검색 다음에 응답을 만드는 순차 흐름입니다. 두 검색 노드를 동시에 실행하면 같은 필드를 함께 갱신할 수 있습니다. 이때는 필드를 분리하거나 병합 규칙을 명시해야 합니다. 단순히 문서 배열을 이어 붙이면 중복 문서와 순위 충돌이 남습니다.
4. 응답 문구도 사용자와의 계약이다 ✍️
상담사는 내부 예외 이름보다 지금 무엇을 할 수 있는지가 궁금합니다. 검색 결과가 없다면 조건을 바꿔 볼 수 있습니다. 검색 서버가 응답하지 않았다면 잠시 후 다시 시도해야 합니다. 두 상황을 같은 빈 목록으로만 보여주면 다음 행동을 고르기 어렵습니다.
기존 응답 노드의 역할은 그대로 유지합니다. 문서 개수에 맞춰 짧은 안내를 만듭니다. 여기에 오류 상태를 명확히 나누는 규칙을 더했습니다. 이 단계에서도 LLM 호출은 필요하지 않습니다.
그림 3. 노드는 작은 역할을 맡고, 연결은 전체 작업 순서를 표현합니다. AI 생성 일러스트입니다.
|
def format_response(state: AgentState) -> dict: |
|---|
이 함수는 검색 노드 뒤에서 실행한다는 계약을 가집니다. 입력이 ok, empty, error 중 하나로 정리된 상태를 기대합니다. 차단 응답은 뒤에서 살펴볼 별도 노드가 담당합니다. 이전 답변이 있더라도 이번 결과에 맞는 문구로 다시 만듭니다.
4.1 노드 두 개를 연결해 실행하기
그래프는 노드의 실행 순서를 정합니다. 검색기가 필요하면 생성 시점에 주입합니다. 대역 검색기와 실제 검색기를 바꿔도 그래프 구조는 유지할 수 있습니다.
|
from langgraph.graph import END, START, StateGraph |
|---|
4.2 상세 질문은 선택한 문서에서 출발한다
상담사가 이벤트를 고르면 문서 묶음 식별자를 상세 질의에 전달합니다. 기존 구조는 이 요청을 LangGraph 밖에서 직접 처리합니다. 문서가 이미 정해졌으므로 해당 묶음을 조회하고 답변 근거를 구성합니다. 새로운 벡터 검색은 이 경로의 필수 단계가 아닙니다.
- 인증 정보와 요청값을 확인합니다.
- 사용자가 선택한 문서 묶음을 볼 권한이 있는지 확인합니다.
- 대표 문서와 부속 조건을 함께 가져옵니다.
- 문서 제목과 출처를 유지하며 모델 입력을 구성합니다.
- 모델 답변에 근거를 연결해 반환합니다.
문서를 평탄화할 때는 제목과 적용 조건의 경계를 살립니다. 서로 다른 이벤트의 본문이 하나로 섞이면 답변 근거를 추적하기 어렵습니다. 문서 길이가 모델 입력 한도를 넘을 때의 처리도 정해야 합니다. 이런 정책은 그래프에 넣기 전에도 상세 질의 서비스가 책임져야 합니다.
5. 조건부 분기는 업무 규칙이 생겼을 때 🚦
이제부터는 기존 검색 그래프에 정책 검사를 더하는 확장 예제입니다. 입력 검사 결과가 허용이면 검색합니다. 허용되지 않으면 안내 문구를 반환하고 종료합니다. 문제가 생겼을 때 어디서 멈췄는지 한눈에 보이는 구조입니다.

그림 4. 향후 적용할 수 있는 정책 분기입니다. 현재 검색 그래프에 이미 배포된 기능을 뜻하지 않습니다.
5.1 분기 함수는 판단 결과만 읽게 한다
정책 검사는 input_guardrail이 담당합니다. 분기 함수는 검사 결과를 읽고 다음 노드 이름을 고릅니다. 검사와 이동 규칙을 분리하면 정책을 바꿨을 때 테스트 범위도 분명해집니다.
|
from collections.abc import Callable |
|---|
예제의 allowed에는 테스트용 함수를 넣을 수 있습니다. 운영에서는 업무 범위, 민감정보, 접근 정책에 맞는 판단기가 필요합니다. 단순한 금칙어 목록만으로 모든 위험한 요청을 잡을 수는 없습니다. 정책 검사 자체가 실패했을 때도 검색을 허용할지 별도로 정해야 합니다.
5.2 답변 생성까지 넣는다면
검색 이후에도 사용자가 목록만 원하는지, 설명까지 원하는지 구분합니다. 답변이 필요한 요청에만 생성 노드를 연결합니다. 생성 후에는 근거 누락이나 금지 표현을 점검할 수 있습니다. 검사 노드를 추가했다고 모든 부정확한 답변이 사라지는 것은 아닙니다.
| 추가 노드 | 도입할 만한 상황 | 함께 정할 기준 |
|---|---|---|
| 질의 분해 | 한 질문에 여러 업무 요청이 있음 | 분해 개수와 통합 방식 |
| 순위 보정 | 종료 이벤트나 업무 우선순위 반영 | 평가 질문과 적용 규칙 |
| 답변 생성 | 목록보다 설명이 필요한 요청 | 근거 범위와 입력 길이 |
| 출력 검사 | 근거 없는 조건 안내를 줄여야 함 | 보류와 재생성 기준 |
| 사람의 검토 | 자동으로 확정하기 어려운 안내 | 검토 권한과 만료 시간 |
6. 사람의 검토와 실행 재개는 별도 설계다 🤝
“확신 점수가 낮으면 상담사가 확인한다”는 문장은 쉽게 쓸 수 있습니다. 하지만 어떤 점수를 기준으로 삼는지부터 합의해야 합니다. 검색 유사도나 모델의 자기 평가는 정답 확률과 같지 않습니다. 근거 문서 부족, 조건 충돌처럼 설명 가능한 신호도 함께 봅니다.
LangGraph의 interrupt()는 외부 입력을 기다리는 흐름에 사용할 수 있습니다. 체크포인터와 thread_id를 준비하고, 같은 실행 맥락으로 재개합니다. 재개할 때는 Command(resume=…)로 검토 결과를 전달합니다. 이 기능의 사용 조건은 공식 Interrupts 문서에 설명되어 있습니다.
특히 중단된 노드는 재개 시 처음부터 다시 실행될 수 있습니다. 중단 전에 알림 발송이나 이력 저장이 있으면 중복 처리가 생길 수 있습니다. 쓰기 작업을 분리하고 요청 식별자로 중복을 막아야 합니다. 단순히 체크포인터를 붙이는 것만으로 업무 전체가 한 번만 실행되지는 않습니다.
6.1 식별자는 역할에 맞게 구분하기
| 값 | 예시 | 구분해야 하는 이유 |
|---|---|---|
| 상담 세션 | conversation-42 | 사용자의 대화 이력 묶음 |
| 문서 묶음 | EVENT-101 | 답변에 사용할 근거 묶음 |
| 그래프 스레드 | review-73 | 저장된 그래프 상태와 재개 대상 |
| 추적 식별자 | trace-demo | 한 요청의 노드별 실행 기록 |
| 사용자 식별자 | 서버에서 확인한 주체 | 조회와 검토 권한 판단 |
문서 묶음 식별자를 상담 세션 식별자처럼 재사용하지 않습니다. 스레드 식별자를 안다는 이유만으로 다른 사용자의 실행을 재개하게 해서도 안 됩니다. 서버에서 소유자와 업무 권한을 확인한 뒤 저장 상태에 접근합니다. 검토가 끝나지 않았을 때의 만료와 취소도 사용자 화면에 표현해야 합니다.
짧은 일회성 검색은 저장 상태 없이 실행할 수도 있습니다. 검토와 재개가 필요해질 때 저장 범위와 보존 기간을 정합니다. 체크포인터와 장기 저장소의 역할 차이는 Persistence 문서를 참고할 수 있습니다.
7. 느린 단계와 실패한 단계를 찾는 기록 🛠️
“답변이 늦어요”라는 말만으로는 원인을 찾기 어렵습니다. 검색이 느린지, 문서를 읽는 데 오래 걸렸는지 나눠 봐야 합니다. 모델이 호출되지 않은 검색 요청이라면 모델 지연부터 볼 이유도 없습니다. 요청 흐름에 맞춰 시간을 기록하는 것이 먼저입니다.
기존 글에서 강조한 관측 지점은 그대로 유효합니다. 질의 정제, 검색, 문서 묶음 조회, 순위 보정, 모델 호출을 구분합니다. 각 단계가 같은 추적 식별자를 공유하면 한 요청을 따라가기 쉽습니다. 실행하지 않은 단계는 기록에서 억지로 채울 필요가 없습니다.
그림 5. 실행 기록은 상담 화면의 문제를 처리 단계와 연결하는 단서입니다. AI 생성 일러스트입니다.
7.1 상태와 로그에 남길 값 구분하기
| 항목 | 상태에서의 용도 | 운영 기록의 용도 |
|---|---|---|
| 실제 검색 조건 | 다음 노드가 조건을 이해 | 같은 조건의 요청 비교 |
| 문서 묶음과 개정 | 근거 연결 | 어떤 자료를 참조했는지 확인 |
| 단계별 상태 | 다음 행동 결정 | 실패율과 빈 결과 비율 구분 |
| 소요 시간 | 필요 시 사용자 안내 | 병목 구간과 지연 분포 확인 |
| 정책 버전 | 분기 이유 보존 | 정책 변경 전후 비교 |
질문과 문서 본문을 무조건 로그에 복사하지는 않습니다. 민감정보를 가리거나 식별자만 기록하는 기준을 정합니다. 자세한 진단 정보는 접근 권한과 보존 기간이 정해진 저장소에 남깁니다. 이 구조는 OpenTelemetry의 trace와 span 개념으로도 표현할 수 있습니다.
7.2 빈 결과와 시스템 장애를 섞지 않기
| 상황 | 그래프의 판단 | 사용자에게 필요한 안내 |
|---|---|---|
| 검색 성공, 문서 0건 | empty | 검색어나 기간 조정 |
| 검색 의존성 일시 장애 | error | 잠시 후 재시도 |
| 업무 정책에 의한 거절 | blocked | 지원 범위 안내 |
| 잘못된 요청값 | 그래프 진입 전 검증 실패 | 수정할 입력값 안내 |
| 예상하지 못한 코드 오류 | 예외 전파와 서버 기록 | 일반 오류 안내와 추적 번호 |
검색 노드는 알려진 의존성 오류만 사용자 상태로 바꿉니다. 모든 예외를 빈 결과로 바꾸면 개발 오류까지 정상 처리처럼 보입니다. 원시 예외 메시지도 상담 화면으로 그대로 보내지 않습니다. 내부 주소나 연결 정보가 포함될 수 있기 때문입니다.
그래프의 상태값이 HTTP 응답 코드를 자동으로 결정하지는 않습니다. API 계층에서 오류 상태와 응답 규격을 연결해야 합니다. 일시 장애를 503으로 반환하는 식의 정책도 그 경계에서 정합니다. 이 구분은 FastAPI 오류 처리 문서와 함께 볼 수 있습니다.
7.3 재시도는 실패한 의존성에 가깝게
짧은 네트워크 단절은 제한된 횟수로 다시 시도할 수 있습니다. 입력 오류나 권한 거절은 같은 요청을 반복해도 해결되지 않습니다. 검색 어댑터와 그래프가 각각 재시도하면 총 호출 횟수가 늘어납니다. 한 요청의 시간 예산 안에서 횟수와 대기 시간을 함께 관리합니다.
헬스 체크가 정상이어도 실제 검색 요청은 실패할 수 있습니다. 운영 요청의 오류율과 지연 분포를 별도로 확인해야 합니다. 상담 이력 저장이나 외부 알림이 포함되면 재시도 시 중복 여부도 점검합니다.
8. 그래프 테스트는 결과와 경로를 함께 본다 ✅
검색기를 대역으로 바꾸면 문서 저장소 없이도 흐름을 검사할 수 있습니다. 응답 문구만 확인하면 잘못된 노드 호출을 놓칠 수 있습니다. 정책으로 차단된 요청이 실제 검색기를 호출하지 않았는지도 확인합니다. 아래 테스트는 앞의 타입과 함수를 그대로 사용합니다.
|
class EmptySearch: |
|---|
| 추가로 확인할 항목 | 놓치기 쉬운 문제 |
|---|---|
| 공백 질문과 과도한 검색 건수 | 잘못된 입력이 검색기까지 전달됨 |
| 기존 상태의 복사 여부 | 원본 상태가 의도치 않게 바뀜 |
| 추적 식별자 유지 | 메타데이터 갱신으로 이전 값이 사라짐 |
| 실패 후 다시 성공한 요청 | 이전 오류나 답변이 남음 |
| 허용된 요청의 분기 | 차단 경로만 테스트하고 정상 경로 누락 |
| 노드별 실행 순서 | 응답 구성이 검색보다 먼저 실행됨 |
노드 단위 테스트는 입력과 변경분의 계약을 확인합니다. 컴파일한 그래프 테스트는 실제 연결과 분기를 확인합니다. 이런 방식은 LangGraph 테스트 안내에서도 다룹니다. 실제 문서 검색 품질과 모델 답변 평가는 별도의 대표 질문 세트로 이어갑니다.
9. 결론 — 흐름이 읽혀야 고치기도 쉽다 🌱
기존 상담 Agent의 검색 그래프는 짧습니다. 검색하고, 결과를 정리하고, 끝냅니다. 상담사가 후보를 고르는 화면에는 이 정도의 책임이 잘 맞습니다. 상세 답변은 선택한 문서 묶음을 근거로 별도 경로에서 처리합니다.
이번에 보강한 부분은 그 경계를 더 분명하게 만드는 장치입니다. 상태의 필드를 정하고, 변경분을 반환하고, 빈 결과와 장애를 구분했습니다. 정책 분기 예제에서는 차단된 요청이 검색까지 가지 않는지 확인했습니다. 그래프가 커지기 전에도 충분히 필요한 점검입니다.
앞으로 업무가 늘어나면 질의 분해나 출력 검사를 추가할 수 있습니다. 사람의 검토가 필요하면 권한과 재개, 중복 처리까지 함께 설계합니다. 중요한 것은 노드 수가 아니라 사용자가 다음에 무엇을 할 수 있는지입니다. 그 질문에 답할 수 있는 흐름이라면 운영 중에도 설명하고 개선하기 쉽습니다.
10. 참조 출처 📚
- LangGraph Graph API — 상태, 노드, 엣지, 갱신 규칙.
- LangGraph Persistence — 실행 상태와 장기 정보 저장의 구분.
- LangGraph Interrupts — 외부 검토를 기다리는 중단과 재개.
- LangGraph Test — 노드와 그래프 검증 방법.
- LangChain Models — 별도 답변 경로에서 사용하는 모델 호출 개념.
- OpenTelemetry Traces — 요청과 처리 단계의 관측.
- FastAPI Handling Errors — API 경계의 오류 응답 구성.
- Pydantic Models — 요청값 검증과 타입 모델.
11. 태그
#상담AI #AIAgent #LangGraph #AgentState #Workflow #RAG #Guardrail #QueryRefinement #Observability #BundleSearch #사람의검토