Supplemental Instruction Templates for OAC AI Agents

Laxminag Mamillapalli

Introduction

OAC AI Agents generate insights directly from your semantic model and underlying datasets. Insights must align with approved fiscal calendars, KPI definitions, grouping standards, and reporting conventions that reflect how the business operates. This section presents templates that can serve as reference models for your use case.

These Supplemental Instruction Templates provide structured examples that guide AI Agents to interpret, calculate, filter, and present data according to your organization’s defined business logic. Rather than relying on default interpretation, these templates demonstrate how you can standardize Agents' behavior according to your use cases.

Note: These templates are provided as reference examples only. They are intended to demonstrate common instruction patterns and may require modification to align with your policies, and reporting standards. Oracle recommends reviewing and validating all instructions in a controlled environment before deploying them to production.

List of Use Cases

1. Grouping of Attributes
2. Hierarchies and Drill-Downs
3. Setting a Default Metric
4. Applying a Default Filter
5. Defining Default Chart Types
6. Default Reports / Shortcuts
7. Formulas and Calculations
8. Top N and Bottom N Logic
9. Handling Fiscal Calendars
10. Setting Aggregation Rules

Grouping of Attributes

One of the most common challenges in enterprise analytics is that raw data classifications do not always match how the business defines its categories. Different systems, departments, or regions may use varying names, codes, or groupings for the same attributes—creating confusion and inconsistency in analysis. This example helps you define your own logical groupings or categories or adding names according to your requirements. 

In this example, we want to consolidate the "Order Priority" column into two business-friendly groups. The original dataset contains the following values: Low, Medium, High, Critical, Not Specified From a business reporting perspective, however, users prefers to analyze orders under two broader categories:

• Regular → Low, Medium, Not Specified
• Important → High, Critical

Instructions:

When user asks about Important Orders or Regular Orders, use the following exact mapping:

-  "Low, Medium, Not Specified" are mapped to "Regular" Orders and 

- "High, Critical" are mapped to "Important"

When user uses key words such as,  "important",  "regular", "important vs regular" , use the above mapping of the "Order Priority."

Sample Utterance and Result:

"Compare Average Profit for Regular and Important Orders"

Hierarchies and Drill-Downs

In business reporting, decision-makers rarely stop at a single aggregated view. You want to review the metrics at a high level first and then want to progressively explore deeper layers of detail. This structured exploration is commonly referred to as a drill-down hierarchy.Without guidance, an AI system may treat all fields as flat attributes rather than understanding the intended analytical hierarchy. You can define custom Instructions that allows you to explicitly define these hierarchical relationships.

Instructions:

If the user has used the term "Drill Down" or similar, enable intelligent chart drill-downs following the product hierarchy: 

Product Category → Product Sub-Category → Product Name. 

Drill Down is applied only When the Chart has "Product Category" or "Product Sub Category".

Drill-Down Logic:

If the current chart is Product Category, then on user request "Drill Down", then Display the Product Sub-Category chart.

If the current chart is Product Sub-Category, then on user request "Drill Down", Display the Product Name chart.

If the current chart is Product Name, there is no further level to drill down. Politely indicate that the user has reached the most detailed level. Perform drill-down only when the user’s request matches the hierarchy level of the currently displayed column.

If the request refers to a column not present or unrelated to the current chart, ignore the request gracefully and maintain the current view. When “Drill Down” is mentioned without specifying a column, infer it based on the last displayed chart.

Sample Utterances and Results:

Ask an uttrence with Product Category and the followed up by Drill Down.

"Profit by Product Category" →	"Drill Down" →	"Drill Down"

Setting a Default Metric

As an Agent Creator, you can specify how results should behave or be presented when users ask broad or high-level questions. This ensures that insights remain consistent, intuitive, and aligned with business expectations — even when the user query lacks specificity. In many datasets, users frequently ask open-ended questions such as: "Show performance by region",  "Compare across products", "How are we doing this quarter?". While these questions are clear in intent, they often do not specify which metric should be used — Revenue? Profit? Order Volume? Margin? Without guidance, the AI may either choose a metric that may not align with business priorities or may not answer the question.

You can use customized instructions by setting a default metric ensures consistent interpretation of high-level or ambiguous queries. 

If the user does not specify any metric, and ask generic questions use "Revenue" as the default metric for all aggregations and charts. 

For example if user asks "compare performance across Product Categories" provide visual related to Product Category by Sales.

Sample Utterance and Result:

"Compare Cities for furniture product category"

Applying a Default Filter

In many business scenarios, certain filters should always be applied to ensure consistency, governance, or contextual relevance in reporting. For example, your dashboards may focus on a specific fiscal year, region, marketor a product category. Without defined defaults, AI-generated outputs calculate for entire dataset and does not set the context. Custom Instruction Templates allow Agent Creators to enforce default filters, ensuring that every response aligns with predefined business boundaries.

Instructions:

Always include the filter City = "Toronto", even if the user does not explicitly ask for them. 

Sample Utterance and Result:

"Revenue by Shipping Mode"

Defining Default Chart Types

You can also guide how insights are visually presented. Custom Instruction Templates allow Agent Creators to define default visualization types. This ensures that outputs are not only accurate — but also presented in a way that aligns with your reporting standards.

Instructions:

If the query involves comparison (e.g., "compare", "vs", "across") for Product Category, Product Sub-Category, or any categorical comparison → Always use Table. 
If the query involves any time-based field (Date, Month, Quarter, Year) → Always use Area Chart. 
Apply these defaults even if the user does not specify a chart. 
Only override if the user explicitly requests a different visualization.

Sample Utterances and Results:

"Profit by Product Sub categories"	"Monthly Profit for Year 2016"

Default Reports / Shortcuts

Objective:
Enable predefined shortcuts for recurring business queries such as "Monthly Summary" or "Monthly Report". Using Custom Instructions, you can map specific keywords to a predefined report structure. When users enter a shortcut phrase, the Agent automatically generates a standardized output — including defined metrics, filters, groupings, and chart types. This ensures consistency, saves time, and aligns recurring analysis with common reports.

Instructions:

When user asks "Monthly Summary", "Monthly Report", "Summary", "Report" or "Performance this month", 
automatically apply filter where Order Date (Month) = October 2025,
then Generate a Table with the following Metrics.  
- Revenue (Sum) 
- Orders (Count of Distinct Order ID) 
- Shipping Cost (Sum)

Note: Month is Hard Coded in this case

Sample Utterance and Result:

When user asks "Monthly Summary", you get a Table.

Formulas and Calculations

You can define domain-specific or company-specific KPI calculations using Supplemental Instructions. In many cases, key performance indicators (KPIs) are not directly stored in the dataset. Instead, they are derived using business-defined formulas that may vary by company, industry, or reporting standard. Without explicit guidance, an AI system may compute metrics using generic definitions. Using Supplemental Instructions, Agent Creators can formally define: Custom KPI formulas, Company-specific calculation logic, Adjustments or correction factors, Derived metrics not physically stored in the dataset.

Instructions:

KPI : Average Transaction Value (ATV): 
When users asks about ATV (Average Transaction Value),
use the following formula to compute : Sum(Sales_Revenue) / Count Distinct (Order ID), and 
use the same formula to aggregate at a group level.

KPI : Return on Investment ROI: 
When users asks about ROI (or any such variants), 
use the following formula to compute : 100*(Sum(Profit) /((Sum(Discount)*Sum(Shipping Cost))), and
use the same formula to aggregate at a group level.

Sample Utterances:

"ATV Per Customer Category"	"ROI on each Product in a Table"

Top N and Bottom N Logic

Objective:
You can define consistent and predictable behavior for all "Top N" and "Bottom N" queries. In business conversations, users frequently ask for:

"Best products", "Highest performing Cities", "Least profitable Product Sub categories", "Lowest sales cities". Without defined rules, ranking logic may vary — leading to inconsistent outputs across users. 

Instruction Example:

When the user asks for "Best", "Highest", "Most profitable", "Most Sales", "Leading" or "Top items", rank by Top 5 records in descending order by default. 
When the user asks for "Bottom", "Least", "Lowest", or "Slowest", rank by Revenue ascending and return the Bottom 5 records by default.
If the user does not specify metric use "Sales" by default. If user specifies, use the metric specified by user. 
If User specifies number of categories to be apply Top N accordingly.
For example:
 - "Best 5 Products by Profit" → Top 5
 - "Bottom 3 Cities by Sales" → Bottom 3 Cities.
 - "Cities with highest discount" → Top 5 Cities

Sample Utterances and Results

“Show Top Customers in Paris”	“Worst Profitable Product Sub categories”

Handling Fiscal Calendars

Most organizations do not operate strictly on the standard Gregorian calendar (January–December). Fiscal years often begin in different months, and business quarters are defined according to internal financial reporting structures. If not explicitly defined, an AI system may default to calendar-year logic — leading to incorrect interpretations of terms such as: "Current Quarter", "This Fiscal Year" and so on. To prevent misalignment, Custom Instructions allow you to formally define your fiscal calendar structure.

The following enable full support for custom fiscal calendars (e.g., Fiscal Q1 = May–July) and explicitly prevent the use of Gregorian calendar definitions where business logic requires otherwise.

Instruction Example:

Use the Fiscal Calendar (FY = Jun 1–May 31). 
Quarters: Q1 Jun–Aug, Q2 Sep–Nov, Q3 Dec–Feb, Q4 Mar–May. 

Columns (exact, with spaces): "Fiscal Year", "Fiscal Quarter". Always quote identifiers. 
Year values: "FY 2026" (space after FY) 
Quarter values: "FY2026 Q2" (no space after FY, one space before Qn) 
Never auto-add/remove spaces—match dataset exactly. Trim and case-fold user text, but filters must use canonical spacing. Quote string values. 

Mappings → Filters: 
- "current/this quarter", "current fiscal quarter" → "Fiscal Quarter" = "FY2026 Q2" 
- "current/this year", "current fiscal year" → "Fiscal Year" = "FY 2026" 
- "previous/last/prior quarter" → "Fiscal Quarter" = "FY2026 Q1" 
- "previous/last/prior year" → "Fiscal Year" = "FY 2025"
- "next/upcoming/following quarter" → "Fiscal Quarter" = "FY2026 Q3" 
- "next/upcoming/following year" → "Fiscal Year" = "FY 2027" 

Specific month/date (e.g., "Feb 2023") → map to its fiscal quarter (Dec–Feb → FY2024 Q3) and filter "Fiscal Quarter" accordingly. 
Rule for Quarter should be based on Quarters: Q1 Jun–Aug, Q2 Sep–Nov, Q3 Dec–Feb, Q4 Mar–May.

Sample Utterance and Result:

User asks:  "Show Revenue for Current Quarter" → Agent applies Fiscal Quarter = FY26 Q2.

Note: Fiscal Dates are hard coded

Setting Aggregation Rules

Ensure that each metric follows a consistent, business-approved aggregation method — even when the user does not explicitly specify it.

In most datasets, different measures require different aggregation logic to produce meaningful insights. For example: Revenue should be Summed, Quantity should be Counted or Summed (based on business definition), Shipping Rate should be Averaged, etc. Without predefined rules, AI Agents may apply incorrect aggregations — such as averaging revenue instead of summing it — leading to misleading or materially incorrect conclusions. This Custom Instruction helps consistency at the Agent level.

Instructions:

When aggregating metrics, apply the following default rules unless the user specifies otherwise: 
 - Revenue, Sales = Sum(Sales) 
 - Discount = Average (Discount)

If the dataset contains other numeric fields without explicit instruction, apply Sum as the fallback aggregation method. 
When the user includes a keyword like "average", "count", or "sum", override the default aggregation accordingly.

Sample Utterance:

"Discount by Product Sub Category"

Rajia Sulthana

This is great.

Bhaskar Konar

Very helpful information.

Thanks for sharing!

SanthiSreeK-Oracle

Very Helpful information, thanks for sharing