Tool Activation
The Tool Activation section is used to select which tools can be used by this Process Copilot to perform its intended task. This section includes a list of questions that you can answer about what you need the Process Copilot to be able to do. You can expand each question for more details and to see which tools are recommended for helping with the selected question. For more information on the individual tools available and how to configure them in YAML, refer to Configure tools using YAML.
Warning
Only select the tools that are required for your use case.
Note
Our recommendations:
If you are looking for fast access to data that exists in your Knowledge Model and want your answers shown in a table or chart, we recommend activating only items (2) and (5);
If you are looking for ad hoc calculations on top of your data or are looking to build a Process Copilot that performs a very specific task, we recommend activating only item (1);
We do not recommend activating items (1) and (2) together unless you are an expert user and are familiar with how to instruct a Process Copilot on when to use which tool.
Configure tools using the UI
Click the Tool Activation section to expand it.
From the list of questions, click to expand any option that is relevant to your Process Copilot’s intended function. Expanding shows examples of the types of questions that can be answered and any relevant tools that will help with the Process Copilot’s purpose.
Use the checkboxes to select any tools you want to include with your Process Copilot.
Note
Selecting too many tools can lead to your Process Copilot being less accurate with its responses.
Click the blue Save Changes button at the bottom once all tools have been selected.
Once your tools have been selected, you can now define the intended task of this Process Copilot in the System Prompt section.
Configure tools using YAML
Tools are functions that Process Copilot can call to complete a task. Each tool has its own tool arguments and those arguments will differ between tools.
For most tools, you can instantiate (aka activate) them in your Process Copilot configuration without any arguments. When you do this, the arguments are filled out by the LLM based on what the user asked and the context from the system prompt.
Sometimes, you might want to "fix" the tool behavior.
For example, you might have the requirement from your customer to always display a fixed table with fixed columns and specific sorting when users ask for an "overview of invoices". In this example, you would create a customized instance of the display_table tool where you "fix" this behavior using arguments.
Warning
An alternative solution - but not recommended for this example - is to have an instance of the display_table function without arguments. In this case, you rely on the LLM to determine which columns to use. Writing guidance in the system prompt about which columns to use and what sorting behavior to apply is less reliable and efficient than instantiating a customized display_table tool.
Within your Process Copilot configuration, you can instantiate one tool multiple times with different configurations. For example, you can have a display_table tool with no arguments that is used for most questions and a second customized instance display_table_for_invoice_details that is used when users ask for invoice details. You can educate the LLM about when to use each instance by filling out the description argument in the customized instance of your tool.
There is an exception for the pql_tool and trigger_action_flow tools. These two tools always require a manual configuration of arguments.
Arguments
When you customize a tool by providing arguments, you don’t need to specify all of them. The unspecified arguments will be filled out by the LLM as usual. For example, with a display_table tool you can specify the columns but leave the caption, limit, order by and sorting order up to the LLM.
Customization by tool
Note
Customization of tools is currently only available using YAML.
Arguments that can be set on any tool
All tools can be given:
description: Instructions to the LLM for when to use this tool.unique_id: Mandatory when you instantiate the same tool multiple times.active: true/false. If set to "false", your Process Copilot cannot use this tool.
Search data and disambiguate
Should not be customized.
Display table
This tool is needed when you want to display a table component (such as the one from Views) in answers.
Unique arguments for this tool are:
caption (str): The text shown above the table.column_ids (list[str]): The list of KPIs and record attribute ids of the table.limit (int | None): The number of rows to display.order_by (str | None): The column id to order the table by.ascending (bool | None): Sort the data in ascending or descending order.
Example
- id: display_table description: Use this when users ask for the no touch rate per vendor. unique_id: vendor_no_touch_rate_table caption: The No Touch Rate per vendor. column_ids: - INVOICE.IDENTIFIER_AS_ATTRIBUTE - KPI_NO_TOUCH_RATE order_by: KPI_NO_TOUCH_RATE ascending: true
Display chart
This tool is needed when you want to display a chart component.
Unique arguments for this tool are:
caption (str): The text shown above the chart.x_axis_id (str): The record attribute id used on the x axis.y_axis_id (list[str]): The list of record attribute or KPI ids used on the y axis. Use at most two values.chart_type (list[str]): Eitherbarorlinefor everyy_axis_identry.
Example
- id: display_chart x_axis_id: INVOICE.YEAR y_axis_id: - KPI_NO_TOUCH_RATE chart_type: - line
Display KPI
This tool is needed when you want to display a KPI list component.
Unique arguments for this tool are:
caption (str): The text shown above the KPI.kpi_ids (list[str]): The list of KPI ids to display.
Example
- id: display_kpi kpi_ids: - KPI_NO_TOUCH_RATE
Get insights
This tool is needed when you want to answer a question like "How can I improve DPO?" and want to see Celonis-generated Insights.
Warning
Insights come from the Celonis recommendation engine and are the same insights that are generated in the Insight Explorer asset. For details about how these insights are generated, please refer to the Insight Explorer documentation.
Unique arguments for this tool are:
kpi (str): The KPI id for which you want to find insights.field_ids (list[str]): List of record attribute ids related to the KPI.
Example
- id: get_insights kpi: KPI_DPO field_ids: - O_CUSTOM_INVOICE.VENDOR - O_CUSTOM_INVOICE.DOCUMENT_TYPE
Get data
This tool is used when you have a use case that requires you to load data for the LLM to "see" prior to performing further analysis/tasks, such as by calling the Python tool to perform an ad-hoc calculation on the data it "got".
Note
This tool can retrieve a maximum of 500k rows of data from the data model.
Unique arguments for this tool are:
columns (list[str]): The list of KPIs and record attribute ids the tool loads.
Example
- id: get_data columns: - MATERIAL_REPLENISHMENT_DATA.PLANT_NAME - MATERIAL_REPLENISHMENT_DATA.MATERIAL_NAME - MATERIAL_REPLENISHMENT_DATA.AMOUNT_IN_STOCK
Python
This tool is needed when you want your Process Copilot to do ad-hoc calculations in addition to what you have available in the Knowledge Model. This tool usually works together with the get_data tool since the LLM needs to "see" (get) the data first, then perform calculations.
Unique arguments for this tool are:
code (str):The Python code to execute.require_get_data (bool):True if the data must be loaded before running this tool.
Example
- id: python
unique_id: square_otp_rate
code: |
otp_rate = df['KPI_VendorInvoiceItem_AVG_OnTimePaymentRate'].iloc[0]
otp_rate_squared = otp_rate ** 2 print(f'The OTP rate is {otp_rate:.2%} and its square is {otp_rate_squared:.4%}')
Trigger Action Flows
Note
Must be customized.
This tool allows you to connect your Process Copilot to an existing Action Flow and instruct your Process Copilot on when to surface this action to users.
Unique arguments for this tool are:
description (str): The description of the Action Flow and what it does. This description is passed to the LLM to decide if it calls the Action Flow. You can also pass instructions here, but should keep those instructions short and precise.Flow_hook_id (str): hook id of the URL provided in the Action Flow.flow_node_id (str): Node_id of the Action Flow asset.Flow_input_schema: The input schema of the Action Flow as configured in the first part. This configuration must match the webhook configuration, otherwise the Action Flow will not be executed correctly. The specification follows the OpenAI spec.Flow_display_name (str): A display name that is shown to the user to confirm executing the Action Flow.
Example
- id: trigger_action_flow unique_id: send_email description: Sends an email to a recipient given an email address and email body. flow_hook_id: 5rdzshdul653ogktg541mu0hhki13mrn flow_node_id: 5633193a-6dd0-48da-8db2-9ef2df221b9e flow_display_name: Sends email to user flow_input_schema: type: object required: - email - body properties: body: type: string description: The body of the email to send. email: type: string description: Email address to send an email to.
PQL tool
Note
Must be customized.
This tool is helpful for questions such as "Give me the current status of Invoice A" or "What’s going on with my Trade AB" where you want Process Copilot to pull in a large amount information (e.g., 20 columns) for one particular case to summarize it or to perform additional tasks on this information.
Something similar can be achieved with a combination of get_data and python, but we found that the orchestration of these tools and how they interact is a bit complex and the source of many model errors.
Example
- id: pql_tool
columns:
- id: INVOICES.INVOICE_NUMBER <- can specify IDs from KM
- pql_template: <- or write custom PQL
pql: '"invoices"."Invoice Value"'
name: invoice value
filters:
- pql_template: <- PQL can have ${} variable place holders
pql: FILTER "invoices"."Invoice Number" in ('${invoice_number}')
name: Invoice Number Filter
unique_id: get_invoice_by_id
description: Get invoice information for a specific invoice number
input_schema:
properties:
invoice_number: <- the variable placeholder becomes an LLM argument
description: the invoice number you want to filter by.In this above configuration we make a new tool with an argument for invoice_number that retrieves a table with invoice number and invoice value filtered to a specific invoice number that is inserted by the LLM. When using this tool, the LLM simply runs get_invoice_by_id(‘INV-1001’) and retrieves the content.
The output of this tool is written into a data frame which can be used by python further or can be simply used by the LLM to provide a summary for the users.