Execute Generative AI Skill Smart Service

Overview

The Execute Generative AI Skill smart service lets you integrate your AI skill into your process. This smart service takes input and appends it to the prompt you created in the relevant AI skill. Then, the smart service sends the compiled prompt to a generative AI model, which returns an output. The smart service can be run in two different execution modes.

The smart service takes a document, email, or text as input. Review the list of generative AI skills you can use with this smart service.

Permissions

The user who executes the process model doesn't need to have access to the AI skill being called by the Execute Generative AI Skill smart service. However, without those permissions, some smart service configuration options are masked.

Properties

• Category: AI_Skills
• Icon:

• Assignment Options: Unattended

• Compatible with autoscale: Yes

Configuration options

Setup tab

The Setup tab allows you to select an AI skill and the execution mode.

• Select AI Skill: Search or browse for an AI skill to use with this smart service.

• Execution Mode: The execution mode determines how this smart service runs in a process. Review the descriptions below to choose the mode that best fits your use case. See the Execution modes topic for more details.

  Execution Mode	Description
  Standard	Best for most use cases, especially jobs that complete quickly while the user is waiting for results. Supports activity chaining. Timeout: 4.5 minutes (1.5 minutes in autoscaled processes)
  Long Running	Best for use cases with complex reasoning, large outputs, or high-volumes. Does not support activity chaining. Timeout: 60 minutes

Data tab

Node inputs

Inputs change based on the AI skill you use with this smart service.

Document inputs

Email inputs

Text inputs

Ensure your input format matches the format specified in the prompt. For example, if the prompt includes instructions for the AI to format a list or map into JSON, ensure the input is in list or map format.

Spreadsheet inputs

Model inputs

Usage inputs

Node outputs

The smart service returns the model's response as text. If the model encounters an error, details are returned in the Error Message output.

Usage considerations

Activity chaining is supported.

Attribute AI usage to groups

You can attribute AI usage from this smart service to specific Appian groups for internal chargeback and cost allocation. Configure the Usage Groups input on the Data tab to associate one or more groups with the execution. The Usage Groups input accepts a List of Group and is configured on the smart service node, not the AI skill itself. This means different process models, or different branches within the same process, can call the same AI skill and attribute those calls to different groups depending on the business context.

If the Usage Groups input is left empty, the execution is logged as unattributed. You can assign up to 100 groups per execution. The execution continues with only the valid groups. Null, duplicate, or invalid groups are ignored.

Context limits

Each AI model has a context window that limits how much content it can analyze in a single call. The effective limit is determined by both the model's context window and Appian's document input requirements. Even if a document meets the size requirements, it can still exceed the model's limit if the content is particularly dense or complex. If the combined prompt and input exceed the model's capacity, you may encounter an error.

If any of these guardrails are limiting, please reach out to your Appian contact.

Autoscaled process models and application performance

Using this smart service in a process model with autoscale enabled may result in degraded site or application performance. It should be used with caution and tested thoroughly before deploying it for real-world use. When the application is in production, use the Autoscaled Process Activity tab to monitor how the process performs at scale.

Execution modes

The Execute Generative AI Skill smart service can run in two distinct modes: standard and long running. Choosing the right mode depends on your use case and the complexity of your inputs.

• Standard (Default): This is the default behavior of the smart service. Standard mode is best for runs that can generally complete quickly or where you need an immediate response to use activity chaining in your process model. When used in a standard process, the AI skill called by the smart service needs to finish in 4.5 minutes; when used in an autoscaled process, the AI skill must finish in 1.5 minutes.
• Long Running: This mode is designed for processing lengthy or complex jobs that could otherwise fail because of the standard mode timeout limit. When you select this mode, the smart service checks at regular intervals to see if the model has responded, instead of keeping the process node active the entire time. This is the best mode for use cases that require significant processing time; however, activity chaining is not supported.

When to use Long Running mode

Use Long Running mode when you expect the Generative AI Skill smart service to take a long time to generate a response. Long Running mode lets a request finish without requiring the node to stay active the entire time.

For example, consider a financial services application that needs to process a 150-page compliance report. The process uses the generative AI skill to:

• Read the full document
• Extract key regulations
• Generate a plain-language summary of required actions

Because the input is large and the response must be comprehensive, the request may exceed the timeout limit of the Standard mode. Running the smart service in Long Running mode allows the process to continue once the AI output is ready.

Another example is an insurance company that needs to process a large number of claim documents at the same time. The process uses the Generative AI Skill smart service to:

• Analyze each document for claim details
• Extract customer and policy information
• Generate summaries for downstream processing

Because these jobs run in parallel, keeping them in standard mode would hold the process execution open and place unnecessary strain on system resources. Running the smart service in long running mode ensures the workload can complete efficiently in the background without requiring users to wait for results.

Things to know when choosing a mode

Consider the following when choosing a mode:

• You cannot use activity chaining when the node is running in standard mode.
• Long running mode does not support activity chaining.
• The Test button in the AI Skill will always run in standard mode and is still subject to the standard timeout limit, even if you have the long running mode selected in the smart service.

Input requirements

Input requirements correspond to the type of AI skill you're using with the smart service. Refer to the table below to see the requirements for each input type.

Different requirements apply for each input type:

• Text: Only plain text is supported for text input, so file size, page count, and image limits do not apply.
• Email: EML files are supported with a maximum file size of 25 MB. Page and image size limits do not apply.
• Document: See the following table for the Document input type requirements.

Document input type requirements

Excel and CSV input type requirements

The spreadsheet extraction skill has the following requirements for Excel files (XLS, XLSX, XLSM) and CSV files:

Using the runtime prompt

The Runtime Prompt is an optional prompt that the smart service can use instead of the prompt configured in the AI skill. Use a runtime prompt when the prompt needs to dynamically adjust based on user input, data, or context captured during the process execution.

This approach is helpful when you can't define all of the instructions during design time. For example, you can use a runtime prompt to automatically review and evaluate outputs generated earlier in the process. This approach helps improve straight-through processing and reduces the need for manual review.

The following process model example uses a runtime prompt to automate document evaluation and reduce manual review:

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Include examples

To get the best results with the runtime prompt, always provide clear instructions in plain text and include a few examples. Including examples in the runtime prompt helps guide the AI model to consistently provide a response in the format you want, which makes the output more predictable. Predictable output is easier to parse and use in later steps of a process.

In this example runtime prompt, we ask the AI model to verify the customer number and case number are in a valid format.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<Role>
You are an expert at validating customer and case numbers
using defined format rules.
</Role>

<Context>
A valid customer number follows the format: CUST-#####
A valid case number follows the format: CASE-#####
</Context>

<Instructions>
1) Confirm if each number matches its required format.
2) Return in JSON format as:
  {
  customerNumber: valid/not valid
  caseNumber: valid/not valid
   }
</Instructions>

Examples

Using spreadsheet extraction

When you use a spreadsheet extraction AI skill, the smart service returns a structured JSON response with extracted values and their cell references.

In this example, the skill is configured to extract invoice header fields and line items from an uploaded Excel file.

Example prompt (configured in the AI skill):

1
2
3
4
5
6
Extract the following fields from this invoice spreadsheet:
- Vendor name
- Invoice number
- Invoice date
- Total amount due
- Line items table, including description, quantity, unit price, and subtotal for each row

When executed via the smart service, the Response output contains JSON in the following format:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "vendorName": {
    "value": "Acme Corp",
    "cell": "Sheet1!B2"
  },
  "invoiceNumber": {
    "value": "INV-3337",
    "cell": "Sheet1!B3"
  },
  "invoiceDate": {
    "value": "2026-01-15",
    "cell": "Sheet1!B4"
  },
  "totalAmountDue": {
    "value": "4500.00",
    "cell": "Sheet1!B10"
  },
  "lineItems": [
    {
      "description": { "value": "Consulting Services", "cell": "Sheet1!A6" },
      "quantity": { "value": "10", "cell": "Sheet1!B6" },
      "unitPrice": { "value": "400.00", "cell": "Sheet1!C6" },
      "subtotal": { "value": "4000.00", "cell": "Sheet1!D6" }
    },
    {
      "description": { "value": "Travel Expenses", "cell": "Sheet1!A7" },
      "quantity": { "value": "1", "cell": "Sheet1!B7" },
      "unitPrice": { "value": "500.00", "cell": "Sheet1!C7" },
      "subtotal": { "value": "500.00", "cell": "Sheet1!D7" }
    }
  ]
}

Configure the smart service to store the Response output as a process variable such as pv!jsonOutput. You can then use a!fromJson() in a script task to cast the data to an Appian data type for use in later process steps.

Using runtime overrides for spreadsheet extraction

Use the Runtime Prompt and Runtime Model inputs to handle different spreadsheet templates dynamically within the same process.

For example, if your process receives invoices from multiple vendors, each with a different layout, you can build the extraction prompt dynamically based on the vendor type and pass it as the runtime prompt at execution time. This lets you reuse a single AI skill and smart service node across all templates without creating a separate skill for each one.

Similarly, use the Runtime Model input to switch to a more capable model when processing complex or large spreadsheets, while using a faster model for simpler files.

Using JSON

You can pass JSON as input to the smart service, or have JSON returned as output as defined in the prompt. JSON is a common format to create key-value pairs of data that interests you, and it is easily understood by AI models. Therefore, JSON is an easy way to ask the AI skill to return structured data. Once the output is passed to the process model, you can use functions such as a!fromJson to cast the data to Appian data types.

Example prompt

In this example prompt, we ask the AI to find information within an unstructured document, such as a contract.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<role>
You are an expert at sifting through large amounts of information and finding the entities of interest. Find the below entities from the input information. Here are the entities you need to return:
</role>

Use the <input> to fill out all <entities>:
<entities>
{
  "invoiceNumber" (type: text)
  "orderNumber" (type: text)
  "invoiceDate" (type: date)
  "dueDate" (type: date)
  "totalDue" (type: decimal)
  "items" (type: list of objects): 
        "Hours/Qty" (type: decimal)
        "Service" (type: text)
        "Rate/Price" (type: decimal)
        "Adjust" (type: decimal)
        "Subtotal" (type: decimal)
}
</entities>

<instructions>
- Only output <entities> listed above from the <input>.
- For fields of 'date' type, return value using ISO 8601 format yyyy-MM-dd, do not return time if present
</instructions>

When executed via the smart service, the prompt returns the following output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "invoiceNumber": "INV-3337", 
  "orderNumber": "12345",
  "invoiceDate": "2016-01-25", 
  "dueDate": "2016-01-31",
  "totalDue": "93.50",
  "items": [
    {
      "Hours/Qty": "1.00",
      "Service": "Web Design",
      "Rate/Price": "$85.00",
      "Adjust": "0.00%",
      "Subtotal": "$85.00"
      }
  ]
}

Configure the smart service to store the output as a process variable such as pv!jsonOuput, so you can work with it more easily in later nodes.

Using a script task and the a!fromJson function, you can then cast this data to a record type:

1
2
3
4
cast(
  recordType!Orders,
  a!fromJson(pv!jsonOutput)
)

Finally, add and configure a Write Records smart service to save the data to the record type.

Runtime behavior

At run-time, the smart service calls a machine learning model that is associated with the AI skill configured in the Setup tab.

Possible error messages

Consult the following table to learn how to fix common errors when using this smart service:

Feedback