Bots from custom scripts
Virtual agents are currently in open beta. Bot active time is limited to 24 hours per month. Please contact us at [email protected] if you need more information or need a quota raise.
What are bots from custom script?
WorkAdventure provides out of the box support for bots that are powered by OpenAI, or Tock.ai. You can also provide your own Ollama compatible LLM model.
However, if you have very special needs, you can also build your own bot from the ground, using a custom script. This is the most advanced way to build a bot, and it requires you to have a good understanding of programming and of the WorkAdventure scripting API.
How to build a bot from a custom script?
In WorkAdventure, bots are implemented as a set of scripts that are executed in a headless browser. Each bot runs in its own browser, and can interact with the WorkAdventure world through the scripting API.
From the WorkAdventure server point of view, a bot is a regular user that is connected to the world.
From the bot edition interface, you can select the "Custom script" bot type.
You can provide:
- a script URL that points to the script that will be executed by the bot
- and/or custom hash parameters that will be passed to the headless browser URL when the bot is started
Note that you don't necessarily need to provide a script URL. You could instead code your bot directly in your map scripts, and decide whether to start it or not based on the presence of a specific hash parameter (or a specific tag).
It is often easier to code your bot directly into your map scripts, because you can then use the WorkAdventure map starter kit to code both your map and your bot in the same place.
However, if you want to build a bot that can be reused in multiple maps, you should publish your bot script somewhere on the internet.
Writing your bot script
We will not dive here into the details of the WorkAdventure scripting API. You can find a tutorial about building a bot based on the ChatGPT here. You can use this as a starting point for your own bot.
Publishing your bot script
You want to publish your bot script if you want to reuse it across maps.
You can host your bot script on any web server that supports HTTPS.
A bot script is simply a Javascript ES6 "module" that exports a function named run.
This function will be called by the WorkAdventure server when the bot is started. The module runs inside the browser
and has access to the scripting API (so the global WA object is available in the script).
In order to get you started, we provide a bot-starter-kit.
Step by step guide to using the bot-starter-kit
Go to the Github bot starter kit repository page and click the "Use this template" button.
You will be prompted to enter a repository name for your map.
Make sure to check the "Include all branches" checkbox, otherwise the Github Pages deployment process will not be setup automatically.
If you miss that step, don't worry, you can always fix that by clicking on the Settings tab of your repository and scroll down to the GitHub Pages section. Then select the gh-pages branch. It might already be selected, but please be sure to click on it nonetheless (otherwise GitHub will not enable GitHub pages).
If you only see a "master" branch and if the gh-pages branch does not appear here, simply wait a few minutes and refresh your page. When you created the project, Github Actions triggered a job that is in charge of creating the gh-pages branch. Maybe the job is not finished yet.
Wait a few minutes... Github will deploy a new website with the content of the repository. The address of the website is visible in the "GitHub Pages" section.
Click on the link. You should be redirected directly to WorkAdventure, on your map!
Testing your bot
Your bot now lives at https://[github_pages_url]/bot.js.
To test your bot, you need to register this URL in the "Custom script URL" field.