first-react-agent

A lightweight "Reason and Act" (ReAct) agent built with Node.js and Google Gemini. The agent can decide when it needs to use a tool, execute that tool locally, and then continue reasoning with the result before returning a final answer.

This repository is not a React frontend; it is a backend agent script that uses Gemini function calling with a math calculator and live web search capabilities.

Overview

The project demonstrates a simple agent loop:

1. Send a user prompt to Gemini.
2. Let the model decide whether it needs a tool.
3. Execute the requested tool locally (calculator or web_search).
4. Feed the tool output back into the chat.
5. Return the final answer generated by the model.

The implementation lives in:

• index.js — agent orchestration and tool schema configuration
• src/tools.js — calculator and Tavily search tool implementations

Features

• Gemini chat integration with function calling
• Safe arithmetic evaluation via a local calculator tool
• Live web search via Tavily API
• Environment-based configuration for API keys
• Basic tool loop that keeps calling functions until Gemini no longer needs them

Tech Stack

• Node.js
• JavaScript (ES modules)
• Google GenAI SDK: @google/genai
• dotenv for environment variables
• Tavily search API for live web results

Project Structure

first-react-agent/
├── index.js
├── package.json
├── README.md
├── src/
│   └── tools.js
└── .env

Prerequisites

• Node.js 18 or newer
• A Google Gemini API key
• A Tavily API key for the live web search tool

Setup

1. Install dependencies:

npm install

2. Create a .env file in the project root:

GEMINI_API_KEY=your_google_gemini_api_key
TAVILY_API_KEY=your_tavily_api_key

3. Run the agent:

node index.js

How It Works

Calculator tool

The calculator function accepts a mathematical expression, strips unsafe characters, and evaluates it safely with Function(...).

Example:

calculator("2 + 2")

Returns:

{ "result": 4 }

Web search tool

The web_search function sends a query to the Tavily search API and returns either:

• the direct answer from Tavily, or
• a combined summary of search result snippets

If the environment variable is missing, it returns a structured error message instead of crashing.

Example Usage

The script includes a default prompt:

await runAgent("What is the current population of Paris and what is that number multiplied by 5?");

This triggers:

• a web search for the current population of Paris
• a calculator call to multiply the result by 5
• a final answer generated by Gemini using the tool results

Notes

• The app relies on external APIs, so it will not work without valid API keys.
• The example prompt is hardcoded in index.js for demonstration purposes.
• There are no automated tests configured in the current project.

License

ISC