Build an AI Agent to Handle Mathematical Queries¶
In this tutorial, you'll create an AI-powered math tutor assistant capable of handling a variety of mathematical queries. The agent will be equipped with tools to perform fundamental arithmetic operations and intelligently combine and execute these tools to address user questions. By the end of this tutorial, you'll have built an interactive math assistant that can help users solve problems and provide clear, step-by-step explanations.
Note
This math tutor agent can technically be implemented using just an LLM, without any agent capabilities. However, the purpose of this tutorial is to help you understand the essential concepts required to build an AI agent using Ballerina Integrator. By following this guide, you'll gain hands-on experience with agent creation in Ballerina Integrator, setting the foundation for developing more powerful and tailored AI agents in the future.
Prerequisites¶
- Sign up at OpenAI.
- Get an API key from the API section.
Step 1: Create a new integration project¶
- Click on the Ballerina Integrator icon in the sidebar.
- Click on the Create New Integration button.
- Enter the project name as
MathTutor
. - Select the project directory location by clicking on the Select Location button.
-
Click the Create New Integration button to generate the integration project.
Step 2: Create an agent¶
- Click the + button on the Ballerina Integrator side panel or navigate back to the design screen and click on Add Artifact.
- Select AI Chat Agent under the AI Agent artifacts.
- Provide a Name for the agent. It will take a moment to create an agent with the default configuration.
-
After creating the agent, you can configure it with a model provider, memory, tools, roles, and instructions.
Step 3: Configure the agent behavior¶
- Click on the AI Agent box to open the agent configuration settings.
- Define the agent's Role and provide Instructions in natural language. These instructions will guide the agent’s behavior and tasks.
-
Click Save to finalize and complete the agent behavior configuration.
Step 4: Configure the agent model¶
- Locate the circle with OpenAI logo which is connected to the AI Agent box. This circle represents the LLM model used by the agent.
- Click on the circle to open the model configuration options.
- In the Select Model Provider dropdown, choose OpenAiProvider. By default, OpenAiProvider is selected.
-
Next, provide the OpenAI API key in the API Key input field.
Note
Since the API key is sensitive, it’s recommended to externalize it by using a configurable value. This helps prevent accidentally committing it to your version control system and ensures it’s kept secure without being exposed. To learn more, see Configurations.
- Click the API Key input field to open the Expression Helper window.
- In the top bar, go to the Configurables tab (the third option).
- Click + Create New Configurable Variable to define a new configurable.
- Set the Name to
openAiApiKey
and the Type tostring
. - Click Save to create the configurable.
-
In the Model Type dropdown, select
ai:GPT_40
. -
Click Save to complete the LLM model configuration.
Step 5: Configure agent memory¶
- By default, the agent comes preconfigured with an in-memory implementation.
- For this tutorial, we will keep the default memory configuration and not make any changes.
- If you prefer to run the agent without memory (in a stateless fashion), follow these steps:
- Click on the three vertical dots in the Memory box.
- Select the Delete option to remove the memory.
Step 6: Add tools to the agent¶
Ballerina Integrator (BI) allows you to create tools using existing functions. It also supports automatically generating tools from connector actions or OpenAPI specifications by leveraging BI’s capability to generate local connectors from an OpenAPI spec.
However, in this tutorial, we will create simple functions to perform arithmetic operations and use them as tools.
To create a function:¶
- Click the + button in the Ballerina Integrator side panel under the Functions section.
- Provide the required details to create the function. For this example, use
sum
as the function name, and specify the parameters and return types. - Implement the function logic in the flow node editor that opens.
To add the created function as a tool:¶
- Go to the agent flow view.
- Click the + button at the bottom-left corner of the
AI Agent
box. - Click the + button under the Tools section.
- Select the created function from the Current Integration list — in this case,
sum
. - Then provide the Tool Name and Description of the tool
Follow steps 1 to 3 to create functions named subtract, multiply and divide to perform subtraction, multiplication, and division operations respectively. Define the appropriate parameters and return types, and implement the corresponding logic in the flow node editor. Then repeat steps 4 to 8 to add each of these functions as tools in the agent by selecting them from the Current Integration list and providing a relevant tool name and description for each.
Step 7: Interact with the agent¶
After completing the above steps, your math tutor assistant is now ready to answer questions. Ballerina Integrator provides a built-in chat interface to interact with the agent.
To start chatting with the agent:
- Click the Chat button located at the top-left corner of the interface.
- You will be prompted to run the integration. Click Run Integration.
- Since we have created a configurable variable for
openAiApiKey
in step 4, provide it in theConfig.toml
file.
Note
A temporary OpenAI API key is used in the GIF below to showcase the steps.