Gemini Fullstack LangGraph Quickstart

The backend agent (defined in backend/src/agent/graph.py) performs iterative research using the following lifecycle:

1. Generate Initial Queries: Uses Gemini to create search terms based on user input.
2. Web Research: Uses the Google Search API via Gemini to find relevant web pages.
3. Reflection & Knowledge Gap Analysis: Analyzes results to see if information is sufficient or if gaps exist.
4. Iterative Refinement: If gaps are found, it generates follow-up queries and repeats the research (up to a configured maximum).
5. Finalize Answer: Synthesizes findings into a coherent answer with citations from web sources.

To run the application locally, you need Node.js, npm, and Python 3.11+.

1. Configure Environment Variables

Create a .env file in the backend/ directory by copying backend/.env.example. You must provide a Google Gemini API key:

GEMINI_API_KEY="YOUR_ACTUAL_API_KEY"

2. Install Dependencies

Backend:

cd backend
pip install .

Frontend:

cd frontend
npm install

3. Run Development Servers

You can start both servers simultaneously using make from the project root:

make dev

Alternatively, run them separately:

• Backend: In backend/, run langgraph dev. The API will be at http://127.0.0.1:2024.
• Frontend: In frontend/, run npm run dev. The UI will be at http://localhost:5173.

For production, the backend requires a Redis instance (for pub-sub streaming) and a Postgres database (for persistence and task queuing).

1. Build the Image

From the project root:

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

2. Run with Docker Compose

You will need a GEMINI_API_KEY and a LANGSMITH_API_KEY.

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

3. Access the App

• UI: http://localhost:8123/app/
• API: http://localhost:8123

Note on apiUrl: If you are not using the docker-compose.yml example or are exposing the server to the public internet, you must manually update the apiUrl in frontend/src/App.tsx.

• For docker-compose: http://localhost:8123
• For local development: http://localhost:2024

The web_research node uses the google.genai.Client directly rather than the standard LangChain client. This is because the native Google GenAI client provides access to grounding_metadata, which is essential for retrieving the actual URLs and sources used in the search.

When web_research is called, it:

1. Invokes the model with the google_search tool enabled.
2. Extracts grounding_chunks from the response.
3. Uses resolve_urls to map these chunks to usable URLs.
4. Uses get_citations and insert_citation_markers to ensure the generated text contains proper references to the sources.

The agent maintains state through a messages list. To continue a conversation or follow up on a previous answer, pass the existing message history along with the new user message to the graph.invoke method. This allows the agent to understand context from previous turns.

# Continuing a conversation using the previous state
state = graph.invoke({
    "messages": state["messages"] + [{"role": "user", "content": "How has the most titles? List the top 5"}]
})

You can execute the research agent directly from the command line for one-off queries using the provided example script.

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

The agent's behavior is controlled through a Configuration object passed via the LangGraph RunnableConfig. This allows users to customize the research process without changing the core logic. Key configuration parameters (accessible via Configuration.from_runnable_config(config)) include:

• query_generator_model: The model used for initial query generation.
• reflection_model: The model used to identify knowledge gaps.
• answer_model: The model used to write the final report.
• max_research_loops: The maximum number of times the agent will perform the research/reflection cycle.
• number_of_initial_queries: The number of search queries to generate in the first step.

Note: The agent requires the GEMINI_API_KEY environment variable to be set.

To use the backend agent, you must provide a valid Google Gemini API key. Set this in your .env file using the GEMINI_API_KEY environment variable.

GEMINI_API_KEY=

When running the langgraph-api service via Docker Compose, you must provide the following environment variables. These are injected from your host environment into the container:

• GEMINI_API_KEY: Your Google Gemini API key.
• LANGSMITH_API_KEY: Your LangSmith API key for tracing.

The service also uses internal connection strings for the database and cache:

• REDIS_URI: redis://langgraph-redis:6379
• POSTGRES_URI: postgres://postgres:postgres@langgraph-postgres:5432/postgres?sslmode=disable

environment:
  GEMINI_API_KEY: ${GEMINI_API_KEY}
  LANGSMITH_API_KEY: ${LANGSMITH_API_KEY}
  REDIS_URI: redis://langgraph-redis:6379
  POSTGRES_URI: postgres://postgres:postgres@langgraph-postgres:5432/postgres?sslmode=disable

The agent's output is stored in the messages list within the state. The most recent response from the agent is located at state["messages"][-1].content. You can use IPython.display.Markdown to render this content formatted as Markdown.

from IPython.display import Markdown

# Display the last message content as rendered Markdown
Markdown(state["messages"][-1].content)