ai-agent

An AI coding agent powered by Google's free genai tier. It uses tool-calling to safely interact with a sandboxed working directory and help with coding tasks like listing files, reading and writing files, and running Python scripts.

By default, the agent operates inside the sandbox directory ./calculator (see WORKING_DIR in functions/call_function.py). This protects your broader filesystem while still giving the model useful capabilities.

What it can do

• List files and directories (with sizes and type)
• Read file contents (with size limits)
• Write/overwrite files
• Execute Python files with optional CLI-style arguments

All file paths the agent uses must be relative to the sandbox working directory.

Requirements

• Python 3.12+
• A Google Generative AI API key in your environment
  • Create a .env file at the project root with:
    • GEMINI_API_KEY=your_api_key_here
• Dependencies (declared in pyproject.toml):
  • google-genai==1.12.1
  • python-dotenv==1.1.0

This repo includes a uv.lock and a .venv/ (optional) if you prefer using [uv]. You can also use plain pip.

Install

Choose one of the following:

Using pip

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -U pip
pip install -e .

Using uv (I created my project this way)

uv venv
./.venv/Scripts/Activate.ps1
uv pip install -e .

Run the agent

The main entry point is main.py. Pass a natural-language prompt; add --verbose for debug traces.

python main.py "List the files in the project" --verbose

Behind the scenes, the model gemini-2.0-flash-001 can decide to call one or more tools. Tool calls are executed locally and their results are fed back to the model until it produces a final answer or hits the iteration limit.

Important path note

All tool operations run relative to the sandbox directory: calculator/. For example, asking the agent to read pkg/calculator.py refers to calculator/pkg/calculator.py on disk.

Examples

• List files in the sandbox

  • Prompt: "List the files in the working directory."
  • Tool: get_files_info with directory: "."

• Read a file

  • Prompt: "Open pkg/calculator.py and summarize the evaluate method."
  • Tool: get_file_content with file_path: "pkg/calculator.py"

• Run a Python script

  • Prompt: "Run main.py in the calculator with the expression 3 + 5."
  • Tool: run_python_file with file_path: "main.py", args: ["3 + 5"]

• Write a new file

  • Prompt: "Create a notes.txt file saying hello from the agent."
  • Tool: write_file with file_path: "notes.txt", content: "hello from the agent"

Project structure

ai-agent/
	main.py                 # Agent entrypoint
	pyproject.toml          # Project metadata and deps
	functions/              # Tool implementations and schemas
		call_function.py      # Dispatch + WORKING_DIR = ./calculator
		get_files_info.py     # list files
		get_file_content.py   # read files
		write_file.py         # write files
		run_python_file.py    # run Python scripts
	calculator/             # Sandbox working directory used by the agent
		main.py               # Simple CLI calculator ("3 + 5")
		pkg/                  # Calculator logic and helpers
			calculator.py
			render.py

How it works

• main.py starts a chat with the model and exposes a tool set via function declarations.
• When the model chooses a tool, the call is dispatched by functions/call_function.py.
• Results are returned to the model and the loop continues up to a max iteration count.
• Guardrails enforce that any file path stays inside ./calculator.

Calculator sandbox (quick start)

You can also run the calculator directly without the agent:

python calculator/main.py "3 + 5"

Example output:

{"expression": "3 + 5", "result": 8}

Development

Add a new tool:

1. Create a module in functions/ that exports:
   • An implementation like def my_tool(working_directory, ...) -> str
   • A schema_my_tool = genai_types.FunctionDeclaration(...)
2. Register it in two places:
   • functions/call_function.py: add to func_table
   • main.py: add the function schema to available_functions
3. Keep all paths relative to working_directory and enforce the guardrail checks.

Debugging:

• Use --verbose when running the agent to see each iteration and tool call.
• Tool errors are returned as strings and surfaced to the model and console.

Environment

• Put your API key in .env at the project root:

GEMINI_API_KEY=your_api_key_here

Testing

• tests.py contains quick, manual checks used during development. It is not a formal unit-test suite.
• You can adapt these snippets or wire up pytest if you want automated tests.

License

No license specified.