Interface IAIAgent

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

Experimental: The AI agent is experimental, subject to change, and not intended for partners.

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

AnalyzeBizCardImageAsync(Stream, bool, CancellationToken)

Returns contact and person information from an image. Merges results with matching database records if merge = true

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<BizCard> AnalyzeBizCardImageAsync(Stream image, bool mergeWithDatabase, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Stream	image	Image data containg a business card
bool	mergeWithDatabase	Merge results from analysis with matching database records? True: match company/person names and set ids on returned entities.
CancellationToken	cancellationToken

Returns

Type	Description
Task<BizCard>	Returns a Contact and a Person entity.

AnalyzeBizCardTextAsync(string, bool, CancellationToken)

Extract contact and person information from text. Merge results with matching database records if merge = true

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<BizCard> AnalyzeBizCardTextAsync(string text, bool mergeWithDatabase, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	text	Text that contains useful contact and person information.
bool	mergeWithDatabase	Merge results from analysis with matching database records? True: match company/person names and set ids on returned entities.
CancellationToken	cancellationToken

Returns

Type	Description
Task<BizCard>	Returns a Contact and a Person entity.

AnswerAcceptedAsync(string, CancellationToken)

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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.

Experimental: The operation is experimental, subject to change, and not intended for partners.

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.

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

CreateDefaultCopilotDataSourceEntityAsync(CancellationToken)

Loading default values into a new CopilotDataSourceEntity.

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<CopilotDataSourceEntity> CreateDefaultCopilotDataSourceEntityAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<CopilotDataSourceEntity>	New CopilotDataSourceEntity with default values

CreateDefaultCopilotEntityAsync(CancellationToken)

Loading default values into a new CopilotEntity.

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<CopilotEntity> CreateDefaultCopilotEntityAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<CopilotEntity>	New CopilotEntity with default values

CreateTextForAppointmentAsync(AppointmentEntity, string, CancellationToken)

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

DeleteCopilotDataSourceEntityAsync(int, CancellationToken)

Deletes the CopilotDataSourceEntity

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task DeleteCopilotDataSourceEntityAsync(int copilotDataSourceEntityId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	copilotDataSourceEntityId	The identity of the CopilotDataSourceEntity
CancellationToken	cancellationToken

Returns

Type	Description
Task	This method has no return value

DeleteCopilotEntityAsync(int, CancellationToken)

Deletes the CopilotEntity

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task DeleteCopilotEntityAsync(int copilotEntityId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	copilotEntityId	The identity of the CopilotEntity
CancellationToken	cancellationToken

Returns

Type	Description
Task	This method has no return value

DetectLanguageAsync(string, CancellationToken)

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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.

Experimental: The operation is experimental, subject to change, and not intended for partners.

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.

GetCopilotDataSourceEntityAsync(int, CancellationToken)

Gets a CopilotDataSourceEntity object.

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<CopilotDataSourceEntity> GetCopilotDataSourceEntityAsync(int copilotDataSourceEntityId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	copilotDataSourceEntityId	The identifier of the CopilotDataSourceEntity object
CancellationToken	cancellationToken

Returns

Type	Description
Task<CopilotDataSourceEntity>	A single CopilotDataSourceEntity

GetCopilotEntityAsync(int, CancellationToken)

Gets a CopilotEntity object.

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<CopilotEntity> GetCopilotEntityAsync(int copilotEntityId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	copilotEntityId	The identifier of the CopilotEntity object
CancellationToken	cancellationToken

Returns

Type	Description
Task<CopilotEntity>	A single CopilotEntity

GetFormDesignFromImageAsync(Stream, CancellationToken)

Returns Form Designer properties based on the look of a picture

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<StringDictionary> GetFormDesignFromImageAsync(Stream image, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Stream	image	Image data to analyze for design
CancellationToken	cancellationToken

Returns

Type	Description
Task<StringDictionary>	Returns a Form Designer properties.

GetFormDesignFromUrlAsync(string, CancellationToken)

Returns Form Designer properties based on the look of a web page

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<StringDictionary> GetFormDesignFromUrlAsync(string url, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	url	Url of the web page to extract style from.
CancellationToken	cancellationToken

Returns

Type	Description
Task<StringDictionary>	Returns a Form Designer properties.

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.

Experimental: The operation is experimental, subject to change, and not intended for partners.

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.

Experimental: The operation is experimental, subject to change, and not intended for partners.

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.

Experimental: The operation is experimental, subject to change, and not intended for partners.

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.

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

SaveCopilotDataSourceEntityAsync(CopilotDataSourceEntity, CancellationToken)

Updates the existing CopilotDataSourceEntity or creates a new CopilotDataSourceEntity if the id parameter is 0.

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<CopilotDataSourceEntity> SaveCopilotDataSourceEntityAsync(CopilotDataSourceEntity copilotDataSourceEntity, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CopilotDataSourceEntity	copilotDataSourceEntity	The CopilotDataSourceEntity that is saved
CancellationToken	cancellationToken

Returns

Type	Description
Task<CopilotDataSourceEntity>	New or updated CopilotDataSourceEntity

SaveCopilotEntityAsync(CopilotEntity, CancellationToken)

Updates the existing CopilotEntity or creates a new CopilotEntity if the id parameter is 0.

Experimental: The operation is experimental, subject to change, and not intended for partners.

Declaration

Task<CopilotEntity> SaveCopilotEntityAsync(CopilotEntity copilotEntity, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CopilotEntity	copilotEntity	The CopilotEntity that is saved
CancellationToken	cancellationToken

Returns

Type	Description
Task<CopilotEntity>	New or updated CopilotEntity

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

Returns semantic search results from vector database.

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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.

Experimental: The operation is experimental, subject to change, and not intended for partners.

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

Experimental: The operation is experimental, subject to change, and not intended for partners.

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