|
| 1 | +# AI agent integration |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +### Obtain OpenAI API key |
| 8 | + |
| 9 | +- Sign up at [OpenAI](https://platform.openai.com/signup/). |
| 10 | +- Get an API key from the [API section](https://platform.openai.com/docs/api-reference/authentication). |
| 11 | + |
| 12 | +### Step 1: Create a new integration project |
| 13 | + |
| 14 | +1. Click on the **`Ballerina Integrator`** icon in the sidebar. |
| 15 | +2. Click on the **`Create New Integration`** button. |
| 16 | +3. Enter the project name as `MathTutor`. |
| 17 | +4. Select the project directory location by clicking on the **`Select Location`** button. |
| 18 | +5. Click the **`Create New Integration`** button to generate the integration project. |
| 19 | + <a href="{{base_path}}/assets/img/ai-agent/ai-agent-step1.gif"><img src="{{base_path}}/assets/img/ai-agent/ai-agent-step1.gif" alt="Create a New Integration Project" width="70%"></a> |
| 20 | + |
| 21 | +### Step 2: Create an agent |
| 22 | + |
| 23 | +1. Click the `+` button on the Ballerina Integrator side panel or navigate back to the Design screen and click on **`Add Artifact`**. |
| 24 | +2. Select **`AI Chat Agent`** under the **`AI Agent`** artifacts. |
| 25 | +3. Provide a **`Name`** for the agent. It will take a moment to create an agent with the default configuration. |
| 26 | +4. After creating the agent, you can configure it with a model provider, memory, tools, roles, and instructions. |
| 27 | + <a href="{{base_path}}/assets/img/ai-agent/ai-agent-step2.gif"><img src="{{base_path}}/assets/img/ai-agent/ai-agent-step2.gif" alt="Create an Agent" width="70%"></a> |
| 28 | + |
| 29 | +### Step 3: Configure the agent behavior |
| 30 | + |
| 31 | +1. Click on the **`AI Agent`** box to open the agent configuration settings. |
| 32 | +2. Define the agent's **`Role`** and provide **`Instructions`** in natural language. These instructions will guide the agent’s behavior and tasks. |
| 33 | +3. Click **`Save`** to finalize and complete the agent behavior configuration. |
| 34 | + <a href="{{base_path}}/assets/img/ai-agent/ai-agent-step3.gif"><img src="{{base_path}}/assets/img/ai-agent/ai-agent-step3.gif" alt="Configure the Agent Behavior" width="70%"></a> |
| 35 | + |
| 36 | +### Step 4: Configure the agent model |
| 37 | + |
| 38 | +1. Locate the circle connected to the **`AI Agent`** box. This circle represents the LLM model used by the agent. |
| 39 | +2. Click on the circle to open the model configuration options. |
| 40 | +3. In the **`Select Model Provider`** dropdown, choose **`OpenAiProvider`**. |
| 41 | +4. Next, provide the OpenAI API key in the **`API Key`** input field. |
| 42 | +!!! note |
| 43 | +Since the API key is sensitive it's recommended to create a configurable named `openAiApiKey` and use it as the value for the **`API Key`** field. |
| 44 | +5. In the **`Model Type`** dropdown, select `ai:GPT_40`. |
| 45 | +6. Click **`Save`** to complete the LLM model configuration. |
| 46 | + <a href="{{base_path}}/assets/img/ai-agent/ai-agent-step4.gif"><img src="{{base_path}}/assets/img/ai-agent/ai-agent-step4.gif" alt="Configure the Agent Model" width="70%"></a> |
| 47 | + |
| 48 | +### Step 5: Configure agent memory |
| 49 | + |
| 50 | +1. By default, the agent is preconfigured with memory. |
| 51 | +2. For this tutorial, we will keep the default memory configuration and not make any changes. |
| 52 | +3. If you prefer to run the agent without memory (in a stateless fashion), follow these steps: |
| 53 | + - Click on the three vertical dots in the **`Memory`** box. |
| 54 | + - Select the **`Delete`** option to remove the memory. |
| 55 | + |
| 56 | +### Step 6: Add tools to the agent |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +However, in this tutorial, we will create simple functions to perform arithmetic operations and use them as tools. |
| 61 | + |
| 62 | +#### To create a function: |
| 63 | + |
| 64 | +1. Click the **`+`** button in the Ballerina Integrator side panel under the **`Functions`** section. |
| 65 | +2. Provide the required details to create the function. For this example, use `sum` as the function name, and specify the parameters and return types. |
| 66 | +3. Implement the function logic in the flow node editor that opens. |
| 67 | + |
| 68 | +#### To add the created function as a tool: |
| 69 | + |
| 70 | +4. Go to the agent flow view. |
| 71 | +5. Click the **`+`** button at the bottom-left corner of the `AI Agent` box. |
| 72 | +6. Click the **`+`** button under the **`Tools`** section. |
| 73 | +7. Select the created function from the **`Current Integration`** list — in this case, `sum`. |
| 74 | +8. Then provide the **`Tool Name`** and **`Description`** of the tool |
| 75 | + |
| 76 | +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. |
| 77 | + |
| 78 | +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. |
| 79 | +<a href="{{base_path}}/assets/img/ai-agent/ai-agent-step6.gif"><img src="{{base_path}}/assets/img/ai-agent/ai-agent-step6.gif" alt="Add Tools to the Agent" width="70%"></a> |
| 80 | + |
| 81 | +### Step 7: Interact with the agent |
| 82 | + |
| 83 | +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. |
| 84 | + |
| 85 | +To start chatting with the agent: |
| 86 | + |
| 87 | +1. Click the **`Chat`** button located at the top-left corner of the interface. |
| 88 | +2. You will be prompted to run the integration. Click **`Run Integration`**. |
| 89 | +3. Since we have created a configurable variable for `openAiApiKey` in step 4, provide it in the `Config.toml` file. |
| 90 | + |
| 91 | +!!! note |
| 92 | +A temporary OpenAI API key is used in the GIF below to showcase the steps. |
| 93 | + <a href="{{base_path}}/assets/img/ai-agent/ai-agent-step7.gif"><img src="{{base_path}}/assets/img/ai-agent/ai-agent-step7.gif" alt="Interact With the Agent" width="70%"></a> |
0 commit comments