GitHub - google-gemini/gemini-fullstack-langgraph-quickstart: Get started with building Fullstack Agents using Gemini 2.5 and LangGraph

이 프로젝트는 React 프런트엔드와 LangGraph 기반 백엔드 에이전트를 사용하는 풀스택 애플리케이션으로, 사용자의 쿼리에 대해 포괄적인 연구를 수행하도록 설계되었습니다. 이는 LangGraph와 Google Gemini 모델을 활용하여 연구 증강 대화형 AI를 구축하는 예시를 제공합니다.

주요 기능으로는 React 프런트엔드와 LangGraph 백엔드로 구성된 풀스택 아키텍처, LangGraph 에이전트를 통한 고급 연구 및 대화형 AI 기능, Google Gemini 모델을 활용한 동적 검색 쿼리 생성, Google Search API를 통한 통합 웹 연구, 지식 격차 식별 및 검색 개선을 위한 반성적 추론(reflective reasoning), 그리고 수집된 소스를 기반으로 인용(citation)을 포함한 답변 생성이 있습니다. 개발 중에는 프런트엔드와 백엔드 모두 핫 리로딩(hot-reloading)을 지원합니다.

프로젝트는 frontend/와 backend/ 두 개의 주요 디렉토리로 나뉩니다. frontend/는 Vite로 구축된 React 애플리케이션을 포함하며, backend/는 연구 에이전트 로직을 포함하는 LangGraph/FastAPI 애플리케이션을 담고 있습니다.

백엔드 에이전트의 핵심 방법론은 backend/src/agent/graph.py에 정의된 LangGraph 에이전트를 통해 구현됩니다. 이 에이전트는 다음과 같은 단계를 따릅니다:

초기 쿼리 생성 (Generate Initial Queries): 사용자의 초기 입력(질문)을 기반으로, Gemini 모델은 웹 검색에 적합한 초기 검색 쿼리(search queries) 세트를 동적으로 생성합니다. 이 단계는 LLM이 사용자의 추상적인 요청을 구체적인 검색어로 변환하는 역할을 수행합니다.

웹 연구 (Web Research): 생성된 각 쿼리에 대해, Gemini 모델은 Google Search API를 도구(tool)로 사용하여 관련 웹 페이지를 찾습니다. Gemini 모델은 검색 API 호출을 오케스트레이션하며, 검색 결과(예: 스니펫, 제목, URL)를 수집합니다.

반성 및 지식 격차 분석 (Reflection & Knowledge Gap Analysis): 수집된 검색 결과와 원래 사용자 쿼리를 입력으로 받아, Gemini 모델은 정보를 분석하여 충분한 정보가 수집되었는지, 모순되는 정보는 없는지, 또는 핵심적인 정보가 누락되었는지 판단합니다. 이 단계는 에이전트의 추론 능력을 활용하여 현재 정보 상태를 평가합니다.

반복적 개선 (Iterative Refinement): 만약 지식 격차가 발견되거나 정보가 불충분하다고 판단되면, Gemini 모델은 새로운 정보 획득을 위해 후속 쿼리(follow-up queries)를 생성합니다. 이 과정은 "웹 연구" 및 "반성" 단계로 다시 순환하며, 설정된 최대 반복 횟수(maximum number of loops)까지 반복됩니다. LangGraph는 이 반복적인 워크플로우의 상태 전환과 조건부 로직을 관리합니다.

답변 최종화 (Finalize Answer): 연구 과정이 충분하다고 판단되면, 에이전트는 Gemini 모델을 사용하여 수집된 모든 정보를 종합하여 일관성 있는 답변을 생성합니다. 이 답변에는 정보의 출처를 명확히 하기 위해 웹 소스로부터의 인용(citations)이 포함됩니다.

배포 시에는 Redis를 Pub/Sub 브로커로 사용하여 실시간 스트리밍 출력을 가능하게 하고, Postgres를 어시스턴트, 스레드, 실행 기록 저장, 스레드 상태 영속화(persist thread state), 장기 메모리(long term memory) 관리 및 백그라운드 태스크 큐 상태 관리에 사용합니다. docker-compose.yml 예제는 최적화된 프런트엔드 빌드와 백엔드 서버를 포함하는 Docker 이미지를 빌드하고 실행하는 방법을 보여줍니다.

이 프로젝트는 React (Vite), Tailwind CSS, Shadcn UI를 프런트엔드에 사용하고, LangGraph를 백엔드 연구 에이전트에, Google Gemini를 LLM으로 쿼리 생성, 반성, 답변 합성에 활용합니다.