3.2. Using Tools & Permissions¶

Tools are the "hands" of the agent. They allow the AI to interact with the outside world and perform actions.

Built-in Tools¶

Backend.AI GO comes with a suite of powerful built-in tools organized by category:

Filesystem Tools¶

• read_file: View the contents of a local file.
• write_file: Create or modify local files.
• list_directory: See what files are in a folder with metadata (size, modification time).
• create_directory: Create a new directory at the specified path, with optional recursive creation.
• delete_file: Remove a file from the filesystem.
• move_file: Move or rename a file.

Code Execution Tools¶

• run_command: Execute shell commands on the host system (platform-aware).
• run_python: Run Python code in a managed environment.

Web Tools¶

• fetch_url: Directly read the content of a specific webpage.
• web_search: Search the internet using Brave Search.

Search Tools¶

• search_files: Find files matching a specific glob pattern.
• search_content: Search file contents using regex patterns with context lines support.

Data Tools¶

• json_query: Query and transform JSON data using path expressions.
• csv_reader: Read and parse CSV files with filtering and column selection.

Utility Tools¶

• calculator: Perform complex mathematical operations accurately.
• getcurrenttime: Retrieve the current date and time.
• getsysteminfo: Check CPU, memory, and hardware status.

Cross-Platform Shell Execution¶

The run_command and run_python tools work across all supported platforms (Windows, macOS, Linux) with automatic platform-specific handling:

• Process Tree Management: When a command times out, all child processes are properly terminated (not just the main process).
  • Unix: Uses process groups (killpg)
  • Windows: Uses Job Objects for complete cleanup
• Environment Variables: Essential system variables are automatically passed to child processes:
  • Unix: HOME, PATH, LANG, LC_ALL
  • Windows: USERPROFILE, PATH, SYSTEMROOT, COMSPEC, TEMP, TMP
• Encoding: PYTHONIOENCODING=utf-8 is set on all platforms for consistent text handling.

Tool Permissions¶

To ensure your security, Backend.AI GO implements a robust permission system. Tools are categorized by their risk level:

Low Risk — Always Allow¶

Read-only operations like checking the time or searching documentation. These are executed without asking.

Medium Risk — Ask Once¶

Operations that access external data or write to temporary locations. The agent will ask for permission the first time it uses them in a session.

High Risk — Ask Always¶

Write operations to user-approved folders. The agent will ask for your explicit approval each time.

Critical Risk — Ask Always¶

Destructive actions (deleting files) or system-level access (running shell commands). The agent will always wait for your explicit approval before performing these actions.

Parallel Tool Execution¶

When an LLM requests multiple independent tools at once, Backend.AI GO executes them in parallel rather than sequentially. This significantly improves performance for complex tasks that require gathering information from multiple sources.

How It Works¶

• The agent detects when multiple tool calls are requested simultaneously.
• All independent tools are executed concurrently using parallel processing.
• Results are collected and returned to the LLM in the original request order.
• The UI shows all tools as "In Progress" during parallel execution.

Benefits¶

• Faster Results: A task requiring 5 tools that each take 1 second completes in ~1 second instead of ~5 seconds.
• Better Resource Utilization: Takes advantage of modern multi-core processors.
• Graceful Partial Failures: If one tool fails, others continue executing and succeed.

Approval During Parallel Execution¶

When a tool in a parallel batch requires approval:

• That specific tool waits for your approval while other tools continue.
• You can approve or deny each tool independently.
• The "Remember my choice" option works across parallel executions.

Granting Approval¶

When an agent needs to use a sensitive tool:

1. The execution will pause.
2. A Tool Approval Dialog will appear.
3. You can see the exact tool name and the arguments the agent wants to use.
4. Click Approve to proceed, or Deny to block the action.
5. You can also check "Remember my choice" for the duration of the current session.