MCP와 SSE 기반의 에이전트 워크스페이스 아키텍처를 구현하고 공유한 사례

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

글은 Model Context Protocol을 이용해 외부 도구를 런타임에 등록하는 아키텍처와 Server-Sent Events로 텍스트 토큰과 구조화된 JSON을 함께 스트리밍해 실시간으로 React 컴포넌트를 렌더링하는 설계를 중심으로 설명한다. 구현은 LangGraph 기반 ReAct 오케스트레이션, FastAPI 백엔드, Next.js 프런트엔드, FastMCP와 LangSmith 관찰성, MongoDB Atlas의 슬라이딩 윈도우 메모리로 구성되어 있으며 각 구성 요소가 어떤 역할을 하는지가 기술되어 있다. 인간 승인 흐름은 이메일 발송 같은 민감한 외부 액션을 그래프 실행을 일시 정지한 상태에서 승인 후 재개하는 방식으로 안전하게 처리하도록 설계되어 있다. 단일 SSE 스트림에서 토큰·툴 로그·구조화 UI를 조율하는 구현 난제와 LLM 출력의 이스케이프 문자로 인한 이메일 템플릿 문제 같은 실무적 한계가 명시되어 있다.

실용적 조언

동적 툴을 다루려면 MCP와 같은 런타임 등록 프로토콜을 적용하고, 오케스트레이션 로직을 툴 메타정보 기반으로 설계하면 새로운 도구 추가 시 핵심 로직을 변경하지 않을 수 있다.

섹션별 상세

동적 툴 디스커버리는 하드코딩된 도구 목록을 제거하고 런타임에 외부 도구 서버들이 MCP로 등록하는 방식으로 구현되었다. 에이전트는 MCP를 통해 각 도구의 메타정보와 호출 인터페이스를 수신하고 기존 오케스트레이션 로직을 변경하지 않고 새로운 기능을 즉시 사용 가능하게 만들었다. 글에는 GitHub REST API, Tavily Search, Yahoo Finance 같은 외부 서비스 예시가 명시되어 있어 설계 의도를 명확히 확인할 수 있다. 이 접근은 도구 확장이 증가할 때 아키텍처 유지비용을 낮추고 모듈화를 강화하는 효과를 낳는다.

생성형 UI는 동일한 SSE 연결에서 텍스트 토큰과 구조화된 JSON 페이로드를 함께 스트리밍하는 방식으로 구현되어 프론트엔드에서 실시간 React 컴포넌트로 렌더링되도록 구성되었다. 요청이 주식 데이터를 반환할 때 단순 텍스트 대신 상호작용 가능한 차트 컴포넌트를 응답으로 전달함으로써 사용자 경험을 대화형으로 전환했다. 이 설계는 Next.js 14와 SSE를 활용하여 서버에서 클라이언트로 진행중인 응답을 점진적으로 밀어주는 구조라는 구체적 구현 세부를 포함하고 있다. 결과적으로 응답이 배치 방식이 아닌 실시간 스트림처럼 체감되며 UX 일관성이 개선되었다.

스크린샷은 상호작용 가능한 응답 UI와 샘플 테이블, 입력창을 포함한 대화형 에이전트 인터페이스를 캡처하고 있다. — Screenshot이미지에는 'Sample Table of Top 5 GitHub Repositories' 같은 표와 요약 텍스트, 하단의 대화 입력 박스가 표시되어 있어 텍스트 응답과 구조화된 UI가 함께 렌더링되는 사례를 시각적으로 확인할 수 있다. 이 구성은 글에서 언급한 SSE를 통한 텍스트 토큰과 구조화 JSON의 동시 스트리밍이 실제 프런트엔드에서 어떻게 보이는지를 보여준다. 따라서 구현 결과물의 UX 측면 증거로 활용될 수 있다.

이메일 발송 액션에 대한 인간 승인 흐름은 에이전트가 HTML 이메일 초안을 생성하되 자동 전송을 차단하고 승인 UI가 완료될 때까지 그래프 실행을 일시 정지하는 방식으로 구현되었다. 에이전트가 마크다운을 HTML로 변환하고 템플릿을 적용한 뒤, 실제 외부 전송은 명시적 인간 허가가 있을 때만 수행되도록 설계되어 안전성을 확보했다. 구현 세부에는 승인 전까지 그래프의 진행 상태를 보존하고, 승인 후에 관련 도구 호출을 재개하는 상태 관리가 포함되어 있다. 민감한 외부 액션에 대한 규제 대응과 오용 위험 저감이라는 운영적 장점이 도출되었다.

상태 머신과 가드레일은 순환 그래프 형태로 다중 단계의 추론과 도구 호출을 관리하고, 도구 오류가 발생하면 재시도 및 폴백 경로로 복구하도록 구성되었다. 에이전트는 자신감 하락 시 대체 경로로 전환하거나 외부 확인을 요청하는 흐름을 통해 실패 모드를 완화하며, 이는 도구 통합이 많아질수록 일관된 오류 대응을 제공하는 방식이다. 글에서는 신뢰도 기반 폴백과 반복적 오류 처리 로직을 언급하여 운영 중 안정성 확보에 중점을 둔 점을 확인할 수 있다. 이런 구조는 복잡한 멀티스텝 작업에서 전체 워크플로의 복원력을 높이는 역할을 한다.

용어 해설

Model Context Protocol: — Model Context Protocol은 에이전트와 외부 도구가 런타임에 능동적으로 등록·교환할 수 있도록 설계된 프로토콜이다. 이 프로토콜은 도구의 메타정보와 사용 가능한 인터페이스를 에이전트에 전달하여 오케스트레이션 로직을 수정하지 않고 새로운 기능을 플러그인 방식으로 추가할 수 있게 한다. 동적 툴 디스커버리와 기능 확장이 필요할 때 아키텍처 복잡도를 낮추는 데 핵심 역할을 한다.
Server-Sent Events: — Server-Sent Events는 서버에서 클라이언트로 단방향 스트리밍을 지속적으로 전송하는 웹 표준 방식이다. 텍스트 기반 이벤트 스트림을 통해 토큰, 구조화된 JSON 페이로드, 로그를 동시에 밀어주어 실시간 UI 렌더링과 점진적 응답 처리를 가능하게 한다. 경량 스트리밍 구현으로 실시간 대화형 대시보드와 연동할 때 지연을 낮추는 이점이 있다.
ReAct: — ReAct는 행동(action)과 추론(reasoning)을 교차시켜 에이전트가 도구 호출과 내부 사고 과정을 통합하게 하는 프롬프트 패턴이다. 에이전트는 자연어 추론을 통해 다음 행동을 결정하고, 도구 호출 결과를 재입력으로 삼아 순차적 의사결정을 진행한다. 도구 사용이 빈번한 에이전트 설계에서 행동-사고 루프를 구조화하는 핵심 방법이다.
Human-in-the-Loop: — Human-in-the-Loop는 자동화된 결정 과정 중 특정 액션에 대해 인간의 명시적 승인을 요구하는 운영 패턴이다. 에이전트가 외부 시스템에 영향을 주는 작업을 수행하기 전에 승인 플로우로 실행을 보류하고 검토·승인·거부를 받아 안전성과 규정 준수를 확보한다. 외부 통합과 민감한 액션을 다룰 때 오용·실수 위험을 낮추는 보호막 역할을 한다.

언급된 도구

LangGraph추천

에이전트 오케스트레이션을 위한 그래프 기반 프레임워크로 ReAct 패턴과 통합되어 다중 스텝 플로우를 관리하는 용도이다

FastAPI중립

백엔드 API 서버 구현을 위한 경량 Python 프레임워크로 SSE 엔드포인트와 MCP 접속 지점을 제공하는 용도이다

Next.js 14추천

프론트엔드에서 SSE로 수신한 텍스트와 구조화 JSON을 실시간 React 컴포넌트로 렌더링하는 데 사용된 프레임워크이다

FastMCP추천

Model Context Protocol의 구현체로 외부 도구의 런타임 등록과 통신을 담당하는 미들웨어 역할이다

LangSmith추천

관찰성 도구로 에이전트의 로그·툴 호출·추론 토큰을 수집하고 트레이스하는 용도로 사용되었다

MongoDB Atlas중립

메모리 저장소로 슬라이딩 윈도우 컨텍스트를 TTL 30일로 유지하는 데 사용된 데이터베이스 서비스이다