Discourse AI - AI bot custom tools

:bookmark: This guide explains how to create, configure, and integrate custom AI tools within the Discourse AI plugin, enabling administrators to extend the bot’s capabilities with user-defined JavaScript functions.

:person_raising_hand: Required user level: Administrator

Summary

This documentation covers:

  • Creating a new custom AI tool
  • Configuring tool parameters and scripts
  • Available APIs for tool scripts
  • Integrating custom tools with AI personas
  • Testing and troubleshooting custom tools

Creating a new custom AI tool

To create a new AI tool:

  1. Navigate to Admin Panel > Plugins > Discourse AI > Tools
  2. Click “New Tool” (you can use existing presets to learn about options)
  3. Fill in the following fields:
    • Name: The name of the tool as presented to the LLM
    • Description: The description of the tool as presented to the LLM
    • Summary: Summary of what tool does to assist users (displayed in details)
    • Parameters: Define the inputs your tool needs as presented to LLM
    • Script: The JavaScript code that powers your tool
  4. Click “Save”

This image shows a user interface window with various options, including a selected preset titled "Stock quote (AlphaVantage)" and other tools like browsing the web using jina.ai, exchange rate, and starting from a blank state. (Captioned by AI)

Configuring tool scripts

Available APIs

Your tool scripts have access to the following APIs:

  1. HTTP Requests:

    http.get(url, options)
    http.post(url, options)
    

    Use these to interact with external services. You can use options to specify HTTP headers:

    http.get(url, { headers: { Auth: "some value" } })
    
  2. LLM (Language Model) Integration:

    llm.truncate(text, length)
    

    This allows you to manipulate text within the AI model’s token limits.

Required functions

Your script must implement:

  • invoke(params): The main function that executes when the tool is called

It may optionally implement:

  • details(): (Optional) Provides additional information about the tool’s execution

Example script:

function invoke(params) {
  let result = http.get("https://api.example.com/data?query=" + params.query);
  return JSON.parse(result.body);
}

function details() {
  return "Fetched data from Example API";
}

Limitations and security

  • Execution Timeout: Tools have a default timeout of 2 seconds
  • HTTP Requests: Maximum of 20 requests per tool execution
  • Sandboxed Environment: No access to server file system or Ruby libraries

Testing your tool

You should test any tool you build to ensure the results the LLM will be provided with match your expectations.

Integrating tools with AI personas

To add your custom tool to an AI Persona:

  1. Go to Admin Panel > Plugins > Discourse AI > Personas
  2. Edit an existing persona or create a new one
  3. In the “Tools” section, you’ll see your custom tools listed alongside built-in tools
  4. Select your custom tool to add it to the persona

This image shows a list of enabled tools or plugins in an interface, including options like JavaScript Evaluator, GitHub Search Code, Tags, Image, Dall-E, Google, and a custom tool named "Stock_quote". (Captioned by AI)

Custom tools in action

Once you provide the custom tool to your LLM it can use it to enhance the conversation.

Troubleshooting

If your tool isn’t working as expected:

  1. Use the Test interface to ensure it behaves as expected for your inputs.
  2. Ensure your group is in ai_bot_debugging_allowed_groups. Members of this group have full access to the bot transcripts; you can view the AI logs there.
  3. If anything unexpected is happening, visit https://SITENAME/logs to check for errors.

Additional resources

Last edited by @hugh 2024-08-06T02:04:41Z

Last checked by @hugh 2024-08-06T02:00:12Z

Check documentPerform check on document:
11 Likes