Files
shumai/docs/using-shumai/agent-tools.mdx
T
Yiling-J 8c1e59d131 feat(agent): add asset management tools and CLI commands (#387)
* feat(agent): add asset management tools and CLI commands

* fix(core): resolve code review findings for reparenting cycles, agent deniedTools update, and CLI folder delete
2026-09-06 17:15:58 +08:00

89 lines
4.6 KiB
Plaintext

---
title: Agent Tools
description: Configure the tools and capabilities permitted for each agent.
---
Shumai agents are equipped with built-in tools that allow them to interact with the file system, view files, extract video frames, and execute commands.
By default, most tools are enabled for new agents, while sensitive or destructive tools (such as **Delete Asset**) are disabled by default. Team Owners can toggle specific tools to customize agent capabilities.
<Warning>
**Caution:** Disabling tools can cause agents or skills to fail. For example, disabling the
**Sandboxed Terminal** tool will break almost all custom skills that rely on executing commands or
script environments. Disable tools only when you have a specific security policy or isolation
requirement.
</Warning>
---
## Available Tools
The following tools can be individually toggled in the agent configuration dialog:
### 1. Sandboxed Terminal (`bash`)
- **Description:** Allows the agent to run terminal/shell commands in a highly isolated environment.
- **Why it matters:** Essential for running custom scripts, processing files on disk, or using standard Unix utilities. If disabled, the agent won't be able to run command-line code.
### 2. Read Skills (`read_skill`)
- **Description:** Allows the agent to load and read skill definitions to perform specialized actions.
- **Why it matters:** Enables the agent to inspect the instructions/configurations of custom skills registered in your workspace before executing them.
### 3. Read Asset (`read_asset`)
- **Description:** Allows the agent to inspect images, extract still frames from video files, render PDF document pages, and read text/markdown documents.
- **Why it matters:** Enables multimodal agents to view visual media assets uploaded to Shumai, extract frame-by-frame video screenshots, inspect document layouts, and answer questions about uploaded creative assets.
### 4. Browse Shumai (`list_assets`)
- **Description:** Allows the agent to list folders and browse files in Shumai.
- **Why it matters:** Gives the agent visual mapping of the project structure so it can search for other files or locate related assets.
### 5. Create Folder (`create_folder`)
- **Description:** Allows the agent to create new folders in Shumai.
- **Why it matters:** Needed if the agent organizes outputs or places files in custom subdirectory folders.
### 6. Create File (`create_file`)
- **Description:** Allows the agent to create and upload new files to Shumai.
- **Why it matters:** Allows the agent to generate new assets (e.g. text logs, transcoded clips, reports) and save them directly back into your project.
### 7. Create Version (`create_version`)
- **Description:** Allows the agent to upload and stack a new version of an existing file in Shumai.
- **Why it matters:** Allows the agent to update files in a clean, non-destructive way by stacking revisions rather than creating duplicate files.
### 8. Download Asset (`download_asset`)
- **Description:** Allows the agent to download a workspace asset or specific storage S3 key to the local `.pi` directory for processing with local scripts or bash commands.
- **Why it matters:** Enables agents executing custom skill scripts to fetch files or intermediate transcode artifacts to local disk.
### 9. Rename Asset (`rename_asset`)
- **Description:** Allows the agent to rename an existing file or folder in Shumai.
- **Why it matters:** Enables agents to keep project files neatly named and organized according to workspace naming conventions. Enabled by default.
### 10. Move Assets (`move_assets`)
- **Description:** Allows the agent to move one or more assets to a destination parent folder.
- **Why it matters:** Enables agents to reorganize workspace structures, relocate generated outputs, or tidy up project folders. Enabled by default.
### 11. Delete Asset (`delete_asset`)
- **Description:** Allows the agent to delete a single file or folder by moving it to the Trash bin.
- **Why it matters:** Provides agents with the ability to clean up outdated or redundant assets. To prevent accidental data loss, this tool is **disabled by default** and strictly limited to deleting one asset at a time. Team Owners must explicitly enable this tool for an agent.
---
## Restricting Tools
To change which tools an agent can use:
1. Navigate to **Team Settings** > **Agents** (Note: Only Team Owners can view and modify these settings).
2. Click on the agent you want to edit.
3. Scroll down below the **Skills** section to find the **Tools** configuration panel.
4. Toggle the switches next to the tools to enable or disable them.
5. Click **Save Changes**.