AI Assistant & AI Agents

Download the Sample Dataset

1. Click the download button above to save SampleSales_Data.xlsx to your computer
2. Verify the file downloaded successfully — it should be approximately 2–3 MB

Upload to OAC and Create a Dataset

1. Log in to your OAC instance
2. On the Home page, click Create (top-right) — a menu appears showing Workbook, AI Agent, Dataset, Data Flow, Sequence, Connection, and Semantic Model
3. Click Dataset

Click Create → Dataset

Drop data file here or click to browse

4. The Create Dataset dialog opens, showing “From a File, Subject Area, or Connection”
5. Click Drop data file here or click to browse (the dashed-border area on the left) and select the SampleSales_Dataset.xlsx file from your computer
6. OAC will preview the data — you should see columns like Row ID, Order ID, Order Date, Ship Date, Ship Mode, Customer Name, Segment, Category, Sub-Category, Product Name, Sales, Quantity, Discount, Profit, and more
7. Review the column data types — OAC should auto-detect dates, numbers, and text correctly
8. Click Save — name the dataset SampleSales_Dataset

Cleanse the Data — Set the Right Column Types

When OAC auto-detects column types from an Excel file, a few columns come in as plain numbers even though they aren’t measures you want to sum. Fix these before indexing so the AI Assistant treats them correctly.

Open the dataset for prep

1. From the Home page, click the SampleSales_Dataset to open a new workbook.
2. At the top of the workbook, click the Data tab (next to Visualize and Present).
3. In the Data Diagram canvas, double-click the dataset tile (the box labelled SampleSale...) to enter the dataset editor, where you can change column data types and cleanse values for accuracy.

Workbook → Data tab → double-click the dataset tile to open the prep editor

Columns to fix

How to change a column type in OAC

1. In the dataset view, locate the column in the grid or column list on the left.
2. Click the small icon next to the column name (it shows # for number, A for attribute, calendar for date).
3. In the column properties panel, change Treat As from Measure to Attribute for Year, Postal Code, and Row ID.
4. For Latitude and Longitude, first set Treat As = Attribute, then assign the Location semantic (the 📍 pin icon appears next to the column name once OAC recognises it as a coordinate).
5. Click Save to commit the dataset changes.

Clean nulls and invalid values — accuracy matters

AI answers are only as accurate as the data behind them. Before indexing, sweep each column for missing (null) or out-of-range values so the Assistant doesn’t average in zeros, mis-plot coordinates, or return misleading counts.

1. Scan each column's value profile — the miniature bar chart at the top of every column shows a coloured breakdown. A red sliver indicates invalid or out-of-range rows; a grey sliver indicates null / empty cells.
2. Filter out invalid rows — right-click the column header and choose Filter by Valid Values. This is especially important for Latitude and Longitude: a single 0/0 coordinate will stretch a map to the Gulf of Guinea and hide real customers.
3. Handle nulls explicitly — don’t let them silently pass through. Depending on the column:
   • Measures (Sales, Profit, Quantity, Discount): replace nulls with 0 using the column’s Replace transform, only if a missing value truly means zero. If not, filter the row out instead — averaging in fake zeros skews every KPI.
   • Attributes (Segment, Category, Region, Customer Name): replace nulls with a literal label such as Unknown or Unassigned so the Assistant can still group by them instead of dropping those rows.
   • Dates (Order Date, Ship Date): never fabricate dates. Filter out rows where the date is null — time-series charts break otherwise.
4. Remove duplicates and junk rows — if the preview shows header rows repeated mid-sheet, rows with all-null measures, or test records, add a filter step or use Remove Rows with Nulls from the column menu.
5. Validate text consistency — use the Convert to Uppercase / Trim transforms on key join columns (e.g., Region, Segment) so “west”, “West”, and “WEST ” don’t end up as three separate values in AI answers.
6. Re-check the value profile after each transform and only save once every column’s bar is solid green (no red or grey slivers for columns the AI will be asked about).

Dataset editor — Treat As = Attribute for Latitude and the Location Details option on the column context menu

Year → Treat As: Attribute, Aggregation: None

Latitude / Longitude → right-click → Filter by Valid Values

Navigate to the Dataset and Open the Inspector

1. From the Home page Navigator, click Data (in the bottom navigation bar)

Navigator → Data page

Right-click the dataset → select Inspect

2. Navigate to the SampleSales_Dataset you uploaded, then right-click on the dataset and select Inspect
3. The Dataset Inspector opens, showing tabs on the left: General, Aliases, Data Elements, Search, Access, and Developer
4. Click the Search tab

Configure Index Settings

On the Settings sub-tab of the Search tab:

1. In the Index Dataset For dropdown, select Assistants and Homepage Search
2. Under Languages, leave as English
3. Under Indexing Schedule, leave the defaults for this exercise (you can choose “When Dataset is refreshed” or set a specific start time and repeat interval)
4. Click Save (top-right) — do not close the Inspector

Search tab → Settings: Select “Assistants and Homepage Search”

Configure Index Scope — Select Columns and Add Synonyms

Now click the Scope sub-tab. This is where the real tuning happens.

You will see a table listing all 27 columns with these columns:

Search tab → Scope: Select columns to index, set Index Type, and add Synonyms

1. Click Use Recommended Index Settings — this auto-selects the appropriate columns and sets Index Types
2. Deselect columns that users won’t ask about in natural language: Row ID, Postal Code, Latitude, Longitude, Employee Phone Number
3. Add synonyms for key columns (click the Synonyms field next to each column):

Column Name	Recommended Synonyms	Why
Sales	Revenue, Income, Total Sales, Earnings	Users may say “revenue” instead of “sales”
Quantity	Units, Volume, Units Sold, Qty	Common shorthand
Discount	Discounts, Discount Amount, Savings	Business term flexibility
Category	Product Type, Product Category	Some users think in product types
Sub-Category	Subcategory, Product Line	Naming variations
Order Date	Date, Sales Date, Transaction Date	Resolves date ambiguity
Segment	Customer Segment, Customer Type	Multiple ways to say it
Region	Territory, Area, Sales Region	Conversational language
Ship Mode	Shipping Method, Delivery Mode	Business context

4. Click Save
5. Click Run Now to start indexing
6. You should see a success message. You can click Check (top-right) at any time to verify the index status
7. Click Close to exit the Inspector
What just happened: The LLM now knows your dataset’s schema, column names, data values, and synonyms. When a user asks a question, the LLM maps their natural language to the correct columns. The index counter (e.g., “24/2000”) shows how many columns are indexed out of the maximum allowed.
Sensitive Data warning: The Scope tab shows a yellow banner: “Indexed data is visible to all users with access to that column. For sensitive columns, enable Sensitive Data to restrict visibility.” This sample dataset has no sensitive data, so leave all Sensitive Data checkboxes unchecked.

Indexing Subject Areas (Production Use)

In production, most enterprise customers use Subject Areas instead of file-based datasets. The indexing workflow is different:

1. Navigate to Console → Search Index
2. Click Enable Data Model Crawl
3. Select which subject areas, folders, and columns to index
4. Set Crawl Status to Index (name & values) or Index Metadata Only (name only)
5. Add synonyms in the Search Index configuration
6. Set a crawl schedule (start date, time, frequency)

Download the SampleSales.dva and Import it into Your OAC Instance

1. Download the pre-built project from GitHub:
   ⬇️ Download SampleSales.dva

   ∼3.6 MB · Oracle Analytics portable project archive — bundles the dataset, workbook, synonyms, and a starter AI Agent in one file
2. Open your own OAC instance and sign in. You’ll import the .dva here so you can run, edit, and ask questions against it.
3. From the Home page (or Navigator → Catalog), click the Page Menu — the three dots beside the Create button in the top-right — and choose Import Workbook/Flow…
   

   Page Menu (3 dots, top-right) → Import Workbook/Flow…
4. In the Import Workbook/Flow dialog, click Change File, pick the SampleSales.dva you just downloaded, then click Import.
5. By default, OAC imports everything into My Folders. After a successful import you’ll see:
   • SampleSales_Dataset — the dataset
   • A folder called SampleSales containing the Sample Sales workbook and the Sales Agent
6. Check Indexing on SampleSales_Dataset. The imported .dva already ships with indexing configured for Assistants and Homepage Search, so in most cases you can skip straight to asking questions. You can confirm this from Inspect → Search → Settings — the top-right of the panel shows Last Run: Success with a date.
   Only re-run indexing if… the AI prompt window doesn’t return answers for this dataset in your own instance. To re-run it: right-click SampleSales_Dataset → Inspect → Search tab → on the Settings sub-tab make sure Index Dataset For is set to Assistants and Homepage Search, then click Run Now (or Check Now top-right) and wait for the run to complete. (Full walkthrough: Lab 2 — Indexing & Synonyms.)
   Prompt window disabled or not accepting input? This is almost always a permissions issue in your OAC instance. Open the dataset’s Inspect → Permissions (Access) panel and make sure your user (or the role you’re signed in as) has the right access — typically Author or Consumer — then reload the workbook or Agent.
7. You now have two ways to start asking questions:

   Path 1 — Workbook AI Assistant

   Open the Sample Sales workbook inside the SampleSales folder and ask questions directly from the Workbook AI Assistant.

   Path 2 — Sales Agent

   Open the Sales Agent, upload the policy .txt file (see QS.2), Save, and start asking.

Add the Policies Document to the Agent

The AI Agent uses this document as its knowledge source — it’s how the Agent learns your targets, KPIs, and business rules. You have two options:

Policy content (for Option B)

SALES DISCOUNT POLICY
  - Discounts above 30% require VP approval
  - Standard Class shipping default for orders under $500
  - Volume discounts: 5% for >50 units, 10% for >200 units

QUARTERLY TARGETS (2025)
  - Q1: $2.0M
  - Q2: $1.5M
  - Q3: $600K
  - Q4: $500K
  - Full Year Target: $4.5M

REGIONAL STRATEGY
  - East: Focus on Technology products
  - West: Expand Office Supplies distribution
  - Central: Grow Consumer segment penetration
  - South: Increase Furniture market share

KEY PERFORMANCE INDICATORS
- Primary KPI: Sales (also referred to as Revenue)
- Profitability KPI: Profit Ratio % = Profit / Sales × 100
- High-Value Customer Threshold: Sales > $35,000
- Default Ranking: Top 10 (unless user specifies otherwise)

QUARTERLY TARGETS (2026)
  - Q1: $2.4M
  - Q2: $1.8M
  - Q3: $700K
  - Q4: $600K
  - Full Year Target: $5.3M

FISCAL CALENDAR
- Fiscal Year: January 1 to December 31
- Quarters: Q1 = Jan–Mar, Q2 = Apr–Jun, Q3 = Jul–Sep, Q4 = Oct–Dec
- Dataset contains data through April 15, 2026

Save it anywhere convenient on your computer — Desktop is fine.

Upload it to the pre-built Agent and save

1. Click the Navigator icon — the 9-dot grid in the top-left corner of Oracle Analytics — then choose Catalog.
2. In the Catalog, locate the starter Agent that was imported with the .dva (named something like SampleSales Agent) and click to open it.
3. Go to the Knowledge (Documents) tab → Upload Document.
4. Select the file you downloaded or created (.txt or .pdf) and click Open.
5. Click Save to commit the Agent with the new knowledge document.

Navigator icon (top-left 9-dot grid) → Catalog

Start Asking Questions

You’re ready. Two entry points — pick whichever matches your question:

1. AI Assistant (data questions): Open the SampleSales_Dataset, then click the ✨ Sparkle icon in the workbook toolbar. Ask questions about what’s in the data — sales, profit, regions, customers.
2. AI Agent (business-context questions): From the Navigator (9-dot grid, top-left) open Catalog, then click the starter Agent that came with the .dva and start prompting directly on the dataset. Ask questions that reference your policies or targets — the Agent pulls answers from both the data and your uploaded document.

About the Sample Data

Think of yourself as a regional sales analyst at a fictional US office-supplies & technology retailer. You’re responsible for tracking how the business is performing across the country, spotting what’s working and what isn’t, and reporting back against the company’s quarterly targets and regional strategy.

The SampleSales dataset is your full book of business. It captures every product sold on every order across the last several years — just over seven years of sales history, from January 2020 through mid-April 2026. That’s roughly $21M in total sales, ~$914K in profit, and about 18,000 order lines to explore.

The business sells across the entire United States, organized into six regions — East, West, Central, South, plus two sub-regions called S.East and Western. Customers fall into three segments: everyday Consumer shoppers, larger Corporate accounts, and independent Home Office buyers.

The product catalog spans three categories — Furniture (bookcases, chairs, tables), Office Supplies (binders, paper, storage, art), and Technology (phones, accessories, machines, copiers) — broken down into 17 sub-categories in total. Every order has a customer, a shipping method, a location, a sales rep, and the usual measures you’d expect: sales, quantity, discount, and profit.

On top of the raw data, the AI Agent also knows your business context: quarterly revenue targets for 2025 and 2026, the regional focus strategy (East → Technology, West → Office Supplies, Central → Consumer, South → Furniture), KPI definitions (Profit Ratio, high-value customer threshold), and the discount-approval policy. That’s the layer the sales_policies_targets.txt file adds.

Try These First

Warm up with data-only questions in the AI Assistant, then switch to the AI Agent to see how the policy document changes the answers.

Ask the AI Assistant (data-only)

Ask the AI Agent (data + policies)

Open a Workbook and Launch the Assistant

1. From the Home page, double-click the SampleSales_Dataset dataset to create a new workbook
2. In the workbook toolbar (top-right), click the ✨ Sparkle icon
3. A panel opens on the right side of the workbook with three tabs:

4. Click the Assistant tab
5. If indexing completed successfully, you will see a welcome message and a text box to type questions

Step 3.2 — Ask Questions

Type the following prompts into the Assistant tab. Each demonstrates a different capability.

Add Visualizations to Your Workbook

1. Hover over any visualization generated by the Assistant
2. Click + Add to Canvas
3. Click Additional Insights to see related insights
4. Repeat to build a complete dashboard
5. Click Save — name it AI Assistant Guide — Sales Dashboard

Create the Agent Shell

1. From the Home page, click Create → AI Agent. If you are already in the AI Agents area, click Create Agent.
2. Name the agent Sample Sales Analyst.
3. Save the agent once so the configuration is created.

Connect the Agent to Its Data Source

1. Open the new agent and click Add Data Source.
2. Select Dataset → SampleSales_Dataset. Oracle Analytics also supports Subject Area and Local Subject Area as Agent sources.
3. Confirm the dataset is already indexed from Lab 2 before you continue. Oracle documents one dataset per AI Agent.
4. Use the Agent editor to review indexed columns, activate only the fields you want the Agent to reference, and define any Agent Filters that should always apply to every question.
5. The Agent inherits the indexing and synonyms already defined on that source.

Add Supplemental Instructions (R.T.C.C.O.E. Framework)

Supplemental Instructions encode your business logic, vocabulary, output guidance, and default behaviors (up to 6,000 characters). Use the R.T.C.C.O.E. framework to structure them for maximum accuracy:

Paste the following instructions into the Instructions field:

Add the Welcome Message and Save the Agent

1. Enter a clear welcome message: “Welcome! I’m your Sales Analytics Expert. Ask me about sales performance, products, regions, customer segments, and trends. Try: ‘Show me the Sales Dashboard’ or ‘Who are our high-value customers?’”
2. Add 2–4 starter examples so users know what kinds of questions the Agent is designed to answer.
3. Click Save to save the Agent.

Upload Knowledge Documents (RAG)

Knowledge Documents extend the Agent’s knowledge beyond the dataset. Upload up to 10 PDF or TXT files (each file must be under 5 MB). In newer OAC releases you can also assign document priority levels such as High, Regular, or Low.

Create a file like this to use with your Agent:

Save the Agent

1. Review all the sections you have configured — Data Source, Instructions, Welcome Message, and Knowledge Documents.
2. Click Save to save the final Agent configuration.

Associate the Agent to a Workbook

Now that the Agent is built, let’s connect it to a workbook so users can get AI-powered insights. Open the workbook you saved in Lab 3 and associate the Agent:

1. Open the workbook and click the Present tab in the top menu
2. In the left panel, expand Insights Panel and toggle it to On. Make sure Watchlists and Workbook Assistant are both set to On.
3. Under Workbook Assistant, click the + button next to Agents
4. In the Select an AI Agent dialog, navigate to your folder and select Sales Agent
5. Click OK to associate the Agent to the workbook
6. Save the workbook

Use the Agent — Two Ways

Now that the Agent is built and associated to a workbook, there are two ways to interact with it:

Step 4.9 — Test the Agent for Accuracy

Before publishing an Agent to users, you must systematically test for accuracy. Use the following test plan, which covers five dimensions:

Iterate — The Accuracy Improvement Cycle

Agent accuracy is not a one-time setup. Use this continuous cycle after each round of testing:

1. Test — Run sample queries covering all 5 accuracy dimensions
2. Identify gaps — Which questions produce wrong metrics, wrong charts, or fabricated data?
3. Diagnose the root cause:

4. Update — Modify instructions, add synonyms, or improve knowledge documents
5. Re-test — Validate the fix with the original failing query and existing passing queries (regression check)
6. Expand — Once accuracy is validated, publish to broader user base and collect thumbs up/down feedback

Pre-Deployment Accuracy Checklist

Before publishing your Agent to users, validate every category. An Agent that passes this checklist will perform reliably and maintain user trust.

Enable AI Assistant for Consumer Role Users

Before consumers can use the AI Assistant inside workbooks, an administrator must create an application role with the correct permission and assign users to it. This is a one-time setup.

Step 1 — Create an Application Role

1. Navigate to Navigator → Console → Roles and Permissions → Application Roles.
2. Click Create Application Role.
3. Enter a name (e.g. Consumer Assistant Role) and a description.
4. Click Create.

Step 2 — Add Memberships

1. Open the new role and go to the Memberships tab.
2. Click Add Application Roles.
3. Select DV Consumer (to inherit base consumer capabilities).
4. Click Add Selected.

Step 3 — Add the Permission

1. Go to the Permissions tab.
2. Click Add Permissions.
3. Search for and select Use Assistant in Workbooks.
4. Click Add Selected.

Step 4 — Assign Users

1. Go to the Members tab.
2. Click Add Users to assign individual users, or click Groups to assign an entire group at once.
3. Search for the desired users/groups, select them, and click Add Selected.

Turn On Workbook Assistant in the Present Tab

1. Open the workbook you saved in Lab 3 (AI Assistant Guide — Sales Dashboard)
2. Click the Present tab in the top menu
3. In the left-hand menu, locate Insights Panel
4. Toggle Insights Panel to On
5. Select which tabs to display to consumers:
   • Watch List — allows consumers to see and track saved metrics
   • Workbook Assistant — enables AI Assistant queries on this workbook’s dataset
   Turn on both for the full experience.
6. Save the workbook

Save and Share the Workbook with Consumers

1. Save the workbook in a shared folder.
2. Grant the appropriate workbook access to the consumer users or roles who need access.
3. Share the workbook URL or direct consumers to the shared folder location.
4. If you want consumers to use the Agent from the workbook, make sure you completed Lab 4 and selected the Agent in the Workbook Assistant settings before consumers begin Lab 6.

Before You Begin

To use the AI Assistant as a consumer, the following must already be in place:

1. An administrator has assigned you to a role with the Use Assistant in Workbooks permission (for example, a custom “AI Assistant Consumer” role — see Lab 8)
2. An author has created a workbook, indexed the dataset, and enabled the Insights Panel in the Present tab
3. The author has shared the workbook with you

Open the Shared Workbook

1. Log in to your OAC instance
2. From the Home page, find the workbook that has been shared with you (e.g., AI Assistant Guide — Sales Dashboard)
3. Click to open it — it opens in consumer/view mode

Launch the AI Assistant

1. In the workbook toolbar, click the ✨ Sparkle icon.
2. The Insights panel opens on the right. Depending on what the author published, you may see:
   • Watchlists — saved insights
   • Assistant — the default workbook conversational experience
   • An attached Agent experience — if the author connected an AI Agent to this workbook in the Present tab
3. Use the standard Assistant tab for the default workbook AI experience, or switch to the configured Agent if one is available. In the workbook scenario, the Agent uses the same workbook entry point; consumers do not have to open a separate design screen to use it.

Step 6.3 — Ask Questions as a Consumer

Type these prompts and see the results:

Save Insights to Your Watchlist

1. Hover over any visualization generated by the Assistant
2. Click ☆ Add to Watchlist
3. Switch to the Watchlists tab to see your saved insights
4. These also appear on your OAC Home page for quick access

Build a Complete Dashboard from a Single Prompt

1. Navigate to the OAC Home page.
2. Click the Search bar at the top.
3. Type a single data-related question and press Shift + Enter to have the Homepage AI Assistant build a visualization or dashboard:

Refine with Follow-Up Questions

The Homepage AI maintains conversational context. After the initial dashboard is generated, type a follow-up question in the same prompt bar and press Enter — the existing visualizations update in place.

Explore or Modify Your Results

From the generated dashboard you have two main levers to reshape the output:

• Click Data (next to the dataset or subject-area name) to point the same question at a different dataset or subject area.
• Click Explore as Workbook to open the visualization in a new workbook — from there you can edit, rearrange, add charts, and continue in the Workbook AI Assistant.

Deep-dive in the Workbook AI Assistant

Once the dashboard is open as a workbook:

1. The workbook opens in Visualize mode — you can now edit, rearrange, and add your own visualizations.
2. Click the ✨ Sparkle icon (top-right) to open the AI Assistant panel.
3. Now ask dataset-specific questions just like in Lab 3:

4. If an AI Agent has been attached to this workbook (Lab 4), the Agent’s business rules and knowledge documents will automatically enhance every response.