AI Agent

An intelligent AI coding agent powered by Google's Gemini API that can analyze, modify, and execute code projects autonomously.

Features

This AI agent can perform the following operations on code projects:

• List files and directories - Explore the project structure
• Read file contents - Get the content of any file
• Write files - Create or update files with new content
• Run Python files - Execute Python scripts with optional command-line arguments

Requirements

• Python 3.11 or higher
• Google Gemini API key

Installation

1. Clone the repository:

git clone https://github.com/nikhilww3/aiagent.git
cd aiagent

2. Install dependencies using uv (or your preferred package manager):

uv sync

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

cp .env.example .env

4. Add your Gemini API key to the .env file:

GEMINI_API_KEY=your_api_key_here

To get a Gemini API key, visit Google AI Studio.

Usage

Run the AI agent with a prompt:

uv run main.py "list files in the calculator directory"

Verbose Mode

Get detailed information about token usage:

uv run main.py "your prompt here" --verbose

Examples

# List all files in the project
uv run main.py "what files are in the root?"

# Read a specific file
uv run main.py "read the main.py file"

# Run a Python script
uv run main.py "run the tests in calculator/tests.py"

# Write a new file
uv run main.py "create a new file called example.txt with content 'Hello World'"

Project Structure

aiagent/
├── main.py                 # Main entry point for the AI agent
├── call_function.py         # Function calling handler
├── config.py               # Configuration settings
├── functions/              # Available tool functions
│   ├── get_files_info.py           # List files in a directory
│   ├── get_file_content.py        # Read file contents
│   ├── write_file.py               # Write/create files
│   └── run_python_file.py          # Execute Python files
├── calculator/             # Example project directory
│   ├── main.py            # Calculator application
│   ├── tests.py           # Calculator tests
│   └── pkg/
│       ├── calculator.py  # Calculator logic
│       └── render.py       # Output formatting
└── .env                    # Environment variables (create this file)

How It Works

1. Prompt Input: You provide a natural language request
2. Function Calling: The AI agent analyzes your request and decides which tools to use
3. Tool Execution: The agent executes the appropriate functions
4. Iterative Process: The agent can make multiple function calls in a loop (up to 20 iterations) to complete complex tasks
5. Result Display: The final result or file contents are displayed

Example Flow

When you ask "list files in the calculator directory", the agent:

1. Calls get_files_info() with the directory parameter
2. Executes the function and retrieves file listings
3. Displays the results

Working Directory

The AI agent operates within a working directory (default: calculator) for security reasons. All operations are restricted to this directory to prevent unauthorized access to system files.

You can change the working directory by modifying the working_directory variable in main.py or by setting the WORKING_DIRECTORY environment variable.

Available Tools

get_files_info(directory)

Lists all files and directories in the specified directory, showing file sizes and whether items are directories.

get_file_content(file_path)

Reads and returns the contents of a file (up to 10,000 characters).

write_file(file_path, content)

Writes content to a file, creating parent directories if needed.

run_python_file(file_path, args=[])

Executes a Python script with optional command-line arguments.

Development

Adding New Tools

To add a new tool function:

1. Create a function in the functions/ directory
2. Create a schema using types.FunctionDeclaration
3. Add the schema to available_functions in main.py
4. Add the function mapping to call_function() in call_function.py

Example:

# functions/my_tool.py
from google.genai import types

def my_tool(working_directory, param1):
    # Your tool logic
    return result

schema_my_tool = types.FunctionDeclaration(
    name="my_tool",
    description="Does something useful",
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "param1": types.Schema(
                type=types.Type.STRING,
                description="A parameter"
            ),
        },
    ),
)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Links

• Repository: https://github.com/nikhilww3/aiagent
• Google AI Studio: https://makersuite.google.com/app/apikey

Authors

• Nikhil Agarwal

---

Note: Make sure to never commit your .env file containing the API key. The .gitignore file is configured to prevent this.