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 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: Run one command per call inside the code execution sandbox folder (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.

Where Files and Commands Run¶

In an agent run, the file tools and the code execution tools start from the same folder:

• A run started without a working directory, with any file or code execution tool enabled, gets its own folder, runs/<run id>, inside the code execution sandbox folder. The sandbox folder is set in Settings > Tools & extensions > Python sandbox and defaults to code-exec-sandbox under the application data directory (on a headless server, the server account's data directory). Relative paths in write_file, read_file, create_directory, and the other file tools resolve against the run's folder, and run_command and run_python start in it. A run can therefore write main.c, run gcc main.c -o main, and then run ./main without naming a directory.
• When the session has permitted folders, the first one is the working directory. File tools use it, but run_command and run_python never run outside the sandbox folder, so they start at the top of the sandbox folder instead.

The run's folder is kept after the run ends, so its output stays available. Open the run's details to find its path under Working directory. Old run folders are not deleted automatically; remove them yourself when you no longer need them.

run_command runs one program per call and does not start a shell. Pipes (|), redirects (>, <), &&, ;, and command substitution are rejected, so a build that needs two steps takes two calls. Commands that change permissions or start a shell or interpreter (chmod, sh, bash, python, and similar) are blocked; use run_python for Python code. A working_directory outside the sandbox folder is refused, and the run's step shows the reason, for example working directory '/var/lib/aigo' is outside the sandbox root (...).

The ? next to Tool Permissions in the Cowork settings drawer summarizes these rules.

Tool Permissions¶

For your security, Backend.AI GO controls tool execution through a 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.