An agent is a graph

개요

Claudius 챗봇 개발 시리즈의 네 번째 글에서는 '에이전트(agent)는 그래프'라는 관점에서, 사용자가 메시지를 전송한 시점부터 응답 토큰이 화면에 도착하기까지 발생하는 실시간 대화 처리 과정을 상세히 설명한다.

주요 내용

• 그래프 기반의 챗 엔진: 챗 엔진은 단순히 프롬프트로 모델을 감싸는 단일 호출이 아니라, LangGraph로 구축된 작은 상태 머신(state machine)이다. 이 그래프는 load_context, agent, tools 세 개의 노드로 구성되며, 모델이 도구를 호출하면 tools 노드로 이동하고, 단순 응답이면 종료된다. tools 노드는 항상 agent 노드로 되돌아가는 루프를 형성하여 작업 완료 시까지 반복된다.
• 실행 시점별 모델 선택: 모델은 그래프 생성 시점에 고정되는 것이 아니라, 실행 시점(per run)에 LangGraph의 설정 가능한 채널(configurable channel)을 통해 결정된다. agent 노드는 매번 최신 추론 프로필(inference profile)을 읽어 새 모델 클라이언트를 구성하므로, 대화 중간에도 모델 전환이 용이하다.
• 모델 전환의 용이성: 대화 기록은 변경 없이 유지되며, 다음 턴에서 다른 추론 프로필을 읽어 다른 클라이언트를 구성하는 방식으로 모델 전환이 이루어진다. 이는 그래프 재구축이나 체크포인트 마이그레이션 없이 즉시 반영된다.
• 예측 가능한 단일 도구 형태: web_search 도구는 Tavily API를 래핑하며, title, url, snippet 세 가지 필드만 반환한다. 이러한 예측 가능한 출력 형태는 외부 서비스 변경 시에도 코드 수정 범위를 최소화하며, 시스템 전체가 특정 벤더의 응답 형식에 의존하는 것을 방지한다.
• 이벤트 갭(Event Gap) 브릿징: LangGraph의 streamEvents 인터페이스에서 발생하는 평탄한 이벤트 로그를 Vercel AI SDK가 기대하는 UI 메시지 파트(message parts) 스트림으로 변환하는 계층이 존재한다. 이 변환 계층은 상태 머신으로, 모델 토큰, 도구 시작/종료 등 LangGraph 이벤트를 text-start, text-delta, text-end, tool-input, tool-output 등의 AI SDK 파트로 변환한다.
• 실시간 사용자 경험 제공: 이러한 구조를 통해 응답 토큰이 도착하는 대로 화면에 애니메이션으로 표시되어 기다리는 대신 점진적으로 구축된다. 또한, 에이전트가 웹 검색을 수행하면 "Searching the web"이라는 메시지가 나타나고, 결과가 반환되면 도구가 찾은 소스 목록으로 표시되어 사용자가 에이전트의 작업을 투명하게 확인할 수 있다.
• 대화 기록 전송 방식: 클라이언트는 마지막 메시지만 전송하며, 이전 대화 전체 기록은 서버에 저장되어 모델이 매 턴마다 이를 읽는다.

시사점

에이전트를 그래프로 모델링하고 실행 시점별 모델 선택 및 이벤트 스트림 변환을 통해 동적인 대화 처리와 실시간 UI 업데이트를 가능하게 하며, 사용자는 에이전트의 내부 작동 과정을 투명하게 이해할 수 있다.