Giving an AI Agent access to your emails

We want to provide an agent with the capability of accessing our Microsoft account to help us process our emails. We will take advantage of the Http request skill, and configure the OAuth authentication to use Microsoft Graph APIs. We will be configuring both the access in Microsoft Entra and the agent in Serenity* AI Hub.

Follow this steps to configure the OAuth authentication method.

1. We need to start by having an application registered in Microsoft. To do this, in the Microsoft Entra page, we will access the App registration section:

   

2. And click on New registration:

   

   It is important to add https://hub.serenitystar.ai/OAuth2Connection/AuthorizationCallback as a Redirect Uri to give the required permissions for the authentication.

   

3. On Serenity* AI Hub, we add a new HTTP request skill, and start configuring our integration. We will choose OAuth2 as authentication type and click on Create New to define it:

   

   You will see something like this, and we will go step by step through each of the fields:

   

   • Name: it is for using this configuration within the AI Hub.

   • Auth URL and Token URL: we will obtain it from Microsoft Entra. On your app registration, you can access the Endpoints list:

     

     In particular, we need the OAuth 2.0 authorization endpoint (v2) and the OAuth 2.0 token endpoint (v2)

     

   • Client Id: We obtain it directly from the app registration definition:

     

   • Client Secret: we will create a new secret from Microsoft Entra and link it on Serenity* AI Hub:

     

     Be aware that the expiration defined here will impact the actions that can be performed by the agent.

   • Scope: this will define which endpoints can be accessed with this authentication. The definition in Serenity* AI Hub has to match the permissions that were given to this application in Microsoft Entra. To do this, we go to the API permissions section:

     

     In this case, I want to use Microsoft Graph API, but from here it will depend on the implementation.

     

     

     

     

     In the Scope configuration in the AI Hub, we need to add all of this permissions separated by a white space.

     Important: apart from the scope you want to enable, always add “offline_access” to your scope to enable the authentication.

4. Now you are ready to test the connection. You should see a new tab opened, and if everything was configured correctly, it will have a message like this one:

   

5. Now we can finish configuring the Http request skill, to access our emails.

   In the Microsoft Graph documentation, you can see all of the different endpoints that are available. In particular, we will configure our skill to read our mailbox, and we will use this endpoint:

   https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0&tabs=http

   The parameters of the endpoint can be fully configured following this documentation: https://learn.microsoft.com/en-us/graph/query-parameters?tabs=http

   The following configuration for example, retrieves the sender and subject of 50 emails received since a variable date. The agent will decide the correct date based on the parameters.

   

   TIP: we recommend testing the requests from the Graph Explorer tool https://developer.microsoft.com/en-us/graph/graph-explorer?request=me%2Fmessages&version=v1.0

6. We will use a basic prompt, but ensure to (with the help of liquid) let the agent know what day it is today.

   Help the user process his emails.
   You only have access to the sender and subject of those emails.
   Take into account that today is {{ "now" | date: "%Y-%m-%d %H:%M" }}

7. We can try it out with a simple request:

   

And see the execution of the tool: