VFS Toolset¶

The VFS (Virtual File System) toolset provides access to resources defined in your manifest's resources section. It offers a unified interface to query and read from multiple configured filesystems.

Basic Usage¶

First, define resources in your manifest:

resources:
  docs:
    type: uri
    uri: "memory://"
  data: "s3://my-bucket/data"
  code: "github://myorg:myrepo@main"

Then enable the VFS toolset:

agents:
  my_agent:
    tools:
      - type: vfs

Available Tools¶

Vfs Tools

`vfs_list`

List contents of a resource path.

Parameters:

Name	Type	Description
`path`	string	Resource path to query (e.g., "docs", "docs://guides", "data://files")
`pattern`	string	Glob pattern to match files against
`recursive`	boolean	Whether to search subdirectories
`include_dirs`	boolean	Whether to include directories in results
`exclude`	array	List of patterns to exclude
`max_depth`	integer	Maximum directory depth for recursive search

Hints: read-only, idempotent

Category: search

`vfs_read`

Read content from a resource path.

Parameters:

Name	Type	Required	Description
`path`	string	✓	Resource path to read (e.g., "docs://file.md", "data://folder")
`encoding`	string		Text encoding for binary content
`recursive`	boolean		For directories, whether to read recursively
`exclude`	array		For directories, patterns to exclude
`max_depth`	integer		For directories, maximum depth to read

Hints: read-only, idempotent

Category: read

`vfs_info`

Get information about all configured resources.

Hints: read-only, idempotent

Category: read

Usage Examples¶

Once configured, agents can access resources like:

# List all available resources
vfs_list()

# List files in a specific resource
vfs_list("docs")

# Read a file
vfs_read("docs/guide.md")

# Read a directory recursively
vfs_read("code/src", recursive=True)

Configuration Reference¶

VFS Toolset¶

Configuration for VFS registry filesystem toolset.

VFS Toolset (YAML)
toolsets:
- type: vfs
  namespace: null  # Optional namespace prefix for tool names

When to Use VFS vs File Access¶

Use Case	Recommended
Shared resources across agents	VFS
Agent-specific filesystem	File Access
Simple resource access	VFS
Full file editing capabilities	File Access
Composed/mounted filesystems	File Access with `mounts`