Tools.md

slug	Tools
title	Tools
description	Ms-Agent Tools

Tools

Tool List

MS-Agent supports many internal tools:

split_task

Task splitting tool. LLM can use this tool to split a complex task into several subtasks, each with independent system and query fields. The yaml configuration of subtasks inherits from the parent task by default.

split_to_sub_task

Use this method to start multiple subtasks.

Parameters:

• tasks: List[Dict[str, str]], list length equals the number of subtasks, each subtask contains a Dict with keys system and query

file_system

A basic local file CRUD tool. This tool reads the output field in the yaml configuration (defaults to the output folder in the current directory), and all CRUD operations are performed based on the directory specified by output as the root directory.

create_directory

Create a folder

Parameters:

• path: str, the directory to be created, based on the output field in the yaml configuration.

write_file

Write to a specific file.

Parameters:

• path: str, the specific file to write to, directory based on the output field in the yaml configuration.
• content: str: content to write.

read_file

Read file content

Parameters:

• path: str, the specific file to read, directory based on the output field in the yaml configuration.

list_files

List files in a directory

Parameters:

• path: str, relative directory based on the output in yaml configuration. If empty, lists all files in the root directory.

code_executor

Code execution tool that runs code in a sandbox or commands in local subprocesses. The behavior is controlled by the tools.code_executor.implementation field.

• When omitted or set to sandbox:

  • Uses an ms-enclave based sandbox. The sandbox can be created locally with Docker or via a remote HTTP service.
  • Currently supports two sandbox types: docker and docker_notebook. The former is suitable for non-interactive/stateless execution; the latter maintains notebook-style state across calls.
  • The configured output_dir on the host is mounted into the sandbox at /data so code can read and write persistent artifacts there.

• When set to python_env:

  • Provides shell_executor for system commands and file_operation for basic file operations. The default SDK agent and WebUI expose only shell_executor from this tool.
  • Uses programs and dependencies from the local environment, with output_dir as the working directory. Configure command environment variables with shell_env and the default timeout with shell_timeout.
  • Tool calls follow the agent's permission policy. Programs access host resources directly, so choose sandbox mode when execution requires isolation.

Example local configuration:

tools:
  code_executor:
    mcp: false
    implementation: python_env
    shell_timeout: 120
    include:
      - shell_executor

Migrating an older local configuration: remove python_executor, notebook_executor, reset_executor, and get_executor_info from include / exclude, then enable the local tools you need as shown above. These four interfaces apply only to sandbox mode. Replace python_timeout / notebook_timeout with shell_timeout, and kernel_env with shell_env.

notebook_executor

• Sandbox mode: Executes code inside a docker_notebook sandbox, preserving state (variables, imports, dataframes, etc.) across calls. Files under the mounted data directory are available at /data/..., and you can also run simple shell commands from code cells using the standard ! prefix.

Parameters:

• code: string – Python code to execute.
• description: string – Short description of what the code is doing.
• timeout: integer – Optional execution timeout in seconds; if omitted, the tool-level default is used.

python_executor

• Sandbox mode: Executes Python code in a docker-type sandbox using the sandbox’s Python interpreter, typically used when you do not need full notebook-style interaction.

Parameters:

• code: string – Python code to execute.
• description: string – Short description of what the code is doing.
• timeout: integer – Optional execution timeout in seconds; if omitted, the tool-level default is used.

shell_executor

• Sandbox mode: Executes commands inside a docker or docker_notebook container. Shared files are available under /data.
• Local mode: Executes commands in a new system shell (/bin/sh on POSIX, cmd.exe on Windows), with the working directory set to output_dir. Each call has its own process environment; temporary changes to the working directory or environment variables do not carry over to the next call.

Parameters:

• command: string – Shell command to execute.
• timeout: integer – Optional execution timeout in seconds; if omitted, the tool-level default is used.

file_operation

• Sandbox mode: Performs basic file operations inside a docker or docker_notebook container (create, read, write, delete, list, exists). Paths refer to locations inside the sandbox; files under the mounted /data directory are shared with the host.
• Local mode: Performs the same basic file operations on the local filesystem but always constrained under output_dir to prevent accessing arbitrary locations.

Parameters:

• operation: string – Type of file operation to perform; one of 'create', 'read', 'write', 'delete', 'list', 'exists'.
• file_path: string – File or directory path (sandbox-internal in sandbox mode; relative to or under output_dir in local mode).
• content: string – Optional, content to write when operation is 'write'.
• encoding: string – Optional file encoding, default utf-8.

reset_executor

• Sandbox mode: Recreates the sandbox (or restarts the notebook kernel) to clear all variables and session state when the environment becomes unstable.

get_executor_info

• Sandbox mode: Returns the current sandbox status and configuration summary (such as memory/CPU limits, available tools, etc.).

MCP Tools

Supports passing external MCP tools, just write the configuration required by the mcp tool into the field, and make sure to configure mcp: true.

  amap-maps:
    mcp: true
    type: sse
    url: https://mcp.api-inference.modelscope.net/xxx/sse
    exclude:
      - map_geo

Custom Tools

Passing mcp.json

This method can pass an mcp tool list. Has the same effect as configuring the tools field in yaml.

ms-agent run --config xxx/xxx --mcp_server_file ./mcp.json

Configuring yaml file

Additional tools can be added in tools within yaml. Refer to Configuration and Parameters for details.

Writing new tools

from ms_agent.llm.utils import Tool
from ms_agent.tools.base import ToolBase


# Can be changed to other names
class CustomTool(ToolBase):
    """A file system operation tool

    TODO: This tool now is a simple implementation, sandbox or mcp TBD.
    """

    def __init__(self, config):
        super(CustomTool, self).__init__(config)
        self.exclude_func(getattr(config.tools, 'custom_tool', None))
        ...

    async def connect(self):
        ...

    async def cleanup(self):
        ...

    async def get_tools(self):
        tools = {
            'custom_tool': [
                Tool(
                    tool_name='foo',
                    server_name='custom_tool',
                    description='foo function',
                    parameters={
                        'type': 'object',
                        'properties': {
                            'path': {
                                'type': 'string',
                                'description': 'This is the only argument needed by foo, it\'s used to ...',
                            }
                        },
                        'required': ['foo_arg1'],
                        'additionalProperties': False
                    }),
                Tool(
                    tool_name='bar',
                    server_name='custom_tool',
                    description='bar function',
                    parameters={
                        'type': 'object',
                        'properties': {
                            'path': {
                                'type': 'string',
                                'description': 'This is the only argument needed by bar, it\'s used to ...',
                            },
                        },
                        'required': ['bar_arg1'],
                        'additionalProperties': False
                    }),
            ]
        }
        return tools

    async def foo(self, foo_arg1) -> str:
        ...

    async def bar(self, bar_arg1) -> str:
        ...

Save the file in a relative directory to agent.yaml, such as tools/custom_tool.py.

agent.yaml
tools
  |--custom_tool.py

Then you can configure it in agent.yaml as follows:

tools:
  tool1:
    mcp: true
    # Other configurations

  tool2:
    mcp: false
    # Other configurations

  # This is the registered new tool
  plugins:
    - tools/custom_tool

We have a simple example that you can modify based on this example.