AI Tutorials
With Emporix support for AI, you can enhance text for product descriptions and generate AI completions.
Before you start
Make sure to configure your API token. To do that, you can use the Configuration Service and store the token under openAiApiToken key.
Send the request to the Creating Configurations endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
curl -L
--request POST
--url 'https://api.emporix.io/configuration/{tenant}/configurations'
--header 'Content-Type: application/json'
--data '[
{
"_id": "openAiApiToken",
"value": "mc-ZtG7zOY9lywNv2539383fLeJr34444",
"version": 1,
"secured": false
}
]How to generate an AI supported text for a product
You can generate the text by sending a request based on a provided prompt. To send the request, use the Text Generation endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
curl -i -X POST
'http://api.emporix.io/ai-service/{tenant}/texts'
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
-H 'Content-Type: application/json'
-d '{
"id": "en",
"prompt": "Generate a long description for product '\''pipe cutter'\'' in language EN ",
"maxTokens": 2048
}'How to generate an AI completion
Completion is generated based on chat history. It's a generated response or continuation of a conversation, crafted by the AI to address the given input in context. It can include answering questions, providing suggestions, or completing a sentence or thought. The currently supported AI engine for the completion is OpenAI. To generate the AI completion, send the request using the AI Completions endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
curl -i -X POST
'http://api.emporix.io/ai-service/{tenant}/completions'
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
-H 'Content-Type: application/json'
-d '{
"id": "abc-123",
"messages": [
{
"role": "SYSTEM",
"content": "You are an assistant responsible for creating a configuration based on information provided by user."
}
]
}'How to create an AI agent using a template
Create an AI agent using one of Emporix agent template.
Get the agent template ID
To create an agent, you'll need a template ID.
Either, retrieve all the available agent templates by calling the Listing available agent templates endpoint.
curl -L \
--url 'https://api.emporix.io/ai-service/{tenant}/agentic/templates' \
--header 'Accept: */*'Use the Searching agent templates endpoint to find the specific agent template.
curl -L \
--request POST \
--url 'https://api.emporix.io/ai-service/{tenant}/agentic/templates/search' \
--header 'Content-Type: application/json' \
--data '{
"q": "name:~Support"
}'Copy and note down the template ID of your interest.
Create an agent
Call the Creating agent instance based on the template endpoint to add an agent to your system. In the path parameter, provide the templateID you have copied.
curl -L \
--request POST \
--url 'https://api.emporix.io/ai-service/mytenant/agentic/templates/123/agent' \
--header 'Content-Type: application/json' \
--data '{
"name": {
"en": "Complaint Agent"
},
"description": {
"de": "Agent which is responsible for reading emails and base on that resolve the customer's complaints"
},
"id": "a81bc81b-dead-4e5d-abff-90865d1e13b1"
}'How to search for the AI Agents
When you want to add a trigger for an enabled AI agent through API, for example as a part of a digital process or from an external system, you need to fetch the specific agent details.
Use the Searching agents endpoint to pass a query parameter against the agents in your system.
For example, to find agents of Complaint type:
curl -L \
--request POST \
--url 'https://api.emporix.io/ai-service/mytenant/agentic/agents/search' \
--header 'Content-Type: application/json' \
--data '{
"q": "name:~Complaint"
}'If you know the agent's ID, you can use the Retrieving the agent by ID endpoint.
curl -L \
--url 'https://api.emporix.io/ai-service/mytenant/agentic/agents/invoice-complaint' \
--header 'Accept: */*'You can use the retrieved details to establish the required connections and triggers for the AI Agent.
How to communicate with an Agent
For some Agents, it is convenient to trigger their actions by API calls. To allow communication with the selected agent, you can use the dedicated endpoints.
When instant responses are required from the agent, send the request to the Starting agent chat
curl -L 'https://api.emporix.io/ai-service/{tenant}/agentic/chat' \
-H 'tenant: {tenant}' \
-H 'scopes: ai.completion_manage' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic {token}' \
-d '{
"agentId": "de-agent",
"message": "{\"id\":\"delightCoffee\",\"name\":{\"en\":\"Delight Coffee\"},\"yrn\":\"urn:yaas:saasag:caasproduct:product:{tenant};delightCoffee\",\"code\":\"delightCoffee\",\"description\":{\"en\":\"Awaken your senses with our hand-selected Gourmet Coffee, crafted for true coffee lovers who crave depth, aroma, and sophistication in every sip. Sourced from the world’s finest high-altitude farms, each bean is carefully harvested at peak ripeness, then small-batch roasted to unlock its natural sweetness and complex flavor notes.\"},\"media\":[],\"productType\":\"BASIC\",\"template\":{},\"published\":false,\"metadata\":{\"version\":1,\"createdAt\":\"2025-09-25T04:42:42.607Z\",\"modifiedAt\":\"2025-09-25T04:42:42.607Z\"}}"
}'Trigger the specific agent providing its agentId. In the message, type in your query or data you want the agent to process.
In the above example, the German Translation Agent is triggered. The Agent acts according to its defined prompt - here, the agent is programmed to find the product name and description in the request message and translate the fields into German language. As a result, the Agent gets back with the following response:
{
"agentId": "de-agent",
"agentType": "generic",
"message": "{
"id":"delightCoffee",
"name":{
"en":"Delight Coffee",
"de":"Delight Kaffee"
},
"yrn":"urn:yaas:saasag:caasproduct:product:mytenant;delightCoffee",
"code":"delightCoffee",
"description":{
"en":"Awaken your senses with our hand-selected Gourmet Coffee, crafted for true coffee lovers who crave depth, aroma, and sophistication in every sip. Sourced from the world’s finest high-altitude farms, each bean is carefully harvested at peak ripeness, then small-batch roasted to unlock its natural sweetness and complex flavor notes.",
"de":"Wecken Sie Ihre Sinne mit unserem handverlesenen Gourmetkaffee, kreiert für wahre Kaffeeliebhaber, die Tiefe, Aroma und Raffinesse in jedem Schluck suchen. Aus den besten Hochlandfarmen der Welt bezogen, wird jede Bohne sorgfältig zum Höhepunkt ihrer Reife geerntet und dann in kleinen Chargen geröstet, um ihre natürliche Süße und komplexen Geschmacksnoten freizusetzen."
},
"media":[],
"productType":"BASIC",
"template":{},
"published":false,"metadata":{
"version":1,
"createdAt":"2025-09-25T04:42:42.607Z",
"modifiedAt":"2025-09-25T04:42:42.607Z"
}
}",
"sessionId": "33a550d0-d812-4fb2-bb0d-d50dbfe3627b"
}When it is more pragmatic to wait for the agent's response, for example, when the agent needs to process more data which takes more time, or the agent needs to wait for another task to be completed, use the asynchronous communication. Send the request to the agent using the Starting agent async chat.
curl -L 'https://api.emporix.io/ai-service/{tenant}/agentic/chat-async' \
-H 'tenant: {tenant}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic {token}' \
-d '{
"agentId": "complaint-agent",
"message": Find the details of the customer order \"EON1243\"."
}'Similarly, provide the relevant agentId and pass your query in the message.
In async requests, the response contains the jobId parameter, for example:
{
"jobId": "68e3a593b2cb061e36630849"
}Use the jobId to check details of the job through the Retrieving agent job by its ID endpoint. For example:
curl -X 'GET' \
'https://api.emporix.io/ai-service/{tenant}/jobs/68e3a593b2cb061e36630849' \
-H 'accept: application/json'The job entity contains information about the request and response from the agent.
Last updated
Was this helpful?