Package com.alibaba.cloud.ai.graph.agent.extension.interceptor

Class FilesystemInterceptor

java.lang.Object
com.alibaba.cloud.ai.graph.agent.interceptor.ModelInterceptor
com.alibaba.cloud.ai.graph.agent.extension.interceptor.FilesystemInterceptor
All Implemented Interfaces:
Interceptor
public class FilesystemInterceptor extends ModelInterceptor
Filesystem interceptor that provides file system management capabilities to agents. This interceptor adds filesystem tools to the agent: ls, read_file, write_file, edit_file, glob, and grep. It enhances the system prompt to guide agents on using these filesystem operations effectively. Key Features: - Pluggable backend system for file storage (local, state-based, composite) - Path validation and security (prevents directory traversal) - Custom tool descriptions support - File metadata tracking (creation/modification timestamps) Note: Large result eviction has been moved to LargeResultEvictionInterceptor. To enable automatic eviction of large tool results, use both interceptors together. The interceptor automatically: - Injects filesystem tools (ls, read_file, write_file, edit_file, glob, grep) - Provides guidance on proper file path usage (absolute paths required) - Helps agents explore and modify file systems systematically Example: 
 FilesystemInterceptor interceptor = FilesystemInterceptor.builder()
     .readOnly(false)
     .build();
For automatic large result eviction: 
 FilesystemInterceptor fsInterceptor = FilesystemInterceptor.builder()
     .build();

 LargeResultEvictionInterceptor evictionInterceptor =
     LargeResultEvictionInterceptor.builder()
         .toolTokenLimitBeforeEvict(20000)
         .excludeFilesystemTools()
         .build();

 // Use both interceptors in your agent

  • Method Details

    • builder

      public static FilesystemInterceptor.Builder builder()

    • validatePath

      public static String validatePath(String path, List<String> allowedPrefixes)
      Validate and normalize file path for security. Prevents directory traversal attacks by checking for ".." and "~".
      Parameters:
      path - The path to validate
      allowedPrefixes - Optional list of allowed path prefixes
      Returns:
      Normalized canonical path
      Throws:
      IllegalArgumentException - if path is invalid

    • getTools

      public List<org.springframework.ai.tool.ToolCallback> getTools()
      Description copied from class: ModelInterceptor
      Get tools provided by this interceptor. Interceptors can provide built-in tools that will be automatically added to the agent.
      Overrides:
      getTools in class ModelInterceptor
      Returns:
      List of tools provided by this interceptor, empty list by default

    • getName

      public String getName()

    • interceptModel

      public ModelResponse interceptModel(ModelRequest request, ModelCallHandler handler)
      Description copied from class: ModelInterceptor
      Wrap a model call with custom logic. Implementations can: - Modify the request before calling the handler - Call the handler multiple times (retry logic) - Modify the response after handler returns - Handle exceptions and provide fallbacks
      Specified by:
      interceptModel in class ModelInterceptor
      Parameters:
      request - The model request
      handler - The next handler in the chain (or base handler)
      Returns:
      The model response