-
-
Notifications
You must be signed in to change notification settings - Fork 132
Creating your first agents
Witsy allows you to create your own agents. Agents are defined as:
- a specific goal (communicated through system instructions)
- a workflow (only linear for now)
- a defined set of tools that can be used at each step
- a defined set of delegate agents that can be used at each step
Optionally, although it is recommended, you can define a specific model to run your agent. Models are not created equal when it comes to complying to specific instructions and/or call tools appropriately so it is recommended to use a pretty capable model (most Witsy tests were done using OpenAI GPT-4.1).
In this tutorial, we will create an agent that can resolve a combat between two fighters and write a tale about the winner. This agent will use a delegate agent to roll dice.
At the end of the tutorial, you will know how to:
- create single-step and multi-step agents
- use variables to create templated prompt
- assign specific tools to agent steps
- delegate work to other agents
For this tutorial, you need to have configured the Python plugin in Settings | Plugins | Python. Make sure the plugin is enabled and a valid python binary specified.
Click on the Robot icon in Witsy sidebar to launch the Agent Forge. Now click on the robot head to launch the assistant.
The first screen is mostly descriptive althouh be aware that the description will be communicated to the model if this agent is used as a delegate agent.
- Enter "Dice Roller" in the name field
- Enter "An agent that can roll dice to provide a random number" in the description
- Leave the execution model as "User executable" for now
The second screen is to define the goal. This is probably the most crucial part of your agent. The goal will be the first thing communicated to the model and will dictate how it will behave. For our dice roller agent, enter the following goal:
Your goal is to provide a random number using the python coding tool. If a type of dice is specified use it to generate the right python code.
In the third screen, we can specify a model. If you have access to OpenAI, select GPT-4.1. Otherwise select a model of your choice but be mindful of the capabilities of the model you choose.
The fourth screen is used to define the workflow. For the dice roller agent, we will have a single-step workflow. In the prompt field, enter:
Give me a random number using {{type:Type of dice to roll (D&D format)}}
Notice the specific syntax that allows us to define a variable in our prompt. If you execute this agent manually, you will be prompted for the value of this variable. If this agent is called by another agent (as a delegate), then the model is supposed to provide this value.
You can define as many variables as you want. Witsy helps you verify your prompt by displaying the "Detected variables" just below your prompt.
For this step of the workflow to run, we need to make sure the model can actually run a python program. For this, click on "Tool selection". No tool should be selected so scroll down to run_python_code and enable it. Save.
The last screen is used to schedule execution of your agent. We will leave this blank for now and click Save.
Your new agent should be listed on the home page of the Agent Forge. Go back to the Chat mode (clicking the 1st icon in the sidebar), and click on the Robot icon at the top of the window (the one with a lightning).
You should see a window allowing you to select an agent. Only one should be listed: the Dice Roller. Click on it.
You should be prompted for the type of dice to roll (remember our variable). Enter 1D6 and press OK. You should see the result of the roll!
You can navigate back to the Agent Forge, click on your agent. You should see the history runs, and of course the one you just executed.
Now that we have an agent that can roll dice, we can create our Tale Teller. Return to the Agent Forge home and create a new Executable Agent.
You know the first three screens so enter the following data
- Name: "Tale Teller"
- Description: "An agent that resolves a combat between two fighters and tell a tale about the winner"
- Goal:
You are an autonomous agent. You execute your task without ever asking anything to the user. Make your own choices.
Each combat is made of a maximum of 10 rounds.
Each round is resolved bu rolling 2D6 for each fighter:
- Dead if result is less than 4
- Alive otherwise
Output the result immediately after each round and continue to the next round without asking the user.
The combat ends when one of the fighter is dead or if they are still alive after 10 rounds.
For the model, proceed as before.
To make sure the agent does what we want it to do, we will use a multi-step approach:
- Step #1: Resolving the combat
- Step #2: Writing the tale
For step 1, enter:
- Description: "Resolving the combat..."
- Prompt:
Resolve the combat between {{fighter1:Name of 1st fighter:Luke}} and {{fighter2:Name of 2nd fighter:Vader}}.
Notice that we define two variables with default values.
We want our agent to use our Dice Roller for this step: click on "Delegate agents" and enable the "Dice Roller".
Now click on "Add Step" and enter:
- Description: "Writing the tale..."
- Prompt:
Fight outcome: {{output.1}}.
Based on this write the tale of the winner of the fight
Notice that we use {{output.1}} to feed the output of step 1 in the prompt of step 2. By default, steps are not connected and you need to do so explicitely using {{output.*}} variables. This allows you to give more context to the model about that output.
For this step, we do not need any tool or delegate agent.
Click Next and Save your new agent.
We will run our Tale Teller the same way we ran Dice Roller. Back to chat, click on "Run agent" icon and click on "Tale Teller".
This time the prompt should contain two fields, both pre-filled with our default values. Press OK.
The agent should execute and should display:
- Resolving the combat... (description of step 1)
- Writing the tale... (description of step 2)
Once completed you should see a tale about the winner of the fight!
We can go back to the Agent Forge to look at the logs.
In the Tale Teller, you should see then run. The Output part of the run should show the conversation with the fight being resolved (you can see the Agent Dice Roller executed).
You can now navigate to the Dice Roller. You should only see your manual run in the History. Select "All runs" in the dropdown of the History pane, and now you should be able to see the "Worflow" runs that were triggered as part of the Tale Teller execution!
You can switch the Dice Roller type to "Support Agents" by editing it and clicking Save.
Now when you click "Run agent" in the main window, it should not be listed there anymore.