Creatio.ai API

Level: advanced

CopilotEngine class

The Creatio.Copilot.CopilotEngine class implements the ICopilotEngine interface and is required to manage and execute AI Sub-agents within Creatio. The class lets you interact with Creatio.ai, ensuring GDPR and HIPAA compliance. The class provides Creatio powerful AI tools to streamline your workflow, enhance decision-making, achieve results and support users with their daily operations. The class located in the CrtCopilot package.

To interact with the class, call UserConnection.CopilotEngine.

To interact with the class interface, call UserConnection.ICopilotEngine.

Methods

ExecuteIntent()

Executes an AI Sub-agent synchronously.

ExecuteIntentAsync()

Executes an AI Sub-agent asynchronously.

GetAvailableIntents()

Retrieves available AI Sub-agents based on the operating mode.

CopilotIntentCall class

The Creatio.Copilot.CopilotIntentCall class is used to encapsulate the data required to call a specific AI Sub-agent using Creatio.ai API. Use a class to let Creatio.ai to execute pre-configured actions with results that depend on user-defined parameters.

View the template of CopilotIntentCall class usage below.

Template of CopilotIntentCall class usage

/* Create a "CopilotIntentCall" instance. */
var request = new CopilotIntentCall {

    /* Code of the AI Sub-agent to run. */
    IntentName = "UsrCodeOfSomeAISubAgent",

    /* Parameters of the AI Sub-agent. */
    Parameters = new Dictionary<string, object> {
        { "somepromptparameter1", "some parameter value" },
        { "somepromptparameter2", "some parameter value" }
    }
};

Properties

IntentName string

Code of the AI Sub-agent to run.

Parameters IDictionary<string, object>

Input parameters that are specified in the Prompt property of the AI Sub-agent. Creatio only supports string parameter type.

CopilotIntentCallResult class

The Creatio.Copilot.CopilotIntentCallResult class provides the result of an AI Sub-agent execution using Creatio.ai API. Creatio.ai API changes the status of the AI Sub-agent execution depending on the received exception, instead of creating an exception.

Properties

Status IntentCallStatus

Status of the Creatio.ai execution. Defined by the Creatio.Copilot.IntentCallStatus enumeration value. Most values of the Status property are localizable, except the FailedToExecute value that initiates an exception message in the ErrorMessage property.

Available values (Creatio.Copilot.IntentCallStatus)

ExecutedSuccessfully	The AI Sub-agent is executed successfully.
CantGenerateGoodResponse	The AI Sub-agent execution failed because Creatio.ai is unable to generate a result that can be displayed to the user.
FailedToExecute	The AI Sub-agent execution failed.
InsufficientPermissions	The AI Sub-agent execution failed due to insufficient user permissions.
ResponseParsingFailed	The AI Sub-agent execution failed due to inability to parse AI Sub-agent output parameters.
IntentNotFound	The AI Sub-agent execution failed because AI Sub-agent was not found.
InactiveIntent	The AI Sub-agent execution failed because Status property of the AI Sub-agent includes "Deactivated" or "In development" value.
WrongIntentMode	The AI Sub-agent execution failed because Where to use property of the AI Sub-agent includes incorrect value.

Content string

Content generated by Creatio.ai.

ErrorMessage string

Error message of the Creatio.ai execution. Returns the text of error message if error occurs during the AI Sub-agent execution, i.e., the Status property contains a value different from ExecutedSuccessfully. Otherwise, null.

Warnings IList<string>

A warning list of the Creatio.ai execution. Returns a list of warnings if the input parameters of the AI Sub-agent are empty, they have incorrect format or there are additional input parameters that are not part of the AI Sub-agent. Many warnings are separated by user-defined characters. For example, commas, semicolons. Otherwise, null.

IsSuccess bool

Indicates whether the AI Sub-agent was executed successfully.

CopilotIntentStatus enum

The Creatio.Copilot.CopilotIntentStatus enumeration provides a list of AI Sub-agent statuses. Creatio displays the status in the Status property on the AI Sub-agent page.

Active	An active AI Sub-agent, triggered for all users.
InDevelopment	An AI Sub-agent in development. Triggered only for users that have access to the "CanDevelopCopilotIntents" (CanDevelopCopilotIntents code) system operation.
Deactivated	A deactivated AI Sub-agent. Not triggered.

crt.CopilotGetAvailableIntentsRequest request handler

The crt.CopilotGetAvailableIntentsRequest request handler is used to check the accessibility of the AI Sub-agent.

Properties

intentNames: string[]

An array of AI Sub-agent codes to be retrieved. Required.

mode?: RunCopilotIntentMode

Operating mode of the AI Sub-agent. By default, "API."

Available values (RunCopilotIntentMode)

API	Creatio can use the AI Sub-agent on a system level.
Chat	Creatio can use the AI Sub-agent in interactive Creatio.ai conversations.

CopilotGetAvailableIntentsCallResult interface

The CopilotGetAvailableIntentsCallResult interface provides a list of AI Sub-agent codes that are available for use and were passed in the request.

Properties

availableIntentNames: string[]

An array of AI Sub-agent codes that were passed in the request. Required. If you omit the value, Creatio returns a full list of available AI Sub-agent codes.

crt.CopilotExecuteIntentRequest request handler

The crt.CopilotExecuteIntentRequest request handler is used to run a specific AI Sub-agent using Creatio.ai.

Properties

intentNames: string

The code of the AI Sub-agent to run. Required.

parameters?: JsonData

Configuration object of AI Sub-agent parameter values to be used when Creatio executes AI Sub-agent.

Creatio imports the JsonData type from the @creatio-devkit/common library. The JsonData type defines a JSON data structure and contains a "key-value" collection, where "key" is the case-sensitive name of the AI Sub-agent parameter and "value" is the value of the AI Sub-agent parameter.

Example of the key-value collection

parameters: {
    someParameter1: 'Some parameter value',
    someParameter2: 'Some parameter value'
}

Creatio converts this collection into the following array.

key-value converted collection

"parameters": [
    {"Key": "someParameter1", "Value": "Some parameter value"},
    {"Key": "someParameter2", "Value": "Some parameter value"}
]

To avoid server errors during conversion, make sure that the empty parameter value is specified as null or '' instead of undefined.

CopilotIntentCallResult interface

The CopilotIntentCallResult interface provides the result of an AI Sub-agent execution using Creatio.ai API.

Properties

content: string

Content generated by Creatio.ai.

status: IntentCallStatus

Status of the Creatio.ai execution. Defined by the Creatio.Copilot.IntentCallStatus enumeration value. Most values of the Status property are localizable, except the FailedToExecute value that initiates an exception message in the errorMessage property.

Available values (Creatio.Copilot.IntentCallStatus)

ExecutedSuccessfully	The AI Sub-agent is executed successfully.
CantGenerateGoodResponse	The AI Sub-agent execution failed because Creatio.ai is unable to generate a result that can be displayed to the user.
FailedToExecute	The AI Sub-agent execution failed.
InsufficientPermissions	The AI Sub-agent execution failed due to insufficient user permissions.
ResponseParsingFailed	The AI Sub-agent execution failed due to inability to parse AI Sub-agent output parameters.
IntentNotFound	The AI Sub-agent execution failed because AI Sub-agent was not found.
InactiveIntent	The AI Sub-agent execution failed because Status property of the AI Sub-agent includes "Deactivated" or "In development" value.
WrongIntentMode	The AI Sub-agent execution failed because Where to use property of the AI Sub-agent includes incorrect value.

errorMessage?: string

Error message of the Creatio.ai execution. Returns the text of error message if error occurs during the AI Sub-agent execution, i.e., the status property contains a value different from ExecutedSuccessfully. Otherwise, null.

warnings?: string[]

An array of warnings that occur during the AI Sub-agent execution. Returns a list of warnings if the input parameters of the AI Sub-agent are empty, they have incorrect format or there are additional input parameters that are not part of the AI Sub-agent. Many warnings are separated by user-defined characters. For example, commas, semicolons. Otherwise, null.

IsSuccess: boolean

Indicates whether the AI Sub-agent was executed successfully.