AI Engine Chat API

Most of the endpoints depends on various instances and are considered parameters for the actual endpoint, but these are not meant to be passed directly by the user.

Instead, these instance-dependent elements are integrated and managed directly by the backend system. We refer to them as *name_parameter, where the asterisk (*) is used to denote a specific instance-dependent parameter that the route relies on.

Mind that: to access these APIs, user must be authenticated and have the correct permissions.

Overview

The AI Engine Chat API allows you to interact with the DeltaV backend, allowing you to interact with your agents and more.

Endpoints


GET /v1beta1/engine/chat/sessions
 
POST /v1beta1/engine/chat/sessions
 
DELETE /v1beta1/engine/chat/sessions/:session_id
 
POST /v1beta1/engine/chat/sessions/:session_id/submit
 
GET /v1beta1/engine/chat/sessions/:session_id/responses (Deprecated)
 
GET /v1beta1/engine/chat/sessions/:session_id/messages (Deprecated)
 
GET /v1beta1/engine/chat/sessions/:session_id/messages/all
 
GET /v1beta1/engine/chat/sessions/:session_id/new-messages
 
POST /v1beta1/engine/chat/sessions/:session_id/feedback
 
GET /v1beta1/engine/chat/remaining_tokens

Starting your session

POST

/v1beta1/engine/chat/sessions

Request

Start a new session for a user authenticated through JWT.

Name
payload
Type
JSON
Required
required
Description
Contains the data for the type of payload being sent.
Name
email
Type
email
Required
required
Description
The email of the user
Name
requestModel
Type
string
Required
required
Description
The request model wherein the user wants to interact.
Name
functionGroup
Type
string
Required
required
Description
The function group that the user wants to interact with. Previously known as service_group. Defaults to Public group!

Responses

Returns the newly created Session object.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions" \
  -d '{
  "email": "your_email_address",
  "requestedModel": "talkative-01",
  "functionGroup": "12c8601c-cccd-42de-a5f1-7eab76ae3121"
}'

HTTP 200

[
  {
    "session_id": "c320b5c4-518c-428b-889d-3cb8403901c0",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "model": "talkative-01",
    "remaining_tokens": 10000000,
    "function_group": "12c8601c-cccd-42de-a5f1-7eab76ae3121"
  }
]

Get all sessions for a user

GET

/v1beta1/engine/chat/sessions

Request

Retrieves all sessions for a user authenticated through JWT.

Responses

Returns a list of Session objects associated with the user.

Curl

curl -X GET \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions"

HTTP 200

[
  {
    "session_id": "7be16891-39a6-44a6-88cb-377250dd8eb7",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "function_group": "12c8601c-cccd-42de-a5f1-7eab76ae3121",
    "model": "talkative-01",
    "remaining_tokens": 9999099
  },
  {
    "session_id": "aed47bb4-9d73-4135-89f7-925036aa83bd",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "function_group": "12c8601c-cccd-42de-a5f1-7eab76ae3121",
    "model": "talkative-01",
    "remaining_tokens": 9999099
  }
]

Sending a new message

There are 4 types of messages that can be sent to the backend:

start: This is the first message that should be sent to the AI Engine for full session (search + execution). It contains the objective and context of the conversation. The objective and context are used to determine which agent to use for the conversation.
execute_functions: This is the first message that should be sent to the AI Engine for execution only (no search). It contains the list of function-ids you want to execute and a function group (for secondary function picks).
user_message: This is a message sent by the user.
user_json: This is a JSON message sent by the user.
stop: This is the last message that should be sent to the backend. It indicates that the conversation has ended.

IMPORTANT: you need to either send start or execute_functions. These two can’t be combined.

Sending start message

POST

/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Sending start message

Name
payload
Type
JSON
Required
required
Description
Contains the data for the type of message being sent.
Name
type
Type
string
Required
required
Description
The type of message being sent. For starting the session set it to 'start'.
Name
objective
Type
string
Required
required
Description
The objective of the conversation. This is used to determine which agent to use for the conversation.
Name
context
Type
string
Required
required
Description
The context of the conversation. This is used to give information about the user to the agent.
Name
recommend_only
Type
boolean
Required
required
Description
Optional flag, if is set to true, AI Engine will only do search, it will match your objective to functions/agents and then stops. False by default. Only supported by Next Generation personality.
Name
session_id
Type
string
Required
required
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

Responses

If the request is successful, there will be no response.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit" \
  -d '{
  "payload": {
    "type": "start",
    "objective": "I'd like to go to London",
    "context": "User full Name: Test User\nUser email: [email protected]\nUser location: latitude=51.5072, longitude=0.1276\n"
  }
}'

HTTP 200

Sending execute functions message

POST

/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Sending execute functions message. Currently only supported by Next Generation personality. Don't use this if you already sent 'start' message.

Name
payload
Type
JSON
Required
required
Description
Contains the data for the type of message being sent.
Name
type
Type
string
Required
required
Description
The type of message being sent. Set it to 'execute_functions'.
Name
functions
Type
string[]
Required
required
Description
List of function ids you want the system to execute.
Name
objective
Type
string
Required
required
Description
The objective of the conversation. This will guide context building.
Name
context
Type
string
Required
required
Description
The context of the conversation. This is used to give information about the user to the agent.
Name
session_id
Type
string
Required
required
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

Responses

If request is successful, there will be no response.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit" \
  -d '{
  "payload": {
    "type": "execute_functions",
    "functions": [
      "b320b5c4-518c-428b-889d-3cb8403901c0"
    ],
    "objective": "",
    "context": ""
  }
}'

HTTP 200

Sending user message

POST

/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Send an answer to a question asked by the agent

Name
payload
Type
JSON
Required
required
Description
Contains the data for the type of message being sent.
Name
type
Type
string
Required
required
Description
The type of message being sent.
Name
user_message
Type
string
Required
required
Description
The user response to a question asked by the agent or to confirm the context
Name
session_id
Type
string
Required
required
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

Responses

If request is successful, there will be no response.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit" \
  -d '{
  "payload": {
    "type": "user_message",
    "user_message": "The booking is for 2 people"
  }
}'

HTTP 200

Sending user json message

POST

/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Sending an option in a task list requested by an agent

Name
payload
Type
JSON
Required
required
Description
Contains the data for the type of message being sent. The payload is different for each type of message.
Name
type
Type
string
Required
required
Description
The type of message being sent.
Name
user_json
Type
JSON
Required
required
Description
The objective of the conversation. This is used to determine which agent to use for the conversation.
Name
user_json-type
Type
string
Required
required
Description
The context of the conversation. type: `task_list`, `options`. `task_list` is used to select a task pertaining to a specific agent. `options` is used to select a subtask pertaining to a specific agent or select an option from a list of suggestions given by the agent.
Name
user_json-selection
Type
array
Required
required
Description
The selection of the user from the list of options. The selection is an array of integers or UUID4
Name
session_id
Type
string
Required
required
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

Responses

If request is successful, there will be no response.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit" \
  -d '{
  "payload": {
    "type": "user_json",
    "user_json": {
      "type": "task_list | options",
      "selection": [
        "0 | 9f157712-472d-4f0d-814d-d5aae9fd7b28"
      ]
    }
  }
}'

HTTP 200

Sending stop message

POST

/v1beta1/engine/chat/sessions/{session_id}/submit

Request

Sending a stop message to an agent

Name
payload
Type
JSON
Required
required
Description
Contains the data for the type of message being sent. The payload is different for each type of message.
Name
type
Type
string
Required
required
Description
The type of message being sent.
Name
session_id
Type
string
Required
required
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

Responses

If request is successful, there will be no response.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit" \
  -d '{
  "payload": {
    "type": "stop"
  }
}'

HTTP 200

Delete a session for a user

DELETE

/v1beta1/engine/chat/sessions/{session_id}

Request

Delete a specific session given a session id for a user authenticated through JWT.

Responses

Curl

curl -X DELETE \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}"

HTTP 200

Fetch all messages sent by an Agent in a session

GET

/v1beta1/engine/chat/sessions/{session_id}/messages/all

Request

Fetches agent messages filtered by timestamps for a specific session identified by the session_id

Name
session_id
Type
string
Required
required
Description
The unique identifier of the chat session for which all messages are being retrieved.

Responses

Returns all messages sent by the Agent for a specific session.

Curl

curl -X GET \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/messages/all"

HTTP 200

[
  {
    "session_id": "063fcfef-a3ec-46c4-aa8e-c9a51b6f24b7",
    "messages": [
      {
        "message_id": "24df920c-a8eb-41cb-aa10-4283d0602d5e",
        "timestamp": "2023-08-31T13:26:23.238697",
        "score": 0,
        "type": "agent_json",
        "agent_json": {
          "type": "task_list",
          "text": "Found tasks for your objective. Please select.",
          "options": [
            {
              "key": 0,
              "value": "TopActivities/TopActivities"
            },
            {
              "key": 1,
              "value": "Flights/Flights"
            },
            {
              "key": 2,
              "value": "Hotels/Hotels"
            }
          ],
          "context_json": null
        }
      },
      {
        "message_id": "922c9be4-28dd-4fdb-9b91-fc26f360d86c",
        "timestamp": "2023-08-31T13:26:42.093485",
        "score": 0,
        "type": "agent_info",
        "agent_info": "I start building the context to execute 'TopActivities/TopActivities' task.."
      }
    ]
  }
]

Retrieve new messages sent by Agent (with possible duplicate or missed messages)

GET

/v1beta1/engine/chat/sessions/{session_id}/new-messages

Request

Retrieves a batch of new messages since the last retrieved message for a specific chat session.

Name
session_id
Type
UUID4
Required
required
Description
The unique identifier of the chat session. It must be a valid UUID4 string.
Name
last_message_id
Type
string
Required
optional
Description
The message ID of the last message that was retrieved. This is optional and, if provided, the service will return messages that were sent after this message.

Responses

Returns a list of new messages for the session. If specified, it returns the messages since the last checked message. If there are no new messages, an empty list is returned. If the session is not found, a 404 error with a descriptive message is returned.

Curl

curl -X GET \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/new-messages"

HTTP 200

[
  {
    "status": 200,
    "agent_response": [
      {
        "session_id": "063fcfef-a3ec-46c4-aa8e-c9a51b6f24b7",
        "messages": [
          {
            "message_id": "24df920c-a8eb-41cb-aa10-4283d0602d5e",
            "timestamp": "2023-08-31T13:26:23.238697",
            "score": 0,
            "type": "agent_json",
            "agent_json": {
              "type": "task_list",
              "text": "Found tasks for your objective. Please select.",
              "options": [
                {
                  "key": 0,
                  "value": "TopActivities/TopActivities"
                },
                {
                  "key": 1,
                  "value": "Flights/Flights"
                },
                {
                  "key": 2,
                  "value": "Hotels/Hotels"
                }
              ],
              "context_json": null
            }
          },
          {
            "message_id": "922c9be4-28dd-4fdb-9b91-fc26f360d86c",
            "timestamp": "2023-08-31T13:26:42.093485",
            "score": 0,
            "type": "agent_info",
            "agent_info": "I start building the context to execute 'TopActivities/TopActivities' task.."
          }
        ]
      }
    ]
  }
]

Provide feedback for a session

POST

/v1beta1/engine/chat/sessions/{session_id}/feedback

Request

Give feedback for a specific session identified by the session_id

Name
models
Type
array
Required
required
Description
Contains the list of models that the user wants to query for remaining tokens. It is an array of strings where each string is the name of the model.
Name
feedback
Type
string
Required
required
Description
The feedback of the user. It can be positive or negative.
Name
session_id
Type
string
Required
required
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

Responses

Retrieves the remaining tokens for the models that have been queried.

Curl

curl -X POST \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/feedback" \
  -d '{
  "feedback": "positive"
}'

HTTP 200

{
  "model_tokens": {
    "talkative-01": 9999099,
    "creative-01": 5000000
  }
}

Retrieve remaining tokens

GET

/v1beta1/engine/credit/remaining_tokens?models=talkative-01,creative-01&[email protected]

Request

Request for retrieving the amount of tokens left for each model

Name
models
Type
array
Required
required
Description
Contains the list of models that the user wants to query for remaining tokens. It is an array of strings where each string is the name of the model.
Name
email
Type
string
Required
required
Description
The email of the user

Responses

Retrieves the remaining tokens for the models that have been queried.

Curl

curl -X GET \
  -H "Authorization: bearer <your token here>" -H "Content-Type: application/json" \
  "https://agentverse.ai/v1beta1/engine/credit/remaining_tokens?models=talkative-01,creative-01&[email protected]"

HTTP 200

{
  "model_tokens": {
    "talkative-01": 9999099,
    "creative-01": 5000000
  }
}