Files
shumai/docs/using-shumai/agent-tools.mdx
T
Yiling-J b3cae4f2b0 feat: move MCP to /mcp and add teammate operations (#500)
* 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
2026-10-27 14:37:26 +08:00

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**.