# 9 Atomic Tools in GenericAgent: Complete Implementation Guide in ga.py

> Discover the 9 atomic tools in GenericAgent and their complete implementation in ga.py. Learn how to use code_run, ask_user, web_scan, file_patch, and more.

- Repository: [LJQ/GenericAgent](https://github.com/lsdefine/GenericAgent)
- Tags: how-to-guide
- Published: 2026-04-16

---

**The 9 atomic tools in GenericAgent are `code_run`, `ask_user`, `web_scan`, `web_execute_js`, `file_patch`, `file_write`, `file_read`, `update_working_checkpoint`, and `start_long_term_update`, implemented as `do_*` methods in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) spanning lines 296 to 508.**

The GenericAgent framework (`lsdefine/GenericAgent`) exposes a minimal, secure boundary between large language models and the host environment. All external interaction—whether executing code, manipulating files, browsing the web, or persisting memory—flows through nine immutable primitive operations defined in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py). These atomic tools ensure deterministic behavior and comprehensive auditability.

## Overview of the 9 Atomic Tools in GenericAgent

The toolkit divides naturally into five functional domains: **code execution**, **user interaction**, **browser automation**, **filesystem operations**, and **memory management**. Each tool is stateless and atomic, meaning it either completes entirely or fails without side effects, simplifying error recovery and retry logic.

| Tool | Domain | Core Purpose |
|------|--------|--------------|
| `code_run` | Execution | Run Python, Bash, or PowerShell with timeout and output streaming |
| `ask_user` | Interaction | Halt execution for human input with optional candidate selection |
| `web_scan` | Browser | Capture simplified HTML or tab lists from the controlled browser |
| `web_execute_js` | Browser | Inject and return arbitrary JavaScript execution results |
| `file_patch` | Filesystem | Atomic find-and-replace within a file using unique content blocks |
| `file_write` | Filesystem | Create, overwrite, append, or prepend entire files |
| `file_read` | Filesystem | Read with line ranges, keyword search, and memory-access logging |
| `update_working_checkpoint` | Memory | Write temporary working memory to guide immediate next steps |
| `start_long_term_update` | Memory | Trigger durable knowledge extraction and SOP updates |

## Implementation Details in ga.py

Each atomic tool maps to a `do_*` method inside [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py). The `GenericAgentHandler` class implements these methods between lines 296 and 508, with the dispatcher automatically stripping the `do_` prefix when routing LLM requests.

### code_run Implementation

The `do_code_run` method (starting at **line 296**) handles safe execution of arbitrary code snippets. It supports Python, PowerShell, and Bash, injecting timeout controls and streaming output capture. The implementation writes temporary files when necessary and references [`assets/code_run_header.py`](https://github.com/lsdefine/GenericAgent/blob/main/assets/code_run_header.py) for Python template initialization.

### ask_user Implementation

 Defined at **line 320**, `do_ask_user` constructs an interrupt payload that pauses the agent loop until the human operator responds. It supports optional candidate lists, forcing the user to select from predefined options rather than free-form input.

### web_scan Implementation

The `do_web_scan` method (line **327**) interfaces with the browser controller to retrieve simplified HTML snapshots. It can enumerate open tabs, switch to specific tab IDs, and return text-only content to reduce token consumption. The heavy lifting is delegated to [`simphtml.py`](https://github.com/lsdefine/GenericAgent/blob/main/simphtml.py).

### web_execute_js Implementation

At **line 342**, `do_web_execute_js` injects arbitrary JavaScript into the controlled browser context. It captures return values, execution errors, and DOM mutations. The method optionally persists the JS return value to a specified file path.

### file_patch Implementation

The `do_file_patch` method (line **370**) performs atomic in-place file modifications. It searches for a unique `old_content` block and replaces it with `new_content`, including safety checks for missing or ambiguous matches to prevent corrupted states.

### file_write Implementation

Starting at **line 384**, `do_file_write` handles whole-file operations: overwrite, append, or prepend. It accepts content via `<file_content>` tags or fenced code blocks and implements safe buffering for large writes.

### file_read Implementation

The `do_file_read` method (line **418**) provides flexible file access with optional line ranges (`start`, `count`), keyword search, and line-number display. It also logs memory-access events for files under the `memory` directory to track working set changes.

### update_working_checkpoint Implementation

At **line 447**, `do_update_working_checkpoint` writes to the agent’s temporary working memory. It stores `key_info` and `related_sop` references that influence the immediate next steps without persisting to long-term storage.

### start_long_term_update Implementation

The final tool, `do_start_long_term_update` (line **508**), initiates a durable memory distillation process. When the agent identifies valuable task knowledge, this method prepares a prompt for the LLM to extract permanent facts and updates the memory SOP files.

## How to Invoke the Tools: JSON Payload Examples

The `GenericAgentHandler` routes tool calls by stripping the `do_` prefix from method names. Below are the canonical JSON payloads the LLM emits to invoke each atomic tool.

Execute Python with timeout:

```json
{
  "tool_name": "code_run",
  "args": {
    "type": "python",
    "code": "print('Hello from GenericAgent')",
    "timeout": 30
  }
}

```

Request human input with candidates:

```json
{
  "tool_name": "ask_user",
  "args": {
    "question": "Which repository should I clone?",
    "candidates": ["repo1", "repo2", "repo3"]
  }
}

```

Capture browser state:

```json
{
  "tool_name": "web_scan",
  "args": {
    "tabs_only": false,
    "switch_tab_id": "tab-3",
    "text_only": true
  }
}

```

Inject JavaScript:

```json
{
  "tool_name": "web_execute_js",
  "args": {
    "script": "document.title",
    "save_to_file": "page_title.txt"
  }
}

```

Atomic file modification:

```json
{
  "tool_name": "file_patch",
  "args": {
    "path": "config.yaml",
    "old_content": "debug: false",
    "new_content": "debug: true"
  }
}

```

Write or append files:

```json
{
  "tool_name": "file_write",
  "args": {
    "path": "notes.txt",
    "mode": "append",
    "content": "<file_content>\nNew observation at $(date)\n</file_content>"
  }
}

```

Read with search and pagination:

```json
{
  "tool_name": "file_read",
  "args": {
    "path": "README.md",
    "start": 1,
    "count": 100,
    "keyword": "Installation",
    "show_linenos": true
  }
}

```

Update working memory:

```json
{
  "tool_name": "update_working_checkpoint",
  "args": {
    "key_info": "User prefers Chinese language output",
    "related_sop": "sop/translation.md"
  }
}

```

Trigger long-term memory consolidation:

```json
{
  "tool_name": "start_long_term_update",
  "args": {}
}

```

## Key Supporting Files

While [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) contains the tool implementations, several adjacent modules provide essential infrastructure:

- **[`agent_loop.py`](https://github.com/lsdefine/GenericAgent/blob/main/agent_loop.py)**: Defines the `BaseHandler` class and the orchestration loop that drives LLM-to-tool interaction, dispatching requests to the `do_*` methods in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py).

- **[`simphtml.py`](https://github.com/lsdefine/GenericAgent/blob/main/simphtml.py)**: Provides HTML simplification and JavaScript execution capabilities for the `web_scan` and `web_execute_js` tools, bridging the agent to the browser controller.

- **[`assets/code_run_header.py`](https://github.com/lsdefine/GenericAgent/blob/main/assets/code_run_header.py)**: Template header injected into temporary Python scripts executed by `do_code_run`, setting up safe execution contexts.

- **[`memory/global_mem_insight.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem_insight.txt)**: Static global memory context appended to prompts via `get_global_memory`, providing persistent SOP guidance across agent sessions.

## Summary

The 9 atomic tools in GenericAgent provide a complete, sandboxed interface between LLM reasoning and environmental interaction:

- **`code_run`**: Safe execution of Python, Bash, or PowerShell with timeout controls.
- **`ask_user`**: Interactive human-in-the-loop interrupt with optional candidate selection.
- **`web_scan`**: Browser state inspection and tab management via simplified HTML capture.
- **`web_execute_js`**: Arbitrary JavaScript injection with return value capture.
- **`file_patch`**: Atomic find-and-replace for safe in-place file modification.
- **`file_write`**: Whole-file write, append, or prepend operations.
- **`file_read`**: Flexible file reading with search, pagination, and line-number display.
- **`update_working_checkpoint`**: Temporary working memory updates for immediate context.
- **`start_long_term_update`**: Durable memory distillation and SOP persistence.

## Frequently Asked Questions

### What distinguishes the 9 atomic tools in GenericAgent from other agent frameworks?

The GenericAgent architecture treats these nine operations as indivisible primitives, ensuring that every environmental interaction flows through a single, auditable channel in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py). Unlike frameworks that expose broad API surfaces, GenericAgent restricts the LLM to these specific `do_*` methods (lines 296–508), enabling precise sandboxing and deterministic replay of agent actions.

### How does the `code_run` tool handle security and timeout constraints?

According to the [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) implementation starting at line 296, `do_code_run` enforces security through temporary file isolation and explicit timeout parameters. The method injects a safe header from [`assets/code_run_header.py`](https://github.com/lsdefine/GenericAgent/blob/main/assets/code_run_header.py) into Python executions, streams output back to the agent loop, and terminates processes that exceed the specified timeout, preventing runaway computations.

### What is the difference between `update_working_checkpoint` and `start_long_term_update`?

`update_working_checkpoint` (line 447) writes temporary context to the agent’s working memory for immediate tactical guidance, such as storing user preferences for the current session. In contrast, `start_long_term_update` (line 508) initiates a knowledge distillation process that extracts durable facts from the completed task and persists them to the memory SOP, affecting future agent behavior across sessions.

### Which files support the browser automation tools `web_scan` and `web_execute_js`?

While the tool definitions reside in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) (lines 327 and 342), the actual browser interaction logic relies on [`simphtml.py`](https://github.com/lsdefine/GenericAgent/blob/main/simphtml.py) for HTML simplification and JavaScript execution context management. Additionally, [`agent_loop.py`](https://github.com/lsdefine/GenericAgent/blob/main/agent_loop.py) provides the orchestration layer that handles the asynchronous callback structure when these tools interrupt the agent flow to communicate with the browser controller.