Hi.
An example script that loads the user-agent strings from a file and changes the "User-Agent" request header field of the messages sent by ZAP:
// Loads user-agent strings, separated by end-of-line character(s), from a file
function loadUserAgents(filePath) {
   var reader = new java.io.BufferedReader(new java.io.FileReader(filePath));
   var userAgents = new java.util.ArrayList();
   var userAgent = null;
   while((userAgent = reader.readLine()) != null) {
       userAgents.add(userAgent);
   }
   reader.close();
   return userAgents;
}
var ZAP = JavaImporter(org.parosproxy.paros.network, org.zaproxy.zap.network);
with (ZAP) {
   var userAgents = loadUserAgents("/path/to/file/with/user-agent/strings");
   println("Read " + userAgents.size() + " user-agents.");
   if (userAgents.size() < 2) {
       println("Listener not added, expected at least 2 user-agents.");
   } else {
       println("Adding listener responsible for changing the user-agent...");
       HttpSender.addListener(new HttpSenderListener() {
           userAgentIdx:0,
           numberRequests:0,
           getUserAgent: sync(function() {
               // Change user-agent after 3 messages sent.
               if (this.numberRequests >= 3) {
                   this.numberRequests = 1;
                   ++this.userAgentIdx;
                   if (this.userAgentIdx >= userAgents.size()) {
                       this.userAgentIdx = 0;
                   }
               } else {
                   ++this.numberRequests;
               }
               return userAgents.get(this.userAgentIdx);
           }),
           onHttpRequestSend: function(msg, initiator) {
               // The user-agent is changed on all the messages sent by ZAP (proxied, active scanner, fuzzer...)
               msg.getRequestHeader().setHeader(HttpHeader.USER_AGENT, this.getUserAgent());
              Â
               // You can use the variable "initiator" to only change the messages sent by specific ZAP extensions.
               // For what values it can have see the *_INITIATOR constants:
               // https://code.google.com/p/zaproxy/source/browse/trunk/src/org/parosproxy/paros/network/HttpSender.java#75
               // Example:
               // if (initiator == 3) { // Change only spider messages
               //    msg.getRequestHeader().setHeader(HttpHeader.USER_AGENT, this.getUserAgent());
               // }
           },
           onHttpResponseReceive: function(msg, initiator) {
           },
           getListenerOrder: function() {
               return 200;
           }
       });
       println("Listener added.");
   }
}
Steps to add the script to ZAP:
1. Run ZAP (with "Script Console" add-on installed);
2. Select the "Scripts" tab and press the "New Script..." button;
3. Choose a name for the script, select the type "Stand Alone", select the script engine "ECMAScript : Rhino" and press "OK" (if you need to use the script several times you might want to select the option "Load on start" and use the same ZAP session);
4. Paste the above example script to the "Script Console" text area, change the path to the file that contains the user-agent strings and press the "Run script" button;
5. It should output something like this (using the file "UserAgents.fuzz.txt" bundled with "Fuzzdb files" add-on):
Read 2463 user-agents.
Adding listener responsible for changing the user-agent...
Listener added.
6. New requests sent by ZAP will have the "User-Agent" request header field changed.
Tested with:
ZAP version 2.2.2;
"Script Console" add-on version 9.
Best regards.