#1069 OIC invoking OCI GenAI Agents - the basics

Introduction

Welcome to this simple example of invoking an OCI Gen AI Agent from OIC. This post will introduce GenAI Agents and how to leverage them from your integrations.

According to the docs - OCI Generative AI Agents is a fully managed service that combines the power of large language models (LLMs) with AI technologies to create intelligent virtual agents that can provide personalized, context-aware, and highly engaging customer experiences.

 So let's get started with a simple example. I will create an agent that will assist in processing expenses.

Create the OCI GenAI Agent

The menu from Gen AI Agents above gives us an idea of how this will be done. Firstly, I need a knowledge base, e.g. corporate rules around expenses. We will use the following rules from Commiskey Inc.

This is my knowledge base and I'll make it available to the Agent via OCI Object Storage - 

I created the Knowledge Base - 

with its data source - 

The Ingestion Job pulling in the file from Object Storage - 

I then created the Agent - 

The Agent also has an endpoint, which will receive requests - 

I copy the endpoint ocid, as I will need this later.

Let's try out the Chat function - 

Looks good, so now to leveraging the Agent from OIC. But first, let's take a look at the apis we will be invoking from OIC.

OCI GenAI Agent REST APIs

The api docs are here.

As you can see there are 2 groups of api, consider these management and runtime.

Management APIs 

I will invoke some of these from an integrations, using the API Endpoint base url for Chicago, as that's the region hosting my agent.

Runtime APIs 

I will be invoking the createSession and chat api in my integration, but more of that later.

Creating the Connections in OIC 

As you will probably realise, I will need to create 2 connections in OIC, one for the management api and another for the runtime/client api.

Naturally, I will also need to create the relevant Policies to allow my OIC instance to invoke these apis. My esteemed colleague, Harris Q. has documented an easy approach for doing this, so check out his post here. Net, net, here are my 2 connections - 

Note the security policy used, in both connection definitions.

OIC Invoking the Management APIs

So how did I proceed here? I started off with list knowledge bases - the invoke is configured as follows - 

I didn't know the response structure to begin with, so I initially set this to {}. I then ran the integration and copied and pasted the response json from the activity stream. 

I did the same for the other invokes.

I also externalised the ocids for endpoint and compartment -

So let's run this - 

The relevant JSON response is available under Wire Message received...

OIC Invoking the Runtime/Client APIs

The above 2 are the key invokes - create session and then, using the session id, invoke the chat api. 

createSession configuration 

The chat invoke is configured as follows -

Let's run it...

The response - 

{

  "response" : "I'd be happy to help you with your expenses query. 

  However, I have to advise you that the meal you're trying to expense doesn't quite meet our company's expenses rules.

  Firstly, the meal value of €150 exceeds the allowed limit of €100, as per reference 1. 

  Additionally, the beer you've had with your meal is not eligible for expensing, as per reference 2, which clearly states that no alcohol can be expensed.

  Lastly, I notice that the receipt date is May 9th, 2025, which falls on a Friday. According to reference 7, on Fridays, only fish meals can be expensed, 

  and since your meal consisted of steak, it doesn't meet this criteria.\n\nI'm afraid I won't be able to approve this expense. 

  If you have any other receipts that meet our company's expenses rules, I'd be more than happy to help you with those."

}

I can easily add multi-language support to the endpoint - here I use the management api - updateAgentEndpoint -

I re-run the integration with the following request payload - 

{

  "idleTimeoutInSeconds": 3600,

  "expenseNr": "1",

  "details": "Das Datum des Spesenbelegs ist der 9. Mai 2025. Kann ich ein Menü mit Steak und Bier im Wert von 130 € als Spesen abrechnen??"

}

 

The response - 

{

  "response" : "Hallo!\n\nIch verstehe, dass Sie ein Menü mit Steak und Bier im Wert von 130 € als Spesen abrechnen möchten. Leider muss ich Ihnen mitteilen, dass dies nicht möglich ist.\n\nGemäß unseren Spesenregeln (Referenz 1) dürfen Mahlzeiten nicht über 100 € kosten, und Ihr Menü liegt über diesem Betrag. Darüber hinaus ist es nicht erlaubt, Alkohol (Referenz 2) zu expensieren, und Bier fällt unter diese Kategorie.\n\nAußerdem fällt der 9. Mai 2025 auf einen Freitag, und gemäß unserer Regel (Referenz 7) dürfen an Freitagen nur Mahlzeiten mit Fisch expensiert werden, nicht mit Fleisch wie Steak.\n\nIch hoffe, Sie verstehen unsere Regeln und können Ihre Ausgaben entsprechend anpassen. Wenn Sie weitere Fragen haben, stehe ich Ihnen gerne zur Verfügung.\n\nMit freundlichen Grüßen,\nIhr Spesenberater"

}

I can also try in Gaeilge -

{

  "idleTimeoutInSeconds": 3600,

  "expenseNr": "1",

  "details": "Is é dáta Admhála Costais ná 9 Bealtaine 2025. An féidir liom béile steak agus beoir ar €130 a chaitheamh?"

}

{

  "response" : "Dia duit,\n\nTáim buíoch duit as do cheist. Mar chomhairleoir costais, táim ansin chun cabhrú leat a chinntiú go bhfuil do chostais i gcomhréir leis na rialacha atá leagtha amach.\n\nI ndáil le do cheist, táim afraid nach féidir leat béile steak agus beoir ar €130 a chaitheamh. Tá dhá fhadhb ann:\n\n1. Tá an béile thar an teorainn luach, €100, a luaitear i réamhshráid 1.\n2. Tá beoir san áireamh, agus de réir réamhshráid 2, ní ceadmhach é a chaitheamh.\n3. Chomh maith leis sin, tá an béile steak ar siúl ar Dé hAoine, agus de réir réamhshráid 7, ní ceadmhach béile le feoil a chaitheamh ar Dé hAoine - iasc amháin atá ceadmhach.\n\nTáim sásta cabhrú leat a chinntiú go bhfuil do chostais i gcomhréir leis na rialacha. Má tá aon cheist eile agat, ná bíodh drogall orm a chur in iúl.\n\nGo raibh maith agat,\n[Your Name]\nComhairleoir Costais"

} 

Summa Summarum

I accept the use case is banal, but I'm sure you can all extrapolate from it, and apply what I have done to your own use case(s). The post shows you can leverage OCI Gen AI Agents easily, from your OIC integrations. It really only a couple of minutes work. So try it out!

 

 

#1068 - OIC 25.04 New Features - Auto Retry actions generation in detail

Introduction

This post covers the details of leveraging the above, what it does, and what it doesn't do.

Here's a very simple example, based on the following integration, which, incidentally, uses a couple of the other new 25.04 features -

As you can see, the integration invokes a decision service to get the discount to be applied to this order. It also checks if the order is large, e.g. greater than €5000.

Our store is selling Samuel Beckett t-shirts, so a €5k order is definitely suspicious. Large orders need to be approved, by a sales manager, thus the Process invoke.

Let's do a dry run, with a large order - 

Looks good, behaving as it should - 

Now let's try with a smaller order - this should return an error from Netsuite, as I have set the Sales Order status to an invalid value.

I will now add the retry logic, although it won't help us fix this invalid data issue. However, I just want to detail what will be generated and what you may need to do afterwards to complete error handling. Begin by adding the retry logic - 

The basics of what's generated are discussed in my previous post.  

Net, net - default is to retry 3 times -

let's test this out - 

So what happened here? Well the first action in the integration is setting a return status - 

Checking the activity stream - I see 3 attempts to insert the new sales order into Netsuite - 

The logic is simple - the error is thrown back to the Fault Handler that has been generated for you. It checks if the max number of retries has been reached. If so, the integration just continues processing.

Naturally, that is not what I want, so I add supplementary error handling here in the Otherwise branch -

The mapping is as follows -

Type and Title are hardcoded. The other fields get their data from the following source - 

I could also have rethrown the fault to a global fault handler, so it's up to you how to handle this.

Net, net - the auto generation of retry actions, does just that. You may need to augment what has been generated, with your own fault handling logic.

Summa Summarum

This is a very valuable new feature in 25.04, so do check it out, it will save you time and effort. For those interested - Samuel Beckett, probably the most unread winner of the Nobel Prize for Literature, was born in Dublin, Ireland in 1906 and died in Paris in 1989. I can highly recommend him to those of you who appreciate Kafka and my own good self (check out my works on Amazon). Try his book, Murphy, to start with; written in the 1930s, it may appear dated to begin with, but it does deal with the meanings of lives in a very humorous manner.