mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 16:08:01 +00:00
* feat(operations): move MCP to /mcp and add search, comment, metadata, version, and upload operations - Serve the MCP server at /mcp instead of /api/mcp - Add search_assets, copy_assets, get_folder_instructions, list_comments, create_comment, resolve_comment, list_metadata_fields, update_asset_metadata, create_version_stack, list_versions, and remove_version on the agent, MCP, and CLI - Add create_file and create_version (agent, MCP) with Creation Context metadata, and complete_upload (MCP) for presigned two-step uploads - Replace the native agent create_file/create_version tools with Operation-backed ones - Route the comment-complete, metadata, copy, version stack, and AGENTS.md read REST endpoints through their Operations * docs(readme): add built-in MCP server and CLI to features list
167 lines
10 KiB
Plaintext
167 lines
10 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.
|
|
- **Limits:** Up to 20 video frames or PDF pages per call. If rendering takes longer than about a minute, the tool tells the agent the render is still in progress instead of failing.
|
|
|
|
### 4. Get Asset Render (`get_asset_render`)
|
|
|
|
- **Description:** Allows the agent to pick up video frames or document pages that were still rendering when `read_asset` returned.
|
|
- **Why it matters:** Long videos and large documents can take a while to render. With this tool the agent can come back for the result instead of starting over. It only returns renders that `read_asset` started for the same user.
|
|
|
|
### 5. Browse Shumai (`list_assets`)
|
|
|
|
- **Description:** Allows the agent to list folders and browse files in Shumai. Large folders are returned page by page.
|
|
- **Why it matters:** Gives the agent visual mapping of the project structure so it can search for other files or locate related assets.
|
|
|
|
### 6. List Projects (`list_projects`)
|
|
|
|
- **Description:** Allows the agent to list the projects you have access to across your teams, including each project's root folder.
|
|
- **Why it matters:** Lets the agent find the right project and its root folder on its own before browsing or creating files.
|
|
|
|
### 7. 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.
|
|
|
|
### 8. 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.
|
|
|
|
### 9. 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.
|
|
|
|
### 10. Generate Image (`generate_image`)
|
|
|
|
- **Description:** Allows the agent to generate still images from text prompts and reference images using configured AI image models.
|
|
- **Why it matters:** Enables agents to create concept art, mockups, textures, and illustrations directly inside Shumai.
|
|
- **Prerequisite:** This tool requires at least one image model to be configured and enabled in [Image / Video Generation](/using-shumai/image-video-generation). If no image models are enabled under a configured provider, this tool is omitted from the agent session even if enabled in the agent settings dialog.
|
|
|
|
### 11. Generate Video (`generate_video`)
|
|
|
|
- **Description:** Allows the agent to generate video clips from text prompts, image animation, or transition keyframes using configured AI video models.
|
|
- **Why it matters:** Enables agents to produce short animated clips, camera motion shots, and video transitions.
|
|
- **Prerequisite:** This tool requires at least one video model to be configured and enabled in [Image / Video Generation](/using-shumai/image-video-generation). If no video models are enabled under a configured provider, this tool is omitted from the agent session even if enabled in the agent settings dialog.
|
|
|
|
### 12. Download Asset (`download_asset`)
|
|
|
|
- **Description:** Allows the agent to download up to 50 workspace files, or a specific storage S3 key (such as a frame from `read_asset`), to the local `.pi` directory for processing with local scripts or bash commands. By default it downloads the web preview version when there is one (for example the transcoded video or the web image); the agent can ask for the original uploaded file instead. Folders are not supported.
|
|
- **Why it matters:** Enables agents executing custom skill scripts to fetch files or intermediate transcode artifacts to local disk.
|
|
|
|
### 13. 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.
|
|
|
|
### 14. 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.
|
|
|
|
### 15. 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.
|
|
|
|
### 16. Search Assets (`search_assets`)
|
|
|
|
- **Description:** Allows the agent to search a folder and its subfolders by name, by meaning (when AI search is enabled for the team), or by metadata such as status.
|
|
- **Why it matters:** Lets the agent find the files a request is about without browsing folder by folder.
|
|
|
|
### 17. Copy Assets (`copy_assets`)
|
|
|
|
- **Description:** Allows the agent to copy files or folders, with everything inside them, into another folder of the same team.
|
|
- **Why it matters:** Lets the agent reuse assets across projects or set up working copies while keeping the originals unchanged.
|
|
|
|
### 18. Read Folder Instructions (`get_folder_instructions`)
|
|
|
|
- **Description:** Allows the agent to read a folder's instructions for AI agents (its AGENTS.md).
|
|
- **Why it matters:** Lets the agent follow the team's conventions, such as naming rules or deliverable specs, before adding files to a folder.
|
|
|
|
### 19. Read Comments (`list_comments`)
|
|
|
|
- **Description:** Allows the agent to read the review comments and replies on a file, including their timecodes.
|
|
- **Why it matters:** Lets the agent act on review feedback, for example to summarize open notes or address them in a new version.
|
|
|
|
### 20. Post Comment (`create_comment`)
|
|
|
|
- **Description:** Allows the agent to comment on a file, optionally at a timecode, or reply to a comment. Comments are posted as the user the agent works for; the audit log records that the agent wrote them.
|
|
- **Why it matters:** Lets the agent take part in reviews like a teammate. Mentions in the agent's comments don't start other agents.
|
|
|
|
### 21. Resolve Comment (`resolve_comment`)
|
|
|
|
- **Description:** Allows the agent to mark comments as resolved, or reopen them.
|
|
- **Why it matters:** Lets the agent close the feedback it has addressed.
|
|
|
|
### 22. List Metadata Fields (`list_metadata_fields`)
|
|
|
|
- **Description:** Allows the agent to see a project's metadata fields, such as status, rating, and custom fields, with their choices.
|
|
- **Why it matters:** Tells the agent which values it can search by or set.
|
|
|
|
### 23. Update Metadata (`update_asset_metadata`)
|
|
|
|
- **Description:** Allows the agent to set metadata values on a file, such as its status or tags. Read-only fields can't be changed.
|
|
- **Why it matters:** Lets the agent keep a file's review status and other fields up to date.
|
|
|
|
### 24. Create Version Stack (`create_version_stack`)
|
|
|
|
- **Description:** Allows the agent to stack existing files in the same folder as versions of one asset.
|
|
- **Why it matters:** Lets the agent tidy up loose revisions (for example `cut_v1.mp4` and `cut_v2.mp4`) into one versioned asset.
|
|
|
|
### 25. List Versions (`list_versions`)
|
|
|
|
- **Description:** Allows the agent to list the versions in a version stack, latest first.
|
|
- **Why it matters:** Lets the agent compare a file with earlier versions.
|
|
|
|
### 26. Remove Version (`remove_version`)
|
|
|
|
- **Description:** Allows the agent to take a version out of its stack. The file isn't deleted; it goes back into the folder as a separate file.
|
|
- **Why it matters:** Lets the agent fix a version that was stacked by mistake.
|
|
|
|
---
|
|
|
|
## 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**.
|