AI Agent Designer

The AI Agent designer is split into two areas:

• Left sidebar for model and infrastructure configuration

• Main panel with four tabs:

  • Prompt / Instruction

  • Annotations

  • Explainable AI

  • Attachments

Left Sidebar

The sidebar contains settings that apply to the entire rule.

AI Model

Select the LLM that will execute the agent. Use the dropdown to browse available models. Once a model is selected, the Connector dropdown below is automatically filtered to show only connectors that are compatible with that model.

Connector

A Connector provides the authenticated link between DecisionRules and the LLM provider. Select an existing connector from the dropdown or click + Create to add one without leaving the designer. For details on setting up AI model connectors see Connectors.

Cache AI Response

When enabled, identical inputs return the cached result instead of calling the model again. Useful when the same input is likely to repeat and a fresh inference is not required every time. Covered in detail on the Caching page.

Explainable AI

When enabled, a system-defined explanation object is automatically added to the rule output. The Explainable AI tab becomes active and shows the fields that will be included. Covered in detail on the Explainable AI page.

Data Dictionary

Data Dictionary A live reference panel showing all data available to the prompt, organized into three groups:

• Input: all fields from the rule's Input Model, shown in their path hierarchy

• Rule Variables: static values defined at the rule level, versioned with the rule. See Rule Variables for how to create and manage them

• Attachments: available when one or more files are attached to the rule

All three groups are searchable in the Data Dictionary. Drag any variable directly into the prompt editor to insert it as a {variable}.

Keep your prompt lean. Reference only the fields the model genuinely needs to produce the output. This reduces token usage and keeps the model focused.

Prompt / Instruction Tab

The prompt is the full instruction sent to the model at execution time. Write it as a single text, there is no separate instruction field. Inputs and variables are highlighted in purple in the editor so they are easy to spot at a glance.

A Prompt Templates button in the top-right corner provides pre-built prompt structures for common use cases.

Prompt Variables

Variables reference fields from the Input Model using curly braces and dot-path notation:

// Input
{fieldName}
{parent.child}

// Rule Variable
{variables.globalTaxRate}

// Attachments
{attachments.NDA_Standards.pdf}

At execution time each {variable} is replaced with the actual value.

Only data that appears in the prompt as a variable is actually sent to the model at execution time, fields defined in the Input Model but not referenced in the prompt are ignored.

Annotations Tab

Annotations describe what each output field should contain. They are the primary way to control what the model returns, not the prompt. Every field defined in your Output Model has a corresponding annotation row in this tab.

Each annotation row has three elements:

• Field name: the output field path, matching the Output Model structure

• Field type: the expected data type for this field. For parent objects this is set to Object automatically and cannot be changed, only leaf fields have a type you select

• Description: a plain text instruction telling the model exactly what value to produce for this field

Field Type

Type	What's returning
Text	A string value
Number	An integer or decimal number (using decimal point)
Boolean	true or false
Object	A nested object (sets automaticaly for parent fields)
Array	A list of values
Auto	The model decides the type at runtime based on the value it returns

All field types are nullable. Instruct the model to return null in the annotation description when a value cannot be determined, see Handling Missing or Uncertain Data section below.

Use Auto sparingly. When the type is unpredictable, downstream rules that depend on that field may behave inconsistently. Prefer an explicit type wherever you know what the field should return.

Description

The description is the most important part of an annotation. It is not a label or a comment, it is a direct instruction to the model. The clearer and more specific it is, the more consistent and reliable the output will be.

A good description tells the model two things:

• what the value represents

• how to determine it

Handling Missing or Uncertain Data

If the model cannot determine a value from the input, instruct it to return null rather than a placeholder string like "N/A" or "unknown". Returning null is cleaner and far easier to catch in a downstream Decision Table using a IS_NULL operator.

Be consistent across all fields in the same rule. If you choose "unknown" as the fallback, apply it everywhere, mixing null with "unknown" or empty strings will make downstream conditions harder to write and maintain.

Explainable AI Tab

This tab is active only when the Explainable AI toggle is enabled in the sidebar. It shows the four system-defined fields that will be added to every response: probability, reason, source_fragments, and warnings. These fields are injected automatically.

See Explainable AI for a full description of each field and guidance on how to use them.

Attachments Tab

The Attachments tab lets you embed documents into the agent. The model can reason against a fixed reference document — a policy file, a contract template, a scoring rubric, or a regulatory guideline.

To add an attachment:

1. Open the Attachments tab and click Add Attachment.

2. Upload a file. It appears in the list and Data Dictionary with its filename.

3. To remove it, click the × button next to the file.

Once attached, the document is part of the rule definition and is versioned with it. Just like input variables, only attachments that are referenced in the prompt are actually sent to the model.

Reference an attachment in your prompt using the same variable syntax as input fields — drag it directly from the Data Dictionary or type it manually:

{attachments.Return_Policy.pdf}
{attachments.NDA_Standards.pdf}

Supported file formats

Most common formats work across all models:

• PDF

• Plain text (.txt)

• Markdown (.md)

• CSV

Some models support additional formats such as Excel (.xlsx) or Word (.docx) — support varies by provider.

Models without file support

If the selected model does not support file input, a warning will appear on the tab and the rule cannot be executed until the issue is resolved, either by removing the attachments or switching to a model that supports them.