#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!