Unlock a world of possibilities! Login now and discover the exclusive benefits awaiting you.
In a previous post called Calling Snowflake's Cortex Agent API, I started the post by saying the focus of the post was about how the REST API worked not how to create the connection to it. This post is focused solely on how to create a REST API connector for Snowflake Cortex Agents.
Snowflake Agents
Snowflake allows you to build "agents." While I have built several, this post is going to focus on one that I called "SynthAgent."
They also provide a way you for you to question them directly in their user interface. I can simply ask a question like "Who are the top 10 admitting providers?" and voila ... I get an answer:
Actually as my previous post indicated, when you talk to an agent you actually get to see it's entire stream of thought.
Snowflake Cortex Agent API
While asking an isolated question inside of Snowflake is certainly handy-dandy, the bigger picture is in the fact that in the world we live in, agents should play nice with others. So, Snowflake created an API that allows others outside of the Snowflake user interface to speak with t....
Obviously you will need to use your own server and your own agents, but to help you understand the URL I wanted to show you the URL I will use in this post for this Cortex Agent API. Refer to the first image to see the database/schema/agent:
https://AYFR...mputing.com/api/v2/databases/SNOWFLAKE_INTELLIGENCE/schemas/AGENTS/agents/SYNTHAGENT:run
Creating your REST API Connector
While it's a rather complicated URL path, it is in fact nothing more than a URL path. Which is the most important thing that the Qlik Rest API Connector needs. Begin by creating a new connection. Be sure and choose the correct space where you want this new connector created and simply choose "REST".
Paste in the correct URL and choose the POST method:
After choosing POST as the method, the connector is going to prompt you for the BODY of the call.
My agent is built from a Snowflake Semantic View. Based on that, here is the sample body that I passed to my SYNTHAGENT URL:
{
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Who are the top 10 admitting providers?"
}
]
}
],
"tool_choice": {
"type": "auto"
}
}
Notice that I'm asking the exact same question that I asked directly in Snowflake so that I can test the results I get back to ensure it is working.
Additional request parameters
Based on the Snowflake Cortex Agent API documentation, you will need to configure a parameter and a few headers that are passed when calling the URL.
Query parameters
You need to have a parameter named Response-Type with the value text/event-stream
Query Headers
You need to create 4 Query Headers.
Authorization - This is to define the security for the API call. Snowflake provides multiple types of security. In this example I'm using a token model. To create your API Token, called Programmatic access token (PAT) in Snowflake you simply go to your profile, go to Settings and choose Authentication. Then Generate new token.
When you create the PAT, simply copy the value and in the value field type Bearer and then paste in your PAT.
User-Agent use QlikSense.
Accept simply use */*
Content-Type use application/json
Checking the box that isn't there
You had to hard code your question in the body, but in the real world in which you live are you always going to make all users, always see answers for just that question?"
This is when you need to reply out loud in your biggest voice "OF COURSE NOT!!!!"
Then I would say "So check that box that says Enable Dynamic Parameters" or any of the alternatives shown:
Because any of those check boxes would make total sense to you "Oh I need to check the box that allows me to change the question based on what my user asks."
Instead I need you check the box that only makes sense, after you know what it does. It's the check box that says Allow "WITH CONNECTION"
It will make sense in a few minutes why the button has that name. For now just now it relates to any of the 3 button names I wish it had. 😁
Test your connection
Finally give your connection a name and press the Test connection button.
If all of your security is configured correctly in Snowflake (Click here to see all of the things you need to ensure in Snowflake itself.) then you will get a Connection succeeded result.
If you see an error like "Unsupported Accept header null is specified. It simply means that you followed instructions from some other post and left out the Accept */* that I showed above an retest the connection.
Once you see the Connection succeeded save your connection so that we can actually make the call to the agent and see how the results look.
Calling the Connector
Congratulations you know have a connector in place to call your Snowflake Cortex Agent REST API. Woohoo. 😎
Click the Select data button for the connector
It will default to CSV for the response type which is perfect.
The Delimiter should be Tab.
Check the box for CSV Has header.
Check the CSV_source box.
Once you check that box it will go and make the call. If you see results like below you know that have in fact successfully asked your Snowflake Cortex Agent that question that was hard coded.
Press the Insert script button to actually insert the script block into your load script. Isn't this great I can reload my application and get answers to the same question over and over and over again. We are really living large. Right?
Our connector is working great, but I'm still hung up on that whole "same question over and over and over again thing." Logically what we would like to do, and more importantly can do ... is call the REST API and give it the question on the fly. In other words we would need to give it the BODY for the the call on the fly ... like this:
WITH CONNECTION
WITH CONNECTION is the syntax key word that is added to calls to REST API Connectors. Now I get why that checkbox that didn't make sense is called Allow WITH CONNECTION. It is letting you declare when you create the connection if the developers with access to the connection are allowed to do that or not. Glad they didn't rename them with any of the names I suggested. We would have a nightmare on our hands.
Now I have the ability to create a variable with the body, that has whatever question I want in it:
Results
When you look at the results you will realize that the Snowflake Cortex Agent API does not just return the answer to our question. It returns an entire event stream. Which is precisely why when we set the Response-Type parameter initially, we needed to set it to text/event-stream.
Great news is you have successfully created your REST API connector so you can talk to the Snowflake Cortex Agent. The next step is to check out my previous post where I walk you through how to process the results. https://community.qlik.com/t5/Member-Articles/Calling-Snowflake-s-Cortex-Agent-API/ta-p/2535284
PS - This post was planned for a later date. Be sure to thank @chriscammers for requesting it sooner. 😃
