Interface IAIAgent

Interface for the AI Agent AI services, such as Translation, Statistics, Sentiment analysis, backed by calls to Public Cloud providers

Namespace: SuperOffice.CRM.Services

Assembly: SuperOffice.Services.dll

Syntax

[Agent("AI Agent", "Interface for the AI Agent. AI services, such as Translation, Statistics, Sentiment analysis, backed by calls to Public Cloud providers")]
public interface IAIAgent : IAgent

Examples

using SuperOffice;
using SuperOffice.CRM.Services;

using (SoSession mySession = SoSession.Authenticate("user", "pass"))
{
   using (AIAgent agent = new AIAgent())
   {
      // call methods on agent here...
   }
}

Methods

AnswerAcceptedAsync(string, CancellationToken)

Signal that answer was inserted into response- feedback is logged and used to improve the answer algorithm.

Declaration

Task AnswerAcceptedAsync(string trackingId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	trackingId	The id of the answer that you are giving feedback to.
CancellationToken	cancellationToken

Returns

Type	Description
Task	This method has no return value

AnswerAsync(string, string, RagType, int, CancellationToken)

Returns an answer.

Declaration

Task<RagAnswer> AnswerAsync(string namespaceName, string query, RagType type, int top, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	namespaceName	Defines the search domain used for generating answer. e.g. 'ServiceCopilot'
string	query	Question. The search query to answer.
RagType	type	Filter results based on content type. Default: None = no filtering
int	top	Max Number of results to use in generating answer.
CancellationToken	cancellationToken

Returns

Type	Description
Task<RagAnswer>	Generated answer based on query.

AnswerFeedbackAsync(string, bool, CancellationToken)

Send feedback on answer - feedback is logged and used to improve the answer algorithm.

Declaration

Task AnswerFeedbackAsync(string trackingId, bool isThumbsUp, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	trackingId	The id of the answer that you are giving feedback to.
bool	isThumbsUp	True = Like, False = Dislike.
CancellationToken	cancellationToken

Returns

Type	Description
Task	This method has no return value

ClearChatbotTurnsAsync(string, CancellationToken)

Clears the stored history of chat messages for a given chat_id. Chat_id is usually derived from soproto + current id, but could also be arbitrary name

Declaration

Task ClearChatbotTurnsAsync(string chatId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	chatId	identifies this chat = arbitrary name (e.g. user-defined) or the soprotocol + id (e.g. ticket-123, contact-43, diary)
CancellationToken	cancellationToken

Returns

Type	Description
Task	This method has no return value

CreateTextForAppointmentAsync(AppointmentEntity, string, CancellationToken)

Generate agenda text for an appointment based on appointment's company category, title, person, etc.

Declaration

Task<string> CreateTextForAppointmentAsync(AppointmentEntity appointment, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
AppointmentEntity	appointment	The appointment object to generate text for.
string	isoLangCode	Language returned text should be in. Blank = do not specify language.
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	Agenda text in markdown format

DetectLanguageAsync(string, CancellationToken)

Given a (reasonably short) text, detect the language it is written in

Declaration

Task<string> DetectLanguageAsync(string text, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	text	Text to be analyzed; there may be a cost-per-character so do not send a book here
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	ISO Language code, such as NO, US, ES, FR

DetectSentimentAsync(string, CancellationToken)

Detect the sentiment of a (reasonably short) text. Sentiment analysis may cause a translation to be made, since sentiment analysis only supports a limited set of languages

Declaration

Task<Sentiment> DetectSentimentAsync(string text, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	text	Text to be analyzed
CancellationToken	cancellationToken

Returns

Type	Description
Task<Sentiment>	The sentiment information: score (-100 to +100) and confidence

ExpandTextAsync(string, int, string, CancellationToken)

Generate a longer version of a text

Declaration

Task<string> ExpandTextAsync(string text, int percentBigger, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	text	Text to embiggen
int	percentBigger	How much to embiggen.
string	isoLangCode	Language returned text should be in. Blank = do not specify language.
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	Expanded version of the text

GetChatbotPromptSuggestionsAsync(string, string, int, CancellationToken)

Return one or more suggested prompts as actions to display in an empty chat window

Declaration

Task<ChatbotTurn> GetChatbotPromptSuggestionsAsync(string isoLangCode, string soProtocol, int currentId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	isoLangCode	ISO2 Language code ('en', 'no', 'de'...) for suggestions in response
string	soProtocol	Context for suggestions ('contact.main.activities')
int	currentId	current company/person/project id - used for context in suggestions
CancellationToken	cancellationToken

Returns

Type	Description
Task<ChatbotTurn>	Contains zero or more BotActions, and welcome message in Bot response

GetChatbotResponseAsync(string, string, string, string, ChatbotTurn[], string, CancellationToken)

Return a chatbot response given prompt and previous turns. Stores the new turn in the history for the chatId

Declaration

Task<ChatbotTurn> GetChatbotResponseAsync(string chatId, string isoLangCode, string userPrompt, string displayValue, ChatbotTurn[] previousTurns, string apiUrl, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	chatId	identifies this chat = arbitrary name (e.g. user-defined) or the soprotocol + id (e.g. ticket-123, contact-43, diary)
string	isoLangCode	ISO2 Language code ('en', 'no', 'de'...) for suggestions in response
string	userPrompt	User question for chatbot
string	displayValue	User question for display - optional - null = use userPrompt
ChatbotTurn[]	previousTurns	Chat history - all previous turns in chronological order
string	apiUrl	CRM API endpoint URL for chatbot to make callbacks to. 'https://example.com/superoffice/api/'
CancellationToken	cancellationToken

Returns

Type	Description
Task<ChatbotTurn>	Returns new turn that client can append to its local history.

GetChatbotTurnsAsync(string, CancellationToken)

Returns stored history of chat messages for a given chat_id. Chat_id is usually derived from soproto + current id, but could also be arbitrary name.

Declaration

Task<ChatbotTurn[]> GetChatbotTurnsAsync(string chatId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	chatId	identifies this chat = arbitrary name (e.g. user-defined) or the soprotocol + id (e.g. ticket-123, contact-43, diary)
CancellationToken	cancellationToken

Returns

Type	Description
Task<ChatbotTurn[]>	Array containing zero or more turns. If you got zero turns, call GetChatbotPromptSuggestions to get an initial turn from the bot.

GetSummarizeContactPromptAsync(int, int, string, string, CancellationToken)

Return the prompt used to get a short summary of the activities on a contact. Does not call the chatbot for a response. Used for transfering a summary to a chat session.

Declaration

Task<ChatbotTurn> GetSummarizeContactPromptAsync(int contactId, int numSentences, string summary, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	Contact id to summarize
int	numSentences	Length of summary
string	summary	Chatbot's summary of the contact activities
string	isoLangCode	Language returned text should be in. Blank = do not specify language.
CancellationToken	cancellationToken

Returns

Type	Description
Task<ChatbotTurn>	Display text and Prompt used to generate a short summary of the activities on a contact.

GetSummarizeSalePromptAsync(int, int, string, string, CancellationToken)

Return the prompt used to get a short summary of the activities on a sale. Does not call the chatbot for a response. Used for transfering a summary to a chat session.

Declaration

Task<ChatbotTurn> GetSummarizeSalePromptAsync(int saleId, int numSentences, string summary, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	saleId	Sale id to summarize
int	numSentences	Length of summary
string	summary	Chatbot's summary of the sale activities
string	isoLangCode	Language returned text should be in
CancellationToken	cancellationToken

Returns

Type	Description
Task<ChatbotTurn>	Display text and Prompt used to generate a short summary of the activities on a sale.

GetSummarizeTicketPromptAsync(int, int, string, string, CancellationToken)

Return the prompt used to get a short summary of the messages on a ticket. Does not call the chatbot for a response. Used for transfering a summary to a chat session.

Declaration

Task<ChatbotTurn> GetSummarizeTicketPromptAsync(int ticketId, int numSentences, string summary, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	ticketId	Ticket id to summarize
int	numSentences	Length of summary
string	summary	Chatbot's summary of the ticket
string	isoLangCode	Language returned text should be in
CancellationToken	cancellationToken

Returns

Type	Description
Task<ChatbotTurn>	Display text and Prompt used to generate a short summary of the messages on a ticket.

GetTrainingStatusAsync(CancellationToken)

Calling the HugoAI endpoint to fetch the current training status.

Declaration

Task<CategorizationStatusResponse> GetTrainingStatusAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<CategorizationStatusResponse>	Carrier to describe the current status of HugoAI categorization

GuessCategoryAsync(int, CancellationToken)

Given a ticket's id, guess the ticket category it should be placed in. Currently this is based on the first message in the ticket

Declaration

Task<int> GuessCategoryAsync(int ticketId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	ticketId	Id of ticket to guess category for
CancellationToken	cancellationToken

Returns

Type	Description
Task<int>	Suggested ticket category ID

RephraseTextAsync(string, AiTextStyle, string, CancellationToken)

Generate a new version of a text

Declaration

Task<string> RephraseTextAsync(string text, AiTextStyle style, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	text	Text to transform
AiTextStyle	style	New style to transform text into (Rephrase, Correct, Casual, Formal)
string	isoLangCode	Language returned text should be in. Blank = do not specify language.
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	New version of the text

SearchAsync(string, string, RagType, int, CancellationToken)

Returns semantic search results from vector database.

Declaration

Task<RagResult[]> SearchAsync(string namespaceName, string query, RagType type, int top, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	namespaceName	Defines the search domain. e.g. 'ServiceCopilot'.
string	query	Search query.
RagType	type	Filter results based on a specific content type. Default: None = no filtering
int	top	Max Number of results to return.
CancellationToken	cancellationToken

Returns

Type	Description
Task<RagResult[]>	Array containing vector search results

StartRagIndexingAsync(string, string, CancellationToken)

Kicks off a batch task to update the RAG index

Declaration

Task<int> StartRagIndexingAsync(string namespaceName, string sourceId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	namespaceName	Defines the search domain. e.g. 'ServiceCopilot'.
string	sourceId	(Optional) Identifies the data source to update. Blank = all sources
CancellationToken	cancellationToken

Returns

Type	Description
Task<int>	The batch task id

SummarizeContactAsync(int, int, string, CancellationToken)

Generate a short summary of the activities on a contact

Declaration

Task<string> SummarizeContactAsync(int contactId, int numSentences, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	Contact id to summarize
int	numSentences	Length of summary
string	isoLangCode	Language returned text should be in. Blank = do not specify language.
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	Short summary of the activities on a contact - in HTML.

SummarizeSaleAsync(int, int, string, CancellationToken)

Generate a short summary of the activities on a sale

Declaration

Task<string> SummarizeSaleAsync(int saleId, int numSentences, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	saleId	Sale id to summarize
int	numSentences	Length of summary
string	isoLangCode	Language returned text should be in. Blank = do not specify language.
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	Short summary of the activities on a sale - in HTML.

SummarizeTextAsync(string, int, string, CancellationToken)

Generate a short summary of a text

Declaration

Task<string> SummarizeTextAsync(string text, int percentSmaller, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	text	Text to summarize
int	percentSmaller	How much to shorten.
string	isoLangCode	Language returned text should be in. Blank = do not specify language.
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	Short summary of the text

SummarizeTicketAsync(int, int, string, CancellationToken)

Generate a short summary of the messages on a ticket

Declaration

Task<string> SummarizeTicketAsync(int ticketId, int numSentences, string isoLangCode, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	ticketId	Ticket id to summarize
int	numSentences	Length of summary
string	isoLangCode	Language returned text should be in
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	Short summary of the messages on a ticket - in HTML.

TrainCategoryGuesserAsync(int, int, int, CancellationToken)

The category guesser training API will be called with an array of CategorizationTrainingItem during the (background, Batch) execution of this call

Declaration

Task<string> TrainCategoryGuesserAsync(int selectionId, int maxItems, int maxTextLength, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	selectionId	Id of selection of tickets, to retrieve training data from
int	maxItems	Maximum number of tickets to retrieve data from
int	maxTextLength	Maximum length of PlainTextBody or any other large text, truncated to nearest word boundary
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	Placeholder for result... should this be a BatchTaskId? maybe not useful?

TranslateAsync(string, string, CancellationToken)

Translate a text from one language to another. Language of the text is automatically detected.

Declaration

Task<string> TranslateAsync(string text, string targetLanguage, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	text	Text to be translated. Language of the text is automatically detected.
string	targetLanguage	ISO Language code (such as FR) to translate the text into
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	Translated text

TranslateEntityAsync(string, int, string, CancellationToken)

Retrieve, format and translate text for an entity to a specified language

Declaration

Task<string> TranslateEntityAsync(string entityName, int entityId, string targetLanguage, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	entityName	Name of entity to get the text to be translated; eg., 'ticketMessage'
int	entityId	Identifier for the entity to get text to be translated
string	targetLanguage	ISO Language code (such as FR) to translate the text into
CancellationToken	cancellationToken

Returns

Type	Description
Task<string>	Translated text