Custom Tools for AI Assistants

Andy Chen Updated by Andy Chen

Empower your DeskDirector AI Assistants with Custom Tools (also known as plugins) to perform a wide range of actions, from interacting with external services to executing specific operational tasks. This guide will walk you through setting up, assigning, and testing custom plugins to extend the capabilities of your AI Assistants.

Setting Up a Custom Tool

Follow these steps to create a new custom tool for your AI Assistants.

  1. Navigate to AI Services Settings: In your Admin portal, go to the AI Services settings page.
  2. Access Custom Plugins: Under the Custom Plugins section, click on Settings.
  3. Initiate Creation: Click the Create a Custom Plugin button to begin the setup process.

You have two primary methods for defining the operations your plugin can perform: importing an OpenAPI document or creating operations manually.

Option 1: Import an OpenAPI 3.0 Document

If you have a pre-existing OpenAPI 3.0 specification for your tool, you can import it directly.

  • Click the Choose File button.
  • In the pop-up dialog that appears, select the specific operations you want to enable for the AI Assistant. This is a crucial step to control and limit which actions the assistant can take, ensuring it only has access to necessary and approved functions.

Option 2: Create Operations Manually

You can also build your tool's functionality from the ground up by adding individual operations.

  • Click the Add Operation button.
  • Fill in the following details for each operation:
    • Description (Required): Provide a clear and concise description of what the operation does. This description is vital as it helps the AI assistant understand when and how to use this action.
    • HTTP Method/Path (Required): Define the HTTP method (e.g., GET, POST, PUT, DELETE) and the API endpoint path.
    • Query Parameters (Optional): Add any necessary query parameters for the request.
    • Request/Response Body Examples (Optional): Specify example bodies for both the request and the response. These examples help the system generate the necessary schemas for the AI to understand the data structure.

Finalizing the Plugin

After defining your operations, complete the following fields:

  • Plugin Name (Required): Give your plugin a descriptive name that the AI assistant can recognize.
  • Server URL (Required): Enter the base URL for the API. Ensure this is a valid and accessible address pointing to your server or service provider.
  • Authentication (Highly Recommended): Secure your tool by setting up authentication. API Key authentication is supported and is the recommended method to ensure that only authorized requests are processed.

Once all details are configured, click Create Custom Plugin to save your new tool.

Assigning and Testing Your Plugin

After creating a plugin, you need to assign it to an AI assistant and test its functionality.

  1. Return to AI Services: Go back to the main AI Services page.
  2. Select an AI Assistant: Navigate to AI Assistants and choose the assistant you wish to enhance.
  3. Assign the Plugin: In the Basic Settings tab for the selected assistant, find the Plugins section and select one or more of your custom plugins from the list.
  4. Update Chat Instructions: Go to the Adjust Chat Settings tab. This is a critical step. You must update the chat instructions to inform the AI assistant about the new tool and how to use it effectively. Provide clear guidance on when to trigger the plugin and what kind of user queries it can handle.
  5. Test the Plugin: Move to the Test Chat Settings tab. Engage in a conversation with your AI assistant to test the new functionality. Try different prompts to ensure the plugin is triggered correctly and behaves as expected.
  6. Save Your Changes: Once you are satisfied with the configuration and testing, go to the Review & Save tab to apply all your changes.

Best Practices for Creating Effective Plugins

To ensure your LLM-powered AI Assistant can use your custom tools reliably and effectively, follow these best practices:

  • Write Clear, Descriptive Names and Descriptions: The AI relies heavily on the names and descriptions you provide for both the plugin itself and its individual operations.
    • For Operation Descriptions: Be explicit about what the function does, what inputs it needs, and what it returns.
    • For Parameter Descriptions: Clearly describe each parameter. For example, for a parameter named ticket_id, the description could be "The unique numerical identifier for a support ticket."
  • Use Specific, Atomic Operations: Create single-purpose functions rather than one complex function that does multiple things. For instance, have separate operations for get_ticket_details, update_ticket_status, and add_note_to_ticket rather than a single manage_ticket function. This makes it easier for the AI to choose the correct tool for a specific task.
  • Provide High-Quality Examples: The request and response body examples you provide are used to generate the data schemas. Ensure your examples are accurate and representative of the real-world data the tool will handle. This helps the AI understand the expected data formats.
  • Handle Errors Gracefully: Design your API to return meaningful error codes and messages. When the AI receives a clear error (e.g., "404: Ticket not found"), it can provide a more helpful response to the user instead of failing silently.
  • Iterate and Refine: Building effective tools for an LLM is an iterative process. Test your assistant with various prompts, observe its behavior, and refine your operation descriptions, instructions, and examples based on the results.

Advanced

Using an OpenAPI Editor

For creating complex plugins with multiple operations and detailed data structures, we recommend using a third-party OpenAPI editor (like Swagger Editor or Stoplight).

Using an external editor allows you to construct a comprehensive OpenAPI 3.0 specification with well-documented schemas for your request and response bodies. While our user interface currently generates schemas based on the examples you provide, a dedicated editor enables you to add detailed descriptions, constraints, and types for each field. This level of detail provides the AI with a much richer understanding of the API's requirements, leading to more accurate and reliable tool usage.

Once your OpenAPI document is complete, you can easily import it into DeskDirector using the "Choose File" option during the plugin creation process.

How did we do?

Ticket Summary for Tech Portal

Knowledge Bases for AI Assistants

Contact