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:

Web Tools¶

• Web Search: Search the internet using providers like Google or DuckDuckGo.
• Fetch URL: Directly read the content of a specific webpage.

Filesystem Tools¶

• Read File: View the contents of a local file.
• 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.
• Write/Edit File: Create or modify local files.
• Search Files: Find files matching a specific glob pattern.
• Search Content: Search file contents using regex patterns with context lines support.

Utility & System Tools¶

• Calculator: Perform complex mathematical operations accurately.
• Python/Shell Execution: Run code or commands in a secure environment.
• System Info: Check CPU, memory, and hardware status.

Cross-Platform Shell Execution¶

The run_shell 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 (Auto-allowed)¶

Read-only operations like checking the time or searching documentation. These are usually 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/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.