mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 20:27:37 +00:00
* 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
89 lines
4.6 KiB
Plaintext
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**.
|