Creating Zoom Virtual Agent tools

A tool represents an API integration that allows your virtual agent to interact with external systems. It is reusable and can be attached to any Zoom Virtual Agent skill. Tools can perform data lookups (such as fetching customer cases from Zendesk), update information (like posting a new record to Salesforce), or execute custom logic using JavaScript. Each tool includes parameters, which are inputs required by the external API, and responses, which are outputs that can be used in your virtual agent’s dialogue.

Requirements for creating Zoom Virtual Agent tools

• Account owner or admin privileges; or relevant role/privilege
• Basic, Pro, Business, Education, or Enterprise account
• Zoom Virtual Agent and Zoom Contact Center licenses

How to create Zoom Virtual Agent tools

1. Sign in to the Zoom web portal.
2. In the navigation menu, click AI Studio then Tool Templates.
   You will see the following tabs:
   • All tool types: View all available tools.
   • Built-in: Tools provided by Zoom.
   • Custom: Tools you create.
3. In the All tool types or Custom tab, click Add Tool.
4. Select a tool type: API Call or Custom Script.
5. Configure the setting for the selected tool type.
6. Click Create.

API Call settings

• Name: Enter a display name for your API Call tool.
• Description: Provide a concise explanation of when and why the tool should be used. This helps the LLM understand the appropriate context for triggering the API call. For example, "Use this tool when the user asks for the status of their recent orders."
• Endpoint URL: Enter the API endpoint. Use placeholders in curly braces for path variables. For example, /api/user/{userId}
• Method: Select the HTTP method: GET, POST, PUT, or DELETE.
• Authorization (Optional): Add an authorization method (for example, Bearer Token or API Key) if required by the API.
• API timeout value: Specify the maximum time (in seconds) to wait for a response before the call times out.
• Parameters (Optional): Define input parameters required by the API. These parameters help ZVA construct the API call dynamically based on user input or predefined values. Click Add parameter and provide the following:
  • Name: The name of the parameter as expected by the API.
  • Description: Describe the purpose of the parameter. Be specific so the LLM can determine how to supply its value.
  • Location: Where the parameter will be placed (Path, Query, Header, or Body).
  • Type: The data type (for example, string, number, boolean).
  • Value source: Where the value comes from (set manually or collected via LLM).
  • Set Value / Value: Define how the value is derived (for example, user.phoneNumber, "12345").
• Debug: To test your configuration:
  • Click the Run button.
  • Input Parameters: Shows the values for the parameters you've defined.
  • Result: Displays the raw API response so you can verify correctness and troubleshoot if needed.
• Response (Optional): Define how to interpret and use data returned by the API. Click Add parameter and complete the following for each response attribute:
  • Name: The key from the JSON response.
  • Description: Explain the value's significance. This helps the LLM understand how to use it in its reply.
  • Type: The data type (for example, string, number, boolean).
  • Map to variable (Optional): Map the response value to a ZVA or skill-level variable for later reference.

Example of CRM Lookup Tool (No-Code)

1. Enter the CRM API URL.
2. Define input parameters. For example, query for phone number.
3. Under Value Source, select how to populate each parameter:
   • Manual: Hard-code a static value
   • From Variable: Map from an existing variable (for example, global.system.engagement.ani for caller phone)
   • Collect via LLM: Have the virtual agent ask the user for this value

Custom script settings

• Name: Enter a display name for your custom script tool.
• Description: Describe the scenario in which this tool should be used. Be specific to help the LLM determine when to trigger the script. For example, "Use this tool when the user asks for a personalized greeting based on time of day and user location."
• Javascript: Write the logic your tool should execute using JavaScript. This script will be run in a secure, isolated environment.
• After writing your script, click the Format code button to improve readability and ensure code structure is preserved.
• Parameters (Optional): Define input parameters to make the script dynamic. These values can be passed from the user's input, skill context, or other tools. Click Add parameter and provide the following:
  • Name: The variable name used inside your script.
  • Description: A clear explanation of what this parameter is and how it is used. Helps the LLM determine what to pass in.
  • Type: The data type (for example, string, number, boolean).
  • Value source: Where the value comes from (set manually or collected via LLM).
  • Set Value / Value: Define how the value is derived (for example, user.phoneNumber, "12345").
• Response (Optional): Specify what data the script returns and how it should be used. Click Add parameter and provide the following:
  • Name: The key name returned from the script (for example, message, score).
  • Description: Explain the meaning or use of the value. This helps the LLM incorporate it naturally into its response.
  • Type: The format of the returned value (for example, string, number, boolean).
  • Map to Variable (Optional): Assign the output to a reusable variable for later use in skills, responses, or reporting.

Example of CRM Lookup Tool (JavaScript)

• Make API calls with custom logic
• Manipulate or format data before returning it to Zoom Virtual Agent
• Map output values to variables for use in later steps

async function main() {
  // API endpoint and token
  var baseUrl = "https://api.example.com/v1/";
  var token = var_get()["apiKey"];

  var http_request_config = {
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer " + token
    }
  };

  // Get parameters from ZVA
  var phoneNumber = var_get()["phoneNumber"];

  // Step 1: GET case by number
  var getUrl = baseUrl + "/case?phone=" + phoneNumber;
  
  try {
    var getResponse = await req.get(getUrl, http_request_config);
  } catch(error) {
    log.debug(`${error}`);
    return { "result": "lookup failed" }; //agentic return to agent
  }

  if (getResponse.status != 200) {
    log.debug(`Request ${getUrl} failed with status code ${getResponse.status}`)
    return { "result": "unable to find any cases for " +  phoneNumber}; //agentic return to agent
  } else {
    return getResponse.data;
  }
}

[
    {
        "id": 5343,
        "status": "Open",
        "subject": "Refund request for order 3434",
        "priority": "High",
        "date_opened": "2025-11-04",
        "assigned_agent": "ally.agent@example.com"
    },
    {
        "id": 7423,
        "status": "Open",
        "subject": "Upgrade to premium plan",
        "priority": "Medium",
        "date_opened": "2025-11-05",
        "assigned_agent": "aaron.agent@example.com"
    }
]

How to use Zoom Virtual Agent tools in skills

1. Sign in to the Zoom web portal.
2. In the navigation menu, click AI Studio then Virtual Agents.
3. Create or edit an existing voice agent or chat agent.
4. In the Skills section, click Create skill.
5. Add detailed instructions for the agent to follow. For example:
   • Tell the caller we'll look up their cases using their phone number.
   • Use the tool Case Lookup example.
   • If no cases are found, ask for the phone number and try again.
   • Read back only the case ID and subject.
     Once configured, when a user asks, “Can you look up my cases?”, the virtual agent will automatically execute the Case Lookup tool and respond based on the data returned from the external system.

Best practices for creating Zoom Virtual Agent tools

• Use clear, consistent names and descriptions to improve discoverability and guide the LLM.
• Map only essential response attributes needed for the agent’s reply.
• Use meaningful variable names to simplify referencing in skills and responses.
• Test all API calls with the debug tool before publishing.
• Write modular, testable scripts and validate input parameters to prevent errors.
• Return only the data required to fulfill the user request effectively.

This article applies to Zoom Virtual Agent voice and chat agent. If you are using Zoom Virtual Agent classic chatbot, refer to this documentation for setup and deployment instructions.