Version: 10.0

Handle system-level data using Creatio.ai

Level: advanced

Creatio.ai is natively embedded AI functionality in the core of the Creatio Freedom UI platform, designed to empower organizations with intelligent automation by acting as a virtual agent assistant to the end user performing tasks. Creatio.ai's unified AI approach brings together prescriptive, generative, and agentic AI to deliver a comprehensive solution for modern business automation.

In Creatio.ai, an AI Sub-agent represents a comprehensive, end-to-end AI-enabled task that can be executed for a user. It serves as the way for Creatio.ai to acquire new AI capabilities. AI Sub-agent empower users to achieve complex tasks without the need to execute each step manually. They provide a structured and efficient approach to task completion, enhancing the overall user experience.

The AI Sub-agent's mode, specified by the Where to use property, determines how it is used. The options for using AI Sub-agents are as follows:

Interactive Creatio.ai conversations, i.e., the Where to use property is set to "Prompt agents".
Directly on the system level, i.e., the Where to use property is set to "Workflows".

This article covers how to configure and use workflow AI Sub-agents. Learn more about configuring prompt AI Sub-agents: Develop Creatio.ai Skill (user documentation).

1. Develop workflow AI Sub-agent

Click in the top right → System setup → Creatio.ai sub-agents.
Add an AI Sub-agent. To do this, click New.

Fill out the properties of the AI Sub-agent.

Property	Property description
Title*	AI Sub-agent title.
Code*	Code of the AI Sub-agent required for custom development. The property is populated automatically.
Description*	Description of the AI Sub-agent. Creatio.ai uses it to determine which AI Sub-agent to run upon user's requests.
Status*	Whether the AI Sub-agent is active. Select "Active" to use it.
Where to use*	Mode of the AI Sub-agent. Select "Workflows".
Model	Whether to use a specific large language model (LLM). Learn more: Creatio.ai models (user documentation). Leave the field empty to use GPT-4.1.

Specify the user's goal when using the AI Sub-agent.

Property	Property description
Prompt	Initial instruction for the LLM that clearly defines the task the user wants to accomplish. For workflow AI Sub-agents, LLM uses AI Sub-agent parameters if they are specified in the Input parameters and Output parameters blocks and available to use.

Property

Property description

Prompt

Initial instruction for the LLM that clearly defines the task the user wants to accomplish.

For workflow AI Sub-agents, LLM uses AI Sub-agent parameters if they are specified in the Input parameters and Output parameters blocks and available to use.

Learn more about creating the most efficient prompts: AI Skill development recommendations (user documentation).

Specify input parameters that are used by AI Sub-agent and handled by the LLM.

Go to the Input parameters block based on your business goals.
Click New.

Fill out the parameter properties.

Property	Property description
Code*	Code of the parameter required for custom development.
Name*	Parameter title. Creatio.ai uses it to determine which parameter to use. Create a title that helps users to understand parameter purpose.
Description*	Brief parameter description. Create a description that helps users to understand what data the parameter includes.
Data type*	Type of parameter data. Available values: "Boolean," "Currency (0.01)," "Date," "Date/Time," "Decimal (0.01)," "Integer," "Serializable list of composite values," "Text (500 characters)," "Time," "Unique identifier," "Unlimited length text." By default, "Unlimited length text."

Use recommendations for input parameters:

The names of input parameters are case-sensitive.
The names of input parameters start with a letter and can contain Latin letters, digits, underscores and dots.
The names and codes of input parameters must be descriptive. Avoid generic values such as "Type" or "Name." Instead, use specific names and codes that reflect the business meaning of the parameter, for example, "Product name" or "Account type" as the parameter name and ProductName or AccountType as the parameter code.
Creatio.ai uses an empty string instead of the input parameter name if the value of the input parameter is neither defined by the user nor received from the instance.

The following example demonstrates how Creatio.ai works with input parameters in the table below.

User-defined value of the Prompt property	Your task is to display the following information: `inputText`
The user-defined value of the input parameter specified in the Prompt property	Greetings, user!
The resulting value of the Prompt property after Creatio.ai handled data	Your task is to display the following information: Greetings, user!

Specify output parameters that are used by AI Sub-agent and handled by the LLM.

Go to the Output parameters block based on your business goals.

Select the way to specify output parameters.

Specify output parameters manually

Use this way when you need to:

configure a small number of output parameters
map output values in a Freedom UI page schema or business process
specify output parameters one by one using the UI

To specify output parameters manually:

Click New.
Fill out the parameter properties.

Property	Property description
Code*	Code of the parameter required for custom development.
Name*	Parameter title. Creatio.ai uses it to determine which parameter to use. Create a title that helps users to understand parameter purpose.
Description*	Brief parameter description. Create a description that helps users to understand what data the parameter includes.
Data type*	Type of parameter data. Available values: "Boolean," "Currency (0.01)," "Date," "Date/Time," "Decimal (0.01)," "Integer," "Text (500 characters)," "Time," "Unique identifier," "Unlimited length text." By default, "Unlimited length text."

Use recommendations for output parameters: the names and codes of output parameters must be descriptive. Avoid generic values such as "Type" or "Name." Instead, use specific names and codes that reflect the business meaning of the parameter, for example, "Product name" or "Account type" as the parameter name and ProductName or AccountType as the parameter code.

Specify output parameters automatically

Use this way when you need to:

return structured JSON output with a predefined response format
ensure consistent output for further processing
return nested objects, arrays, or other complex data structures
implement business logic to handle the AI Sub-agent output in a business process

To specify output parameters automatically:

Click Switch to JSON structure to switch the output parameter setup mode to automatic. This displays the JSON schema block instead of the Output parameters block.
Insert JSON schema for the AI Sub-agent. Creatio stores the JSON schema as a file in the file structure.

To add output parameters manually as before, click Switch to Output Parameters.

Creatio.ai lets you use Error message, Response text, Status, Warning message output parameters out of the box when implementing the business logic of data handling in both the Freedom UI page schema and business process so you no longer need to add them manually. The parameter values match the property values of the Creatio.Copilot.CopilotIntentCallResult class in the back-end and the CopilotIntentCallResult interface in the front-end. View a detailed comparison in the table below.

Output parameter	Property
Output parameter	Front-end	Back-end
Error message	errorMessage	ErrorMessage
Response text	content	Content
Status	status	Status
Warning message	warnings	Warnings

Learn more: creatio.ai API.

Save the changes.

As a result, Creatio will add the AI Sub-agent to the Creatio.ai sub-agents section and you can use it while implementing the business logic of handling system-level data using Creatio.ai.

2. Set up the data handling using Creatio.ai

Using the "Workflows" mode of Creatio.ai, you can extend out-of-the-box Creatio.ai functionality and handle system-level data depending on your business goals. Clicking a button on a Freedom UI page triggers Creatio.ai to handle data in the Freedom UI page schema or business process, depending on the implemented business logic.

Handle data using Creatio.ai (Freedom UI page schema)

Implement the business logic of data handling using Creatio.ai in the Freedom UI page schema.

Detailed example: Handle system-level data using Creatio.ai in the Freedom UI page schema.

To implement the business logic of data handling using Creatio.ai in the Freedom UI page schema:

Add a button that calls the AI Sub-agent if you need. Instructions: Set up Button components (user documentation).
Add the dependencies if you need to implement the custom request handler. Instructions: Display the value of a system variable (similarly to step 2). Instead of the SysValuesService service, use the HttpClientService service that sends HTTP requests.
Set up how to handle the action executed on button click. Instructions: Optimize the execution of a custom business logic (step 4).

Implement the custom request handler (optional).

For example, implement the custom usr.SomeCustomRequest request handler. To do this:

Go to the handlers schema section.
Retrieve the instance of the HTTP client from @creatio-devkit/common.
Send the crt.CopilotExecuteIntentRequest base request that runs the AI Sub-agent.
Specify code of the AI Sub-agent.
Specify input parameters of the AI Sub-agent.
If Creatio can run the AI Sub-agent, AI Sub-agent fulfills its task. Otherwise, handle an error if it occurs during the AI Sub-agent execution.
Call the next handler if it exists and return its result.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* Implement the custom request handler. */
        handler: async (request, next) => {
            const context = request.$context;

            /* Retrieve the instance of the HTTP client from "@creatio-devkit/common." */
            const handlerChain = sdk.HandlerChainService.instance;

            /* Send the base request that runs the AI Sub-agent. */
            const copilotCallResult = await handlerChain.process({
                type: 'crt.CopilotExecuteIntentRequest',

                /* Code of the AI Sub-agent to run. */
                intentName: 'CodeOfSomeAISkill',

                /* Parameters of the AI Sub-agent. */
                parameters: {
                    somepromptparameter1: 'some parameter value',
                    somepromptparameter2: 'some parameter value'
                },
                $context: request.$context,
                scopes: [...request.scopes]
            });

            /* If Creatio can run the AI Sub-agent, AI Sub-agent
            fulfills its task. */
            if (copilotCallResult.isSuccess) {
                /* Implement custom business logic that handles the
                "copilotCallResult.content". */
                ...

            } else {
            
                /* Implement custom business logic that handles an error and
                "copilotCallResult.errorMessage". */
                ...

            }

            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

As a result, when you click the button on the Freedom UI page, Creatio.ai will handle data based on business logic of the Freedom UI page.

Handle data using Creatio.ai (business process)

Detailed example: Handle system-level data using Creatio.ai in the business process.

To implement the business logic of data handling using Creatio.ai in a business process:

Set up a Read data element that reads Creatio data to handle using Creatio.ai. Instructions: Read data process element (user documentation).
Implement the business logic that runs the AI Sub-agent. To do this, set up a Sub-agent element. Learn more: Call Creatio.ai process element (user documentation).
1. Go to the element setup area.
2. Set Which sub-agent to call? property to code of the AI Sub-agent to run.
3. Specify values of AI Sub-agent input parameters.
If you configured output parameters automatically using a JSON schema on the AI Sub-agent page, parse the structured JSON output using a Script task element. Learn more: Script task process element (user documentation). You can parse structured JSON output in a business process using low-code tools only.
If you need, add a button that calls the business process. Instructions: Button (user documentation).

As a result, when you click the button on the Freedom UI page, Creatio.ai will call the business process, which, in turn, will handle data based on business logic of the Sub-agent element.

1. Develop workflow AI Sub-agent​

2. Set up the data handling using Creatio.ai​

Handle data using Creatio.ai (Freedom UI page schema)​

Handle data using Creatio.ai (business process)​

See also​

1. Develop workflow AI Sub-agent

2. Set up the data handling using Creatio.ai

Handle data using Creatio.ai (Freedom UI page schema)

Handle data using Creatio.ai (business process)

See also