Agent Chat UI가 “정확히” 뭐예요?
Agent Chat UI는 LangChain/LangGraph로 만든 AI 에이전트와 대화하기 위한 웹 채팅 UI(Next.js 앱)입니다. 일반 채팅 UI와 달리, 에이전트가 수행하는 툴 호출(tool call)과 툴 결과(tool result)를 대화 흐름 안에서 시각적으로 보여주고, 디버깅까지 돕는 것이 핵심입니다. Agent Chat UI가 특히 강조하는 기능은 다음입니다.
- 실시간 채팅(스트리밍)
- 툴 호출 시각화(에이전트가 어떤 툴을 어떤 인자로 호출했는지, 결과가 무엇인지)
- Time-travel debugging(대화 과거 지점으로 돌아가 확인/재실행)
- State forking(특정 시점에서 “분기”해서 다른 경로로 다시 실행)
한 줄 요약: “툴 쓰는 에이전트를 운영/디버깅하기 위해 만들어진 전용 채팅 UI” 입니다.
왜 굳이 “Agent 전용 UI”가 필요하죠?
일반 채팅 UI의 한계
일반 채팅 UI는 보통 질문/답변 텍스트만 다룹니다. 그런데 에이전트는 내부적으로 아래처럼 움직입니다.
- 사용자의 질문 → 계획/추론 → 툴 호출(검색/DB/티켓/배포 등) → 결과 해석 → 최종 답변
이때 운영/개발에서 제일 중요한 질문이 생깁니다.
- “왜 이 툴을 호출했지?”
- “어떤 파라미터로 호출했지?”
- “결과가 이상한데 어디에서부터 꼬였지?”
- “툴이 민감 데이터에 접근했나?”
Agent Chat UI는 이 흐름을 UI에 그대로 드러내서, 개발자는 디버깅이 빨라지고, 운영/보안팀은 감사/관찰이 쉬워집니다.
전체 구성요소
Agent Chat UI를 쓸 때 보통 시스템은 3층으로 나뉩니다.
- 프론트엔드: Agent Chat UI(Next.js)
- 에이전트 서버: LangGraph “Agent Server”(API로 에이전트 실행/스레드 관리)
- 툴/리소스: LLM + 내부 DB/검색/SIEM/티켓/Jira/Slack 등
문서에서는 로컬에서 langgraph dev로 에이전트 서버를 띄우면 API URL, Docs, Studio UI까지 제공된다고 안내합니다.
연결 방식 2가지(개발용 vs 운영용)
개발/POC: “브라우저가 에이전트 서버에 직접 연결”
- 빠르고 단순
- 단점: 운영으로 그대로 가면 키/인증/권한/로그 설계가 엉키기 쉬움
운영/프로덕션: “API Passthrough(프록시) 경유”
Agent Chat UI GitHub/문서에서 프로덕션은 API Passthrough를 쓰는 방식이 가장 빠른 productionize 방법이라고 안내합니다. DeepWiki 문서도 “Next.js API 프록시로 인증 처리 + 요청 전달” 구조를 설명합니다.
왜 프록시가 사실상 필수에 가깝냐?
- 브라우저에 민감 키(LLM 키, LangSmith 키 등)를 두지 않기 위해
- SSO/OIDC 붙이기 위해
- 사용자별 권한/스레드 격리/레이트리밋을 중앙에서 적용하기 위해
- 감사로그(누가 어떤 툴을 호출했는지)를 서버에서 남기기 위해
로컬에서 “처음부터” 붙여보는 전체 흐름 예시
LangGraph 서버 띄우기 (개발용)
LangChain 문서 기준으로 langgraph dev는 in-memory 모드로 Agent Server를 시작하며, 개발/테스트용이라고 명시합니다.
langgraph dev출력 예시로
- API:
http://localhost:2024 - Docs:
http://localhost:2024/docs - Studio Web UI:
https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
같은 정보가 뜬다고 안내합니다.
운영에서는 영속 스토리지 기반으로 배포하라고 문서에 분명히 적혀 있습니다.
Agent Chat UI 준비 (개념적으로)
Agent Chat UI는 “에이전트 서버”에 연결할 때 보통 아래 정보를 사용합니다.
- Deployment URL: LangGraph 서버 URL(예:
http://localhost:2024) - Graph ID:
langgraph.json에 정의된 그래프 이름(환경에 따라 assistant/graph 식별자) - (필요 시) LangSmith API Key
위 값들은 문서에서 “로컬/배포 에이전트에 연결할 수 있고, 연결 후 툴 호출/결과를 기본 렌더링”한다고 설명하는 흐름과 맞습니다.
“툴 호출 시각화”가 실제로 왜 유용한지: 구체 시나리오
시나리오: “보안 이벤트 요약 에이전트”
에이전트가 아래 툴을 가진다고 가정해볼게요.
search_siem(query, start, end): SIEM에서 이벤트 검색get_asset(hostname): 자산관리에서 호스트 정보 조회create_ticket(title, body, severity): 티켓 생성
사용자가 이렇게 물어요
“어제(24시간) SSH 로그인 실패가 급증한 서버와 원인 후보를 요약하고, 심각하면 티켓도 만들어줘.”
에이전트 내부 흐름(일반적인 패턴)
search_siem("ssh AND failed", start=..., end=...)- 결과에서 top host/IP/user 집계
- 상위 호스트에 대해
get_asset(hostname)로 소유팀/중요도 확인 - 심각도 높으면
create_ticket(...) - 사용자에게 요약 + 조치 권고
Agent Chat UI에서 “보이는 것”
- 툴 호출 블록이 순서대로 나타남
- 어떤 쿼리/시간범위로 SIEM을 조회했는지
- 어떤 hostname을 자산조회 했는지
- 티켓을 어떤 severity로 만들었는지
- 결과가 예상과 다를 때 “어느 단계의 결과가 이상했는지”를 바로 추적 가능
이게 바로 문서가 말하는 tool visualization + debugging의 실전 가치입니다.
운영(프로덕션)에서 “반드시” 챙겨야 할 핵심: API Passthrough
Agent Chat UI GitHub에서는 “프로덕션화의 가장 빠른 방법은 API Passthrough 패키지를 쓰는 것”이라며, LangGraph 서버로의 요청을 프록시하고 인증을 처리하는 형태를 안내합니다. DeepWiki도 동일하게 “Next.js API proxy가 인증과 요청 전달을 맡는 구조”를 설명합니다.
프로덕션 권장 구조(개념)
- 브라우저 → (SSO 인증된) Next.js API → LangGraph 서버
- Next.js API는
- 사용자 인증/권한 확인
- 서버측 토큰/키로 LangGraph 서버 호출
- 스트리밍 응답을 그대로 전달
- 감사 로그 남김
점검 포인트
인증/권한(최우선)
- 브라우저에 LLM/LangSmith 키를 입력하게 두지 않기
→ 프록시에서 서버측으로만 보관(권장) - 사용자별 스레드/대화 기록 접근 통제
- Graph(에이전트)별 접근 권한 분리
데이터 유출(DLP)
- 프롬프트/툴 결과에 민감정보 포함 가능
- 마스킹 정책(예: 계정/키/개인정보)
- 저장 시 암호화/보존기간/권한
- 로그에 원문 결과를 그대로 남길지(위험) vs 요약만 남길지(절충) 정책화
툴 오남용/프롬프트 인젝션
- 툴 파라미터 allowlist(접근 가능한 인덱스/프로젝트/호스트 범위 제한)
- 고위험 툴(삭제/배포/권한변경)은 “사람 승인(interrupt)” 단계 강제
- 외부 URL fetch가 있으면 SSRF 방지(사설 IP/메타데이터 IP 차단)
감사/추적(Incident 대응)
- “누가/언제/무슨 요청” + “어떤 툴을 어떤 인자로 호출” + “결과 요약”을 표준 로그 필드로 설계
- SIEM 연동(HTTP access log + app log + tool audit log)
LangSmith 인증/접근제어를 같이 고려할 때
LangSmith 문서에는 AuthN(인증) / AuthZ(권한) 개념과 통합 가능한 접근 제어 체계를 설명하고, 커스텀 인증 가이드를 별도로 제공합니다. 단, “LangGraph 오픈소스 라이브러리만 단독으로 쓰는 커스텀 서버”와 LangSmith 플랫폼 적용 범위는 문서 설명을 따라 구분해서 설계해야 합니다.
추가로 이어질 주제
로컬 POC 구현 예시
- LangGraph 에이전트 샘플(툴 2~3개) + Agent Chat UI 연결
- “SIEM 조회 + 티켓 생성” 같은 현실적인 예시를 기준으로
(1) LangGraph 에이전트 코드 뼈대(개념/구조) → (2) 로컬 langgraph dev로 띄우기 → (3) Agent Chat UI에서 연결 → (4) 툴 호출이 UI에 어떻게 보이는지
프로덕션 프록시 예시
- Next.js API Passthrough 구현(SSO 헤더 검증, rate limit, 감사로그)
보안 가드레일 예시
- 툴 allowlist / 사람 승인(interrupt) / SSRF 방지 / DLP 마스킹
댓글