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 filesystem path.

Lists files from the agent's unified filesystem, which includes: - Agent's internal storage (execute_code/, tasks/, etc.) - Configured VFS resources

Parameters:

Name	Type	Description
`path`	string	Path to query (e.g., "/", "/docs", "/tasks")
`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 filesystem path.

Reads from the agent's unified filesystem, which includes: - Agent's internal storage (execute_code/, tasks/, etc.) - Configured VFS resources

Parameters:

Name	Type	Required	Description
`path`	string	✓	Path to read (e.g., "/docs/readme.md", "/tasks/task_123/output.md")
`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 the agent's unified filesystem.

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`