pyagent

An experimental, just-for-fun AI agent with a feedback loop. It can call a small set of tools to work with files and run Python scripts on UNIX-like systems.

Important notes:

• Not error-proof. Expect rough edges.
• Supports only UNIX-like systems (Linux, macOS). No Windows support.

What can it do?

pyagent exposes four simple tool functions to the AI agent:

1. List files in a directory (with basic info)
2. Get the content of a file
3. Write to a file
4. Run a Python file

These are implemented in the functions/ package and wired through a function-calling layer used by the agent loop.

How it works (at a glance)

• The main feedback loop lives in main.py. It uses Google GenAI to plan and call the available tools.
• Tool routing happens in functions/call_function.py which maps the model’s function calls to concrete Python functions.
• The four functions are:
  • functions/get_files_info.py — list directory entries
  • functions/get_file_content.py — read a file
  • functions/write_file.py — write/append to a file
  • functions/run_python_file.py — execute a .py file and capture output

There is also a small sample project under calculator/ that the agent can interact with.

Requirements

• Python 3.10+
• UNIX-like OS (Linux, macOS). No Windows support.
• A Google GenAI API key configured in your environment (see config.py for how environment variables are read).

Setup

Using uv (recommended):

# Ensure you have uv installed: https://github.com/astral-sh/uv
uv venv
uv pip install -r pyproject.toml

Using pip:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Set environment variables (see config.py for exact names). A typical setup includes:

export GOOGLE_API_KEY="your_api_key"

Run

From the project root:

python main.py

By default, the agent is configured to operate within the calculator/ directory when using its tools. You can explore or modify that behavior in functions/call_function.py and the tool implementations.

Usage ideas

• Ask the agent to list files in calculator/.
• Have it read calculator/pkg/calculator.py.
• Request changes to a file via the write tool.
• Run calculator/main.py and review the output.

Example tool intentions the agent might emit (simplified):

• get_files_info: {"path": "calculator"}
• get_file_content: {"path": "calculator/pkg/calculator.py"}
• write_file: {"path": "calculator/notes.txt", "content": "Hello"}
• run_python_file: {"path": "calculator/main.py"}

Limitations & disclaimers

• This is a toy project; no guarantees of safety, robustness, or correctness.
• No sandboxing. Running arbitrary Python files can be dangerous. Only run trusted code.
• Limited to UNIX-like systems; paths and process handling assume POSIX semantics.
• The agent can make mistakes; always verify its changes.

Project layout

• main.py — entry point with the agent loop
• config.py — configuration and environment variable handling
• functions/ — tool implementations and routing
• calculator/ — example project the agent can manipulate