Gemini Fullstack LangGraph Quickstart: A Reference App for Research Agents

What Problem This Quickstart Solves and Who It Is For

Building a research agent that actually works involves more than wiring a language model to a search API. The model needs to evaluate whether the results it retrieved are sufficient, generate follow-up queries when they are not, and eventually synthesize a cited answer from multiple sources. This repository demonstrates all of those steps in a single running application. It is aimed at developers who already understand LangGraph basics but want to see how a multi-step reasoning loop fits into a production-shaped project: a React frontend served by Vite, a FastAPI backend running the LangGraph agent, a Makefile for local development, and a Docker Compose file for production deployment. The README describes it as 'an example of building research-augmented conversational AI using LangGraph and Google's Gemini models,' which accurately describes the scope. It is a template, not a finished product.

The LangGraph Loop: Query Generation, Reflection, and Iterative Refinement

The core agent lives in backend/src/agent/graph.py. Its execution follows five stages. First, the agent generates initial search queries based on the user's input, using a Gemini model. Second, for each query, it calls the Google Search API through the Gemini model to retrieve relevant pages. Third, it analyzes the results to identify knowledge gaps. Fourth, if gaps exist, it generates follow-up queries and repeats the search and reflection stages, up to a configured maximum number of loops. Fifth, once the agent determines the research is sufficient, it synthesizes a coherent answer with citations from the gathered sources. The README calls this process 'reflective reasoning.' The key design choice is that the number of search rounds is not fixed: the agent decides when to stop based on its own assessment of the results. That makes the latency variable and the cost per query unpredictable without a hard loop cap.

Setting Up the Development Environment

The prerequisites are Node.js and npm (or yarn or pnpm), Python 3.11 or higher, and a Google Gemini API key. To set up the API key, navigate to the backend/ directory, copy backend/.env.example to create a .env file, and add your key:

cd backend
pip install .

For the frontend:

cd frontend
npm install

Once both are installed, start both servers together with:

make dev

This runs the frontend Vite dev server and the LangGraph backend concurrently. The README states the frontend is then available at http://localhost:5173/app and the backend API at http://127.0.0.1:2024. For one-off queries without the frontend, the repository also includes a CLI script:

cd backend
python examples/cli_research.py "What are the latest trends in renewable energy?"

This runs the LangGraph agent and prints the final answer to the terminal.

Running in Production: Redis, Postgres, and Docker

The development setup uses LangGraph's local dev server. Production is different. The README states that in production, LangGraph requires a Redis instance and a Postgres database. Redis is used as a pub-sub broker for streaming real-time output from background runs. Postgres stores assistants, threads, runs, thread state, long-term memory, and the background task queue. The included docker-compose.yml defines three services: langgraph-redis (Redis 6), langgraph-postgres (Postgres 16), and langgraph-api (the application itself). The API container uses the built image and listens on port 8123. To build and start the production stack:

docker build -t gemini-fullstack-langgraph -f Dockerfile .

GEMINI_API_KEY=<your_gemini_api_key> LANGSMITH_API_KEY=<your_langsmith_api_key> docker-compose up

The docker-compose example requires a LangSmith API key in addition to the Gemini key. The README notes that the frontend's apiUrl configuration in frontend/src/App.tsx must be updated if the backend is deployed to a host other than localhost.

Constraints and Cases Where This Template Breaks Down

The biggest operational constraint is the production dependency on both Redis and Postgres. A team that wants to deploy this as a lightweight demo will find they need to manage two additional stateful services. The variable loop count in the research agent means a single query could run many search rounds before finishing, which has direct cost implications for the Gemini API and Google Search API usage. The repository has no tagged releases and carries no versioned API contract, so if Google updates the LangGraph server base image or the Gemini SDK, the build may break without warning. The Dockerfile's constraint file reference (/api/constraints.txt) is provided by the base image, not the repository itself, which makes dependency resolution opaque. Finally, the project's architecture assumes the Google Search API is always available; it has no documented fallback for search failures.

LangGraph Standalone vs. This Fullstack Template

Running LangGraph directly with `langgraph dev` from a graph.py file gives a developer the LangGraph Studio UI and a local API endpoint without any frontend code. That approach is simpler, requires no npm installation, and is sufficient for testing agent logic in isolation. The difference with this repository is the React frontend: it provides a chat interface with hot-reloading for both sides during development and a production-grade build pipeline for the frontend that gets embedded into the Docker image. If the goal is to ship a user-facing product rather than test agent logic, this template covers the frontend-to-backend contract. If the goal is to iterate quickly on the research loop without a UI, using `langgraph dev` alone removes several moving parts and dependency surfaces. The Makefile in this repository shows the distinction clearly: `make dev-backend` runs `langgraph dev` in the backend directory, while `make dev-frontend` starts the Vite dev server in the frontend directory, and `make dev` runs both concurrently. A developer who only wants the backend can run either the Makefile target or the underlying langgraph command directly, bypassing the frontend entirely. The react frontend uses Tailwind CSS for styling and Shadcn UI for components, which introduces its own build configuration that teams unfamiliar with those tools will need to learn.

Licence and Maintenance

The project is licensed under Apache 2.0, which permits commercial use, modification, and distribution with attribution and preservation of the licence and NOTICE file. The last push to the repository was on 2026-06-14. That is approximately three and a half months before the date this article was written, which is within an active development window. The repository has no GitHub releases, which means there are no versioned snapshots to pin against. Developers adopting this template should track the main branch directly and monitor the LangGraph documentation for changes to deployment options, since the project depends on LangGraph's managed deployment model for its production architecture.

Editorial conclusion

Developers who want a working reference for a React plus LangGraph research agent and are comfortable provisioning Redis and Postgres in production will find the project structure immediately useful. Teams who want a minimal backend-only agent without a frontend should run `langgraph dev` directly instead. Verify that the LangGraph and Gemini SDK versions pinned in the backend/ directory are current before building on top of this template; the repository has no tagged releases and the last push was on 2026-06-14.

Frequently asked questions

Official sources

1. google-gemini/gemini-fullstack-langgraph-quickstart on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README