πŸ§ͺ Hands-On Lab: Build Your First AI Agent

Work through 12 exercises using 4 real datasets. Each exercise uses the exact instructions and sample utterances from the OAC Agents Technical Guidance β€” practice building Supplemental Instructions that tell the Agent how your business thinks.

πŸ“‹ Prerequisites

Access

OAC instance with BI Content Creator role + "Create and Edit AI Agents" permission enabled via Console β†’ Roles and Permissions

Gen AI Enabled

Console β†’ Extensions and Enrichments β†’ Generative AI. Select a Gen AI Service under AI Assistant Features.

Datasets Uploaded

Upload all 4 datasets below into OAC. Right-click β†’ Inspect β†’ Search β†’ Index for Assistants β†’ Run Now.

Agent Created

Home Page β†’ Create β†’ AI Agent. Attach the dataset indicated for each exercise. Add SI in the Supplemental Instructions box.

πŸ—ƒοΈ Four Datasets β€” Four Agents

Each exercise specifies which dataset to use. You'll create up to 4 agents, one per dataset. Download and upload these into your OAC instance.

DatasetKey ColumnsUsed In Exercises
SOL.xlsxOrder Priority, Product Category, Product Sub Category, Product Name, Sales, Profit, Shipping Cost, City, Customer Name, Ship Mode, Order Date1–6, 9
Retail_Sales.xlsxcategory, sales_revenue, transactions, selling_area_sqft, store_name, region7
Sample_Superstore_-_Rate.xlsxSales, Shipping Rate, Segment, Category, Region, Profit, Quantity8
GP_Sales_Locations.csvLATITUDE, LONGITUDE, Sales, Cat10–12
⬇️ Download SOL.xlsx ⬇️ Download Retail_Sales.xlsx ⬇️ Download Sample_Superstore_-_Rate.xlsx ⬇️ Download GP_Sales_Locations.csv
Choose an Exercise Track
🟒
Beginner Track
Exercises 1–6: Grouping, Hierarchy, Defaults, Filters, Charts, Shortcuts
Dataset: SOL.xlsx · ⏱ ~30 min
🟑
Intermediate Track
Exercises 7–9: KPI Formulas, Aggregation Rules, Fiscal Calendar
Datasets: Retail Sales Superstore SOL · ⏱ ~30 min
πŸ”΄
Advanced Track
Exercises 10–12: Geo Distance, Shop Locations via RAG, Full Agent Build
Dataset: GP_Sales_Locations.csv · ⏱ ~45 min
🟒 Beginner Track β€” Core Agent Behaviors
All exercises use SOL.xlsx Β· Create one Agent, add instructions incrementally
1
Grouping of Attributes
Technical Guidance Β§7.1
SOL.xlsx
Objective

Classify 'Order Priority' into 2 groups. The column has values: Low, Medium, High, Critical, Not Specified. Map them to "Regular" and "Important".

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 key words such as, 'important', 'regular', 'important vs regular', use the above mapping of the 'Order Priority'
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Compare Average Profit for Regular and Important Orders"

2. "Revenue for Important Orders"

3. "Important vs Regular by Shipping Cost"

βœ… Expected

Agent groups Low+Medium+Not Specified as "Regular" and High+Critical as "Important" and shows comparison.

2
Hierarchies and Drill-Downs
Technical Guidance Β§7.2
SOL.xlsx
Objective

Create a product hierarchy drill-down: Product Category β†’ Product Sub Category β†’ Product Name.

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.
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Profit by Product Category" β†’ then say "Drill Down" β†’ then "Drill Down" again

2. Should navigate: Category β†’ Sub Category β†’ Product Name

3. At Product Name level, drill down should say "most detailed level"

3
Setting Default Metric
Technical Guidance Β§7.3
SOL.xlsx
Objective

When users ask generic questions without specifying a metric, default to "Sales" (Revenue).

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.
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Compare Cities for furniture product category" β†’ Sales should be picked up automatically

2. "Show performance by region" β†’ Should default to Sales

3. "Profit by Product Category" β†’ Should use Profit (user specified it)

4
Include a Filter by Default (City = "Toronto")
Technical Guidance Β§7.4
SOL.xlsx
Objective

Auto-apply City = "Toronto" filter on every query, even when the user doesn't ask for it.

Always include the filter City = "Toronto", even if the user does not explicitly ask for them.
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Revenue by Shipping Mode" β†’ Should auto-filter to Toronto

2. "Sales by Product Category" β†’ Check that City: Toronto appears

5
Default Chart Types
Technical Guidance Β§7.5
SOL.xlsx
Objective

Specify default visualization types: Table for categories, Area Chart for time trends.

Even if user does not specify the chart, when comparing between categories β†’ use Table and for time-based trends β†’ use Area Chart as default.
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Sales by Product Categories" β†’ Without instruction: Bar chart. With instruction: Table

2. "Sales trend by month" β†’ Should show Area Chart

6
Default Report / Shortcuts
Technical Guidance Β§7.6
SOL.xlsx
Objective

Create a shortcut for "Monthly Summary" / "Monthly Report" that auto-generates a specific table.

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

Month is hardcoded in this example. In production, you'd update this value when the period changes.

πŸ§ͺ Test It β€” Ask Your Agent:

1. "Monthly Report" β†’ Should produce Table with Sales, COUNT(DISTINCT Order ID), Shipping Cost filtered to Oct 2025

2. "Performance this month" β†’ Same output

πŸŽ‰ Beginner Track Complete!
You've built core agent behaviors using SOL.xlsx.
🟑 Intermediate Track β€” Calculations, Aggregation & Time
These exercises use different datasets β€” create a separate Agent for each
7
Formulas and KPI Calculations
Technical Guidance Β§7.7
Retail_Sales.xlsx
Objective

Create custom KPI calculations: Average Transaction Value (ATV) and Sales per Sq. Ft using columns from the Retail Sales dataset.

⚠️ New Agent Required

Create a new AI Agent and attach Retail_Sales.xlsx as the dataset. Index it first.

KPI : Average Transaction Value (ATV) When users asks about ATV (Average Transaction Value),use the following formula to compute : Sum(Sales_Revenue) / Sum(# of Transactions). Use the same formula to aggregate at a group level KPI : Sales per Sq. Ft When users asks about Sales per Sq. ft (Sales per Square feet or any such variants), use the following formula to compute : Sum(Sales_Revenue) / Sum(Selling_Area_sqft). Use the same formula to aggregate at a group level
πŸ§ͺ Test It β€” Ask Your Agent:

1. "ATV Per Category" β†’ Should compute Sum(sales_revenue) / Sum(transactions)

2. "Sales per Square Feet by Region" β†’ Should compute Sum(sales_revenue) / Sum(selling_area_sqft)

8
Set Aggregation Rules
Technical Guidance Β§7.12
Sample_Superstore_-_Rate.xlsx
Objective

Define default aggregation rules per metric. Without this, the agent might Sum a Shipping Rate instead of Averaging it β€” silently producing wrong numbers.

⚠️ New Agent Required

Create a new AI Agent and attach Sample_Superstore_-_Rate.xlsx as the dataset.

When aggregating metrics, apply the following default rules unless the user specifies otherwise: Revenue, Sales = Sum(Sales), Shipping Rate = Average (Avg) 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.
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Shipping Rate by Segment" β†’ Should automatically use AVG (not Sum)

2. "Sales by Category" β†’ Should use Sum

3. "Average Sales by Region" β†’ User said "average" β€” should override Sum default

9
Top N and Bottom N
Technical Guidance Β§7.8
SOL.xlsx
Objective

Standardize ranking behavior: default to Top/Bottom 5, default metric Sales, map keywords like "Best" and "Worst".

When the user asks for "Best," "Highest," "Most profitable," "Most Sales", "Leading" or Top items, rank by Top 5 records by default. When the user asks for "Bottom N," "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" is Top 5. "Bottom 3 Cities by Sales" Bottom 3 Cities.
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Show Top Customers" β†’ Top 5 customers by Sales

2. "5 Worst Profitable Product Sub categories" β†’ Bottom 5 by Profit ascending

3. "Best 3 cities" β†’ Top 3 by Sales

πŸŽ‰ Intermediate Track Complete!
Your agents now handle KPIs, aggregation rules, and ranking.
πŸ”΄ Advanced Track β€” Fiscal Calendar, Geo Intelligence & Full Build
Exercises 10–11 use GP_Sales_Locations.csv Β· Exercise 12 uses SOL.xlsx
10
Time Handling and Fiscal Calendars
Technical Guidance Β§7.9
SOL.xlsx
Objective

Map a non-standard fiscal calendar (FY = Jun 1 – May 31) so "current quarter" uses fiscal logic, not Gregorian. Note: Update hardcoded values when your fiscal periods change.

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.
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Show Revenue for Current Quarter" β†’ Should filter to FY2026 Q2

2. "Compare Previous and Current Fiscal Years Profits" β†’ FY 2025 vs FY 2026

11
Geographic Distance Calculations
Technical Guidance Β§7.10
GP_Sales_Locations.csv
Objective

Enable location-aware queries using LATITUDE and LONGITUDE columns for distance-based filtering.

⚠️ New Agent Required

Create a new AI Agent and attach GP_Sales_Locations.csv.

When asked for distance, use latitude and longitude as geo coordinates to calculate the distance. Use positive and negative longitude and latitude. When asked for a map, use latitude and longitude to plot the data. When the user says "within X miles of ", interpret this as a distance filter: Compute distance from each record's (LATITUDE, LONGITUDE) to the specified location. Keep only records where Distance <= X miles. If the X miles are not specified and terms like near or at the localtion used, the default is 50 Miles. Default Chart type for all such questions is 'Map'
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Map the Sales" β†’ Should show Map using LATITUDE, LONGITUDE

2. "Show Sales in Tennessee" β†’ then "Change Chart Type to Map"

3. "Show me sales near Nashville" β†’ Should use 50-mile default radius on Map

12
Mark Business Locations via Knowledge Documents
Technical Guidance Β§7.11
GP_Sales_Locations.csv
Objective

Add named shop coordinates via Supplemental Instructions so users can say "near Shop-ABC" and the agent resolves coordinates. In production, shop locations could also be added as a Knowledge Document (RAG).

Adding Shop Coordinates. When asked for distance, use latitude and longitude as geo coordinates to calculate the distance. Use positive and negative longitude and latitude. When asked for a map, use latitude and longitude to plot the data. When the user says "within X miles of ", interpret this as a distance filter: Compute distance from each record's (LATITUDE, LONGITUDE) to the specified location. Keep only records where Distance <= X miles. If the X miles are not specified and terms like near or at the localtion used, the default is 50 Miles. Default Chart type for all such questions is 'Map' All the Shop locations are as follows: Shop-ABC is located at 41.8781Β° N, 87.6298Β° W Shop-MNO is located at 44.9778Β° N, 93.2650Β° W Shop-PQR is located at 39.9526Β° N, 75.1652Β° W Shop-HIJ is located at 33.4484Β° N, 112.0740Β° W Shop-ATT is located at 33.7490Β° N, 84.3880Β° W Shop-XYZ is located at 40.7128Β° N, 74.0060Β° W Treat the above locations as the source of truth for named business locations such as "Shop-ABC", "Shop-ATT (ATL)", etc. When a user refers to a shop or shorthand, "Shop ABC", "ABC shop", "store ABC" β†’ map to the coordinates given above.
πŸ§ͺ Test It β€” Ask Your Agent:

1. "Show Sales near Shop ABC" β†’ Should resolve to Chicago (41.8781Β°N, 87.6298Β°W), 50-mile radius, Map

2. "Show Sales within 300 miles of Shop XYZ" β†’ Should resolve to NYC coordinates, 300-mile radius

πŸ† All Exercises Complete!
You've worked through all 12 use cases from the OAC Agents Technical Guidance using 4 real datasets. Return to the Quick Start Guide for industry templates, or visit the Deep Dive Studio for advanced frameworks and techniques.

πŸ“š References & Resources

▢️ Video Walkthrough
OAC AI Agents β€” Getting Started
YouTube Β· Step-by-step demo of creating and configuring AI Agents
πŸ“– Documentation
Oracle Analytics AI Agents Overview
Oracle Docs Β· Concepts, architecture, and capabilities
πŸ“– Documentation
Create an Oracle Analytics AI Agent
Oracle Docs Β· Step-by-step creation guide with dataset, SI, and Knowledge Docs
⚑ Quick Start Guide
Supplemental Instructions β€” Quick Start
Industry templates, interactive builder, 16 use cases, 8 techniques