Linking an Orchestration Server
This guide provides information on how to connect to a Natural Language Processing (NLP) platform via an Orchestration Server. NLP is a type of Artificial Intelligence (AI) that extracts meaning from human language to make decisions or responses based on available information.
Soul Machines Digital People leverage NLP platforms to:
Understand the user’s intention or inquiry by analyzing their utterance.
Select the proper pre-written response from a finite set of responses.
If you are using any of the supported NLP platforms, you can connect these services directly to your Digital Person from the Digital DNA Studio. However, if you are using another NLP platform or need a business logic layer between your Digital Person and your NLP, then Building an NLP Skill is recommended.
Alternatively, you can use an Orchestration Server. The Soul Machines Orchestration Layer is an additional layer of logic that is hosted on a separate server from the Soul Machines Cloud Platform, operated by the customer.
Soul Machines can provide you with the basic starting code template (In Node JS programming language) for the Orchestration Server. This template is completely customizable to suit any integration needs.
You can quickly get started with this sample code
https://github.com/soulmachines/orchestration-nodejs
Note that you are required to host the Orchestration Server on your own infrastructure, and its endpoints must be publicly accessible.
Audience
This document is intended for Technical personnel, e.g. Solution Architects, Developers, Testers, etc. who want to utilize and configure a separate Orchestration Server to meet their NLP requirements. Information in this document may also be useful to Business users who would like to gain some insight on how other types of NLP platforms can be supported with the use of an Orchestration Server.
Please contact your Soul Machines representative, if you require further assistance in using this guide.
Digital DNA Studio Configuration
To use an Orchestration Server with a Digital DNA Studio deployed Digital Person, add the Orchestration Skill to the Knowledge section in the Digital DNA Studio configuration screen.
Follow the instructions displayed under the Orchestration section to fill in the fields as required to establish the connection to your Orchestration Server.
When developing locally, it is possible to run an Orchestration Server locally for testing or debugging purposes. This requires the server URL (typically ‘localhost’) and your public IP to be specified. You can specify a whitelist with multiple IP address blocks in IPv4 or IPv6 formats. This makes it easier to share a project between multiple developers in different locations. For example, 92.0.2.1/24
or 2001 : db8: 3333 : 4444 : 5555 : 6666 : 7777 : 8888
In Production mode, developing locally is switched off and only a server URL is required (must be HTTPS or wss protocol for security).
Orchestration Server Messages
Overview
Soul Machines uses a bi-directional WebSocket connection to send a message back and forth between our servers and your Orchestration Server. Each message is JSON encoded and sent as a web socket ‘text’ message over HTTPS or WSS. Each JSON encoded message includes some standard fields for the kind of message communicated.
There are three kinds of messages: event, request, and response. In this guide, we only cover the messages relevant to connecting to the NLP platform.
Event
Each event includes the category (‘scene’), kind (‘event’), name, and body. Events are sent by the Digital Person to all connected servers and the connected client web browser (if any).
Request
Each request includes the category (‘scene’), kind (‘request’), name, transaction, and body. Requests are sent from the Server to the Scene. If the transaction is not null, then a response is sent for the request. The transaction is an integer that is unique across all requests and is included in the response. If no transaction is included, then no response is sent—the request is one way.
Response
Each response includes the category (‘scene’), kind (‘response’), name, transaction (from the matching request), status (the C SDK status integer where >= 0 is success, < 0 is failure), and body. Responses are sent from the Scene to the Server.
The following section describes the conversation messages that must be used by any Orchestration Server implementation.
Conversation Messages
The Speech-To-Text (STT) results are sent via the conversationRequest
(see input.text field) message.
To instruct the Digital Person to speak you must send a conversationResponse
(output.text).
The Orchestration Server can send conversationResponse
messages without a prior request. This type of "spontaneous" conversation message can be used when the Orchestration Server wants to command the Digital Person to speak spontaneously (without any prior request).
The Orchestration Server implementation needs to ensure that all conversationRequest
messages are matched with a corresponding conversationResponse
message, the output text can be empty if necessary.
We do not queue messages from Orchestration servers. Any messages sent to the Digital Person from the Orchestration Server while it is already speaking will not be spoken. To prevent this, implement code that checks if the Digital Person's speechState
is 'idle' before sending the next message.
Sample Conversation Messages:
// Example conversationRequest message (sent by the SDK):
{
"category": "scene",
"kind": "event",
"name": "conversationRequest",
"body": {
"personaId": 1,
"input" : {
"text" : "Can I apply for a credit card?"
},
"variables" : {
// conversation variables
}
}
// Example conversationResponse message (sent by the orch server):
{
"category": "scene",
"kind": "request",
"name": "conversationResponse",
"transaction": None,
"body": {
"personaId": 1,
"output" : {