Skip to main content

Deep Dive: Knowledge Base & Human Approval

Calculating read time…

You are about to learn two of the most powerful, most misunderstood, and most enterprise-critical features inside Oracle Integration Cloud Generation 3. Together, Knowledge Base and Human Approval are what transform an OIC AI Agent from a clever chatbot into a trustworthy, enterprise-grade autonomous system that your CFO, CISO, and Compliance team will actually sign off on.

By the end of this guide, you will understand not just what these features are, but why they exist, how to build them from scratch, and how to deploy them safely into production — with zero prior experience required.

🎯 What You Will Build in This Guide:

A real Oracle Fusion HCM use case — an AI-powered Employee Onboarding Agent that:
① Answers policy questions from a Knowledge Base (HR policies, offer letters, benefits docs)
② Requests manager and HR approval before creating the employee record in Fusion HCM
③ Routes exceptions to senior HR when approval is delayed beyond SLA
④ Logs every decision for audit and compliance

📋 What This Complete Guide Covers

📚
Knowledge Base
What it is & why
👤
Human Approval
Gates & workflows
🔧
Step-by-Step Build
Zero to working
🏗️
Architecture
Diagrams & flows
🚨
Mistakes & Fixes
Common pitfalls
🚀
Prod Readiness
Deploy safely
🎓
Interview Prep
Architect Q&A

📚 Part 1: Knowledge Base in Integration Cloud — From Zero to Expert

1.1 What Is a Knowledge Base? (Explain Like I'm a Beginner)

Imagine you hire a brilliant new employee. They are incredibly smart. But on day one, they know nothing about your company — your HR policies, your approval thresholds, your leave rules, your procurement processes. Before they can answer a single internal question correctly, they need to read your company's documents.

That is exactly the problem with an AI Agent in Integration Cloud. The underlying LLM (Large Language Model — think of it as the AI brain) is trained on public internet data up to a certain date. It is brilliant at reasoning and language. But it knows nothing about your Oracle Fusion implementation, your company's custom approval workflows, your leave policies, or your business unit rules.

A Knowledge Base in Integration Cloud is the solution. It is a curated library of your company's documents — stored, indexed, and made searchable by the AI Agent so that every answer it gives is grounded in your actual policies, not generic guesses.

💡 The One-Line Definition:
A Knowledge Base in Integration Cloud is a searchable, AI-indexed collection of your company's documents that the Agent queries at runtime to give accurate, policy-grounded answers — instead of hallucinating.

1.2 Why Do Enterprises Need It? The Real Business Problem

😰 Without Knowledge Base
Employee asks agent: "What is our maternity leave policy?"

Agent replies with a generic answer based on Indian labour law from its training data.

But your company has a custom 26-week policy with top-up pay.
Agent gave a wrong answer. HR gets flooded with escalations. Compliance risk.
✅ With Knowledge Base
Employee asks the same question.

Agent searches the Knowledge Base → finds your official HR Policy PDF → reads section 4.2 Maternity Leave.

Agent replies with your exact 26-week policy, cites the document, and offers to initiate the leave request.
Accurate. Grounded. Auditable.

🏢 5 Enterprise Scenarios Where Knowledge Base Is Non-Negotiable

👥
HCM — HR Policy Engine: Employees ask about leave, benefits, grade pay, performance rating policies. Agent answers from your HR Policy Manual, Employee Handbook, and Grade Structure documents — not generic law.
💰
Finance — Approval Threshold Lookup: Agent needs to know: "Can a department head approve a ₹45L purchase order?" Answer must come from your Delegation of Authority (DoA) document — not the LLM's guess.
📦
SCM/Procurement — Supplier Policy Checks: Before creating a PO, agent checks if supplier is on the approved vendor list, which is stored as a document in the Knowledge Base.
⚖️
Compliance — Regulatory Lookups: Agent checks your compliance policies before triggering any financial transaction. All regulatory guidelines stored in Knowledge Base.
🔧
IT/OIC Support — Integration Runbook: Agent answers "How do I reprocess a failed integration?" from your OIC runbook PDFs stored in the Knowledge Base.

1.3 Where Does Knowledge Base Fit in Integration Cloud Architecture?

Integration Cloud introduced a component called Oracle AI Agent Studio. Think of Agent Studio as the "brain builder" — it is where you define what your AI Agent knows, what it can do, and what rules it must follow. The Knowledge Base is one of the four pillars of an OIC AI Agent.

🏗️ Integration Cloud AI Agent — 4 Pillars (Where KB Sits)

📚
Knowledge Base
What the agent KNOWS
← YOU ARE HERE
🔧
Tools
What the agent CAN DO
OIC Integrations as APIs
📝
Prompt Template
How the agent THINKS
System instructions & persona
👤
Human Approval
What needs HUMAN sign-off
← Part 2 of this guide

1.4 How Knowledge Base Works Internally — The RAG Engine

Under the hood, Integration Cloud's Knowledge Base uses a technique called RAG — Retrieval Augmented Generation. You do not need to understand all the technical details to use it, but knowing the basics will make you a better architect.

🔄 How RAG Works Inside Integration Cloud Knowledge Base (Simplified)

SETUP PHASE (You do this once): You upload your HR Policy PDF, Benefits Guide, Org Chart etc. into OIC Knowledge Base.
⬇️
INDEXING (OIC does this automatically): OCI GenAI Embedding Model reads every document. Converts each paragraph into a vector (a list of numbers representing meaning). Stores these in OCI OpenSearch vector database. Think: library cataloguing every book's ideas — not just words.
⬇️
RUNTIME RETRIEVAL (Every user question): User asks "What is our maternity leave duration?" → OIC converts question to vector → searches Knowledge Base for most similar content → retrieves top 5 most relevant paragraphs.
⬇️
GENERATION (LLM does this): OCI GenAI LLM receives: User question + Retrieved policy paragraphs → Generates answer grounded in your actual documents. Cites sources. Does NOT hallucinate.
⬇️
RESPONSE TO USER: "Per Section 4.2 of the ABC Corp HR Policy (updated Jan 2025), maternity leave is 26 weeks at full pay, followed by optional 12 weeks unpaid. Would you like me to initiate a leave request?" ✅

1.5 Step-by-Step: Creating a Knowledge Base in Integration Cloud

💡 Business Scenario for This Guide: You are building an HR Onboarding Agent for ABC Corp. The agent must answer questions about HR policies (from your Knowledge Base) and must get manager + HR approval before creating an employee record in Oracle Fusion HCM.

📋 STEP 1 — Prepare Your Documents (Pre-Requisite)

1a. Collect all relevant documents
For HR Knowledge Base, gather: HR Policy Manual (PDF), Benefits Guide (PDF), Leave Policy (PDF), Grade and Pay Structure (Excel exported to PDF), Onboarding Checklist (Word/PDF), Company Organisation Chart (PDF). All must be in PDF, DOCX, TXT, or HTML format.
1b. Clean your documents before upload
Remove scanned images without OCR text — the KB cannot read image-only PDFs. Remove confidential salary data if the agent should not access it. Add headers to each section — good structure = better retrieval. Ensure all documents are UTF-8 encoded.
⚠️ Best Practice: Keep each document focused. A 200-page HR manual split into 10 focused PDFs (Leave Policy, Benefits, Grievance, etc.) retrieves 10× more accurately than one massive file. The KB retrieves by relevance, not by page number.

📋 STEP 2 — Navigate to OIC Agent Studio and Create the Knowledge Base

1
Log into Integration Cloud Console. Navigate to: Design → Projects. Open your project (or create one: + Create → Project → Name: "HR_Onboarding_Agent").
2
Inside your project, click + Add. From the dropdown, select "Knowledge Base". You will see the Knowledge Base creation wizard open.
3
Fill in the Knowledge Base details:
Name: HR_Policy_KB
Description: ABC Corp HR Policies, Leave Rules, Benefits Guide, and Onboarding Procedures
Embedding Model: Select OCI Generative AI — cohere.embed-multilingual-v3.0 (supports English + regional languages)
Storage: OCI Object Storage bucket (OIC creates this automatically if you have the right IAM policy)
4
Click Create. The Knowledge Base is now created but empty. You will see a status of "Not Indexed".

📋 STEP 3 — Upload Documents and Trigger Indexing

1
Inside your newly created HR_Policy_KB, click "Upload Documents" or "+ Add Data Source".
2
You have two upload options:
Option A — Direct Upload: Drag and drop PDF/DOCX files directly into the UI. Good for small collections (<50 docs).
Option B — OCI Object Storage: Point to an OCI bucket path where your documents live. Best for large collections and automated refresh.
3
For our HR use case, upload these files:
ABC_Corp_HR_Policy_Jan2025.pdf — Main HR policy
Leave_Policy_Detailed.pdf — All leave types
Employee_Benefits_Guide_2025.pdf — Insurance, PF, Gratuity
Onboarding_Checklist_Template.pdf — Day 1 steps
Grade_Pay_Structure_FY25.pdf — Bands and CTC ranges
4
After uploading, click "Start Ingestion" or "Index Documents". OIC will now:
→ Extract text from each document
→ Split into 512-token chunks (configurable)
→ Call OCI GenAI Embedding API for each chunk
→ Store all vectors in OCI OpenSearch
Status will show: Indexing → Indexed ✅
⏱️ Time to Index: A 100-page PDF takes approximately 2–5 minutes. Large collections (500+ docs) can take 30–60 minutes. Schedule initial ingestion overnight. Set up OCI Object Storage event triggers for automatic re-indexing when documents change.

📋 STEP 4 — Configure Knowledge Base Retrieval Settings

⚙️ Setting What It Controls Recommended Value Why
Top K Results How many document chunks to retrieve per query 5 3 = too narrow, 10 = too much context noise
Similarity Threshold Minimum relevance score to include a chunk 0.7 Below 0.7 = too loosely related content
Chunk Size Token size per indexed chunk 512 tokens Balances context richness vs retrieval precision
Chunk Overlap Tokens shared between adjacent chunks 50 tokens Prevents policy statements from being cut mid-sentence
Citation Mode Whether agent includes source document references ENABLED Critical for enterprise audit and user trust

📋 STEP 5 — Attach Knowledge Base to Your AI Agent

1
In your OIC Project, click + Add → Agent. Name it: HR_Onboarding_Agent.
2
In the Agent configuration panel, find the "Knowledge Sources" section. Click "+ Add Knowledge Base". Select HR_Policy_KB from the dropdown. Save.
3
In System Prompt (we cover this fully in Part 2), add these instructions:
"Always search the Knowledge Base before answering any HR policy question. Always cite the source document and section. If the Knowledge Base does not contain the answer, say so — do not guess."
4
Test the Knowledge Base connection: In the Agent Studio test panel, type "What is the paternity leave policy at ABC Corp?". If Knowledge Base is correctly attached, the agent will return a cited answer from your uploaded documents.

1.6 Architecture Diagram — Knowledge Base in the Full Agent Flow

┌─────────────────────────────────────────────────────────────────┐
│              Integration Cloud — HR Onboarding Agent Architecture         │
│                    (Knowledge Base Focus)                        │
└─────────────────────────────────────────────────────────────────┘

  👤 Employee / HR Manager
        │  "What is our maternity leave policy?"
        │  "Can I onboard Priya Sharma to Grade 5?"
        ▼
  ┌─────────────────────────────┐
  │   OIC REST Trigger Endpoint  │  ← Entry point (exposed as REST API)
  └──────────────┬──────────────┘
                 │
                 ▼
  ┌─────────────────────────────────────────────────────┐
  │              HR_Onboarding_Agent (OIC Agent Studio)  │
  │                                                     │
  │  ┌──────────────┐   ┌──────────────────────────┐   │
  │  │ Prompt       │   │  ReAct Loop Controller   │   │
  │  │ Template     │   │  Think → Act → Observe   │   │
  │  │ (System      │   │  → Adapt → Repeat        │   │
  │  │  Prompt)     │   └──────────┬───────────────┘   │
  │  └──────────────┘              │                   │
  │                                │ Tool calls         │
  └───────────────────────┬────────┘────────────────────┘
                          │
           ┌──────────────┼──────────────────┐
           │              │                  │
           ▼              ▼                  ▼
  ┌──────────────┐ ┌──────────────┐  ┌──────────────────┐
  │  📚 Knowledge│ │  🔧 OIC Tool │  │  👤 Human        │
  │  Base        │ │  Integration │  │  Approval Gate   │
  │              │ │  (Fusion HCM)│  │  (Part 2)        │
  │ HR_Policy_KB │ │              │  │                  │
  │  ├─ Policies │ │ create_emp() │  │ manager_approve()│
  │  ├─ Benefits │ │ get_grade()  │  │ hr_approve()     │
  │  ├─ Leave    │ │ check_org()  │  │                  │
  │  └─ Grades   │ │              │  │                  │
  └──────┬───────┘ └──────┬───────┘  └────────┬─────────┘
         │                │                    │
         ▼                ▼                    ▼
  ┌─────────────┐  ┌─────────────┐    ┌───────────────┐
  │OCI OpenSearch│  │Oracle Fusion│    │ OIC Approver  │
  │Vector Store │  │  HCM REST   │    │ Notification  │
  │(RAG Engine) │  │  APIs       │    │  (Email/Teams)│
  └─────────────┘  └─────────────┘    └───────────────┘
         │
         ▼
  ┌─────────────────────────────┐
  │ OCI GenAI Embedding Model   │
  │ cohere.embed-multilingual   │
  │ Converts queries ↔ vectors  │
  └─────────────────────────────┘

👤 Part 2: Human Approval in Integration Cloud — The Enterprise Safety Net

2.1 What Is Human Approval? (The Simplest Explanation)

Imagine you build an AI Agent so capable that it can create an employee record in Oracle Fusion HCM, set their salary, assign their grade, and send their offer letter — all autonomously. Sounds impressive. Now imagine the agent makes a mistake — wrong salary band, wrong grade, wrong start date — and creates the record before anyone could catch it. Payroll runs. Employee is paid wrong amount. Compliance nightmare.

Human Approval in Integration Cloud is the architectural mechanism that pauses the agent before any high-stakes, irreversible action and requires a human to explicitly approve or reject before the agent proceeds. The agent stops. Waits. A notification goes to the approver. They review. They decide. The agent resumes — or stops — based on that human decision.

💡 The Golden Rule of Enterprise AI:
"The AI can recommend. The AI can prepare. The AI can validate. But certain actions in Oracle Fusion — financial postings, employee creation, supplier approvals, payment releases — must always have a human checkpoint before execution."

Human Approval is how you build that checkpoint into the architecture — not just as a prompt instruction (which LLMs can bypass), but as a hard structural gate that the agent literally cannot pass without a human decision.

2.2 Why Enterprises Cannot Skip Human Approval

⚖️ SOX Compliance
Sarbanes-Oxley requires documented human authorization for financial transactions and employee data changes. An autonomous AI agent without a human gate is a SOX violation by design.
🚨 Hallucination Risk
LLMs can be confidently wrong. If an agent miscalculates a CTC and creates an HCM record — it is in the system. Reversing it is a multi-department fire drill. Human approval catches errors before they land.
🔒 Data Privacy
Employee personal data, salary information, and grade assignments are confidential. GDPR, IT Act 2000, and most enterprise policies require that access and modification is authorized by a human, not a bot.
📋 Audit Trail
Every Oracle Fusion transaction must be traceable to a named human. "The AI did it" is not an acceptable audit response. Human Approval captures WHO approved, WHEN, and WHY — stored permanently in OCI Audit.

2.3 Human Approval Architecture — How It Works in Integration Cloud

In Integration Cloud, Human Approval is implemented using the OIC Human Task Integration Pattern. When the agent decides it needs approval, it calls a special OIC integration that triggers a Human Task. Execution pauses. The task is assigned to an approver. The approver acts. OIC resumes the agent.

🔄 Human Approval — Step-by-Step Internal Flow

① AGENT DECIDES: "I have validated all details for new hire Priya Sharma. CTC ₹18L, Grade 5, Start Date 1 July. I need manager + HR approval before creating the HCM record."
⬇️
② AGENT CALLS APPROVAL TOOL: Agent calls OIC tool: request_manager_approval(employee_details, reason)
⬇️
③ OIC CREATES HUMAN TASK: The OIC integration behind the approval tool creates a structured Human Task with all employee details. Sends notification email to Hiring Manager. Agent execution PAUSES here.
⬇️
④ HUMAN REVIEWS: Hiring Manager receives email: "Your approval is required for onboarding Priya Sharma (₹18L, Grade 5). Click here to approve or reject with comments." Manager opens OIC Workspace or approves via email link.
⬇️
⑤ ESCALATION (If no response in 24h): OIC escalation rule fires automatically. Task reassigned to Senior HR Manager. Agent still paused. SLA breach logged.
⬇️
⑥ HUMAN DECIDES — APPROVED: Manager clicks Approve + adds comment "Approved — please ensure laptop is ready on Day 1." OIC records: WHO (ravi.kumar@abc.com), WHEN (2025-07-01 14:32 IST), WHAT (Approved Priya Sharma onboarding).
⬇️
⑦ AGENT RESUMES: Agent receives APPROVED signal. Proceeds to call Fusion HCM API to create employee record. Sends confirmation to HR. Logs complete audit trail. ✅
⬇️ (OR)
⑦ AGENT STOPS (If REJECTED): Agent receives REJECTED signal + reason "Grade 5 not approved — budget freeze on senior hires." Agent notifies HR Recruiter with rejection reason. No HCM record created. Clean stop. ❌

2.4 Step-by-Step Implementation of Human Approval in Integration Cloud

💡 Architecture Decision First: In Integration Cloud, Human Approval is implemented as a two-part pattern:
(A) An OIC Integration with a Human Task node — this IS the approval workflow.
(B) A Tool registered with the AI Agent that calls this integration.
The Agent calls the Tool. The Tool triggers the Integration. The Integration pauses for human input. The Integration resumes. The Tool returns the decision. The Agent acts.

🔧 STEP A — Create the Approval OIC Integration (The Human Task Flow)

1
Create a new Integration:
In OIC Design → Integrations → + Create → "Orchestration" style (not App-Driven or Scheduled).
Name: HR_Employee_Approval_Flow
Trigger: REST Trigger — this is what the Agent Tool will call.
Method: POST | Path: /request-approval
2
Define the REST request body schema:
{
  "employee_name": "Priya Sharma",
  "employee_id_proposed": "EMP_NEW_001",
  "grade": "5",
  "ctc_annual_lpa": 18,
  "department": "Technology",
  "hiring_manager_email": "ravi.kumar@abc.com",
  "hr_email": "hr@abc.com",
  "start_date": "2025-07-01",
  "justification": "Approved in Q1 headcount plan"
}
3
Add a Human Approval Task node to the Orchestration:
In the Integration canvas, after the REST trigger, drag in a "Human Approval" activity (found in the Activity Palette under Process Activities or from the OIC Process automation actions).
In Integration Cloud, this is configured as: Process → Human Task → Assign.
Name the task: Manager_Approval_Task
4
Configure the Human Task node — Assignment Rules:
Primary Assignee: Use expression: ${requestBody.hiring_manager_email}
Task Title: "Approval Required: Onboard " + employee_name + " at ₹" + ctc + "L"
Task Priority: HIGH
Due Date (SLA): 24 hours from task creation
Escalation After SLA: Reassign to ${requestBody.hr_email}
5
Configure Notification Email Template:
In the Human Task configuration, open Notification Settings.
Set Subject: [ACTION REQUIRED] Approve onboarding of {employee_name} — {department}
Set Body to include: Employee details table, Approve link, Reject link, Comment field.
OIC auto-generates the Approve/Reject links — you just configure the template.
6
Add a Switch/Gateway after the Human Task node:
After the Human Task completes, add a Switch Activity with two branches:
Branch A: Condition: task.outcome == "APPROVED" → Call Fusion HCM Create Employee API → Return success response
Branch B: Condition: task.outcome == "REJECTED" → Skip HCM call → Return rejection with reason
7
Configure Fusion HCM Invoke (Branch A — Approved path):
Add an Invoke Activity using the Oracle HCM Cloud Adapter.
Operation: Worker → Create → createWorker
Map fields: employee_name → WorkerName, grade → GradeCode, start_date → DateStart, department → BusinessUnitId
This is the actual Fusion HCM REST API call that creates the employee record.
8
Define the REST response schema:
{
  "approval_status": "APPROVED",
  "approved_by": "ravi.kumar@abc.com",
  "approval_timestamp": "2025-07-01T14:32:00+05:30",
  "hcm_worker_id": "WRK_20250701_001",
  "comments": "Approved — laptop ready on Day 1"
}
Activate and deploy the integration.

🔧 STEP B — Register the Approval Integration as an Agent Tool

1
In your Agent Studio → HR_Onboarding_Agent → Tools section → click "+ Add Tool".
2
Configure the tool:
Tool Name: request_employee_onboarding_approval
Tool Type: OIC Integration
Integration: Select HR_Employee_Approval_Flow (the one you just built)
Classification: WRITE-IRREVERSIBLE ← Critical: this creates an HCM record
3
Write the tool description (critical — the LLM reads this to decide when to call this tool):
"Submits a new employee onboarding request to the hiring manager and HR for approval via Oracle Fusion HCM workflow. Call this tool ONLY after you have: (1) verified all employee details from the user, (2) confirmed the grade is within the approved headcount plan, (3) confirmed the CTC is within grade band from the Knowledge Base. This tool triggers a human approval workflow that pauses execution until manager approves or rejects. Returns approval_status, approved_by, and hcm_worker_id on success."
4
In your Agent System Prompt, add this instruction about when to use Human Approval:
"Before calling request_employee_onboarding_approval, you MUST have collected: employee_name, proposed_grade, ctc_annual_lpa, department, start_date, and hiring_manager_email. Confirm all details with the user before submitting. Never assume grade or CTC — always verify from user input or Knowledge Base grade bands."

2.5 Complete Sequence Diagram — Full Runtime Flow

SEQUENCE DIAGRAM — HR Onboarding Agent (KB + Human Approval)
═══════════════════════════════════════════════════════════════

User        Agent       KB          Tool         Integration    HCM          Manager
  │            │          │            │               │            │             │
  │ "Onboard   │          │            │               │            │             │
  │  Priya     │          │            │               │            │             │
  │  Sharma"   │          │            │               │            │             │
  │──────────►│          │            │               │            │             │
  │            │          │            │               │            │             │
  │            │ THINK:   │            │               │            │             │
  │            │ Need her │            │               │            │             │
  │            │ grade    │            │               │            │             │
  │            │ band     │            │               │            │             │
  │            │ from KB  │            │               │            │             │
  │            │─────────►│            │               │            │             │
  │            │          │ Search:    │               │            │             │
  │            │          │ "Grade 5   │               │            │             │
  │            │          │  CTC band" │               │            │             │
  │            │          │            │               │            │             │
  │            │◄─────────│            │               │            │             │
  │            │ "Grade 5: │           │               │            │             │
  │            │  ₹15-20L" │           │               │            │             │
  │            │          │            │               │            │             │
  │            │ ACT:     │            │               │            │             │
  │            │ Confirm  │            │               │            │             │
  │            │ with user│            │               │            │             │
  │◄───────────│          │            │               │            │             │
  │ "Please    │          │            │               │            │             │
  │  confirm:  │          │            │               │            │             │
  │  Priya,    │          │            │               │            │             │
  │  Grade 5,  │          │            │               │            │             │
  │  ₹18L,     │          │            │               │            │             │
  │  1 Jul?"   │          │            │               │            │             │
  │──────────►│          │            │               │            │             │
  │ "Yes,      │          │            │               │            │             │
  │  confirmed"│          │            │               │            │             │
  │            │          │            │               │            │             │
  │            │ ACT:     │            │               │            │             │
  │            │ Call     │            │               │            │             │
  │            │ approval │            │               │            │             │
  │            │ tool ────┼──────────►│               │            │             │
  │            │          │            │ POST /request-│            │             │
  │            │          │            │ approval      │            │             │
  │            │          │            │───────────────►            │             │
  │            │          │            │               │ Create     │             │
  │            │          │            │               │ Human Task │             │
  │            │          │            │               │ Send email │             │
  │            │          │            │               │────────────┼────────────►│
  │            │ ⏸ PAUSE  │            │               │            │ Email:      │
  │            │ Waiting  │            │               │            │ "Approve    │
  │            │ for human│            │               │            │  Priya?"    │
  │            │          │            │               │            │             │
  │            │          │            │               │            │  [Review]   │
  │            │          │            │               │            │  [APPROVE]  │
  │            │          │            │               │            │  ────────►  │
  │            │          │            │               │◄───────────┼─────────────│
  │            │          │            │               │ APPROVED   │             │
  │            │          │            │               │ by manager │             │
  │            │          │            │               │            │             │
  │            │          │            │               │ createWorker()           │
  │            │          │            │               │───────────►│             │
  │            │          │            │               │            │ WRK_001     │
  │            │          │            │◄──────────────│            │◄────────────│
  │            │          │            │ {status:APPROVED,          │             │
  │            │          │            │  worker_id:WRK_001}        │             │
  │            │◄─────────┼────────────│               │            │             │
  │            │ OBSERVE: │            │               │            │             │
  │            │ Approved!│            │               │            │             │
  │            │ HCM rec  │            │               │            │             │
  │            │ created  │            │               │            │             │
  │◄───────────│          │            │               │            │             │
  │ "✅ Priya  │          │            │               │            │             │
  │  onboarded │          │            │               │            │             │
  │  WRK_001   │          │            │               │            │             │
  │  Manager   │          │            │               │            │             │
  │  approved" │          │            │               │            │             │

📝 Part 3: Prompt Template — The Agent's Brain Configuration

The Prompt Template (also called the System Prompt) is the set of instructions you give the Agent that controls its personality, scope, decision-making rules, and output format. Think of it as the agent's job description, training manual, and rules of engagement — all in one.

📝 Complete System Prompt for HR_Onboarding_Agent

## IDENTITY
You are the ABC Corp HR Onboarding Agent, an AI specialist for Oracle Fusion 
HCM employee onboarding. You assist HR Recruiters and Hiring Managers with 
policy questions and employee record creation.

## YOUR KNOWLEDGE SOURCES
You have access to the ABC Corp HR Knowledge Base containing:
- HR Policy Manual (Jan 2025)
- Leave Policy (All types)
- Employee Benefits Guide FY25
- Grade and Pay Structure FY25
- Onboarding Checklist

ALWAYS search the Knowledge Base before answering any policy question.
ALWAYS cite the source document and section number in your answer.
If the Knowledge Base does not contain the answer, say: "I don't have 
that policy in my knowledge base — please contact HR at hr@abc.com."

## YOUR TOOLS
1. search_hr_knowledge_base — Use for any policy question
2. get_approved_headcount — Use to verify if position is in budget
3. validate_grade_salary_band — Use to confirm CTC is within grade band
4. request_employee_onboarding_approval — Use ONLY after full validation

## APPROVAL RULES (NON-NEGOTIABLE)
You MUST call request_employee_onboarding_approval for EVERY new hire.
Never create an HCM record without going through approval.
Before calling the approval tool, you MUST have confirmed:
✓ Employee full name (as in passport/Aadhar)
✓ Proposed Grade (check against headcount plan)
✓ Annual CTC in LPA (verify within grade band from KB)
✓ Department and Reporting Manager name + email
✓ Proposed start date (minimum 2 weeks from today)
Always confirm all details with the user in ONE summary message 
before calling the approval tool.

## WHAT YOU MUST NOT DO
❌ Never reveal another employee's salary or grade
❌ Never approve or reject a hire yourself — always go through the tool
❌ Never answer questions about Payroll, Tax, or Finance — redirect to 
    Finance team ❌ Never guess a policy — only answer from Knowledge Base ## OUTPUT FORMAT For policy answers: Answer + Source document + Section + Offer to
initiate action For approval submissions: Confirm summary → Submit → Report outcome clearly Always be professional, concise, and empathetic.

🚨 Part 4: Common Mistakes and How to Avoid Them

❌ Mistake 1 — Uploading Poor Quality Documents to Knowledge Base

Problem: Scanned PDFs without OCR, documents with tables as images, Excel files with merged cells converted to PDF — the KB cannot extract meaningful text from these.
Fix: Always test document quality BEFORE bulk upload. Open each PDF → Select All → Copy → Paste in Notepad. If you see readable text, the KB can index it. If you see nothing, run OCR first (Adobe Acrobat or Oracle Document Understanding). Convert Excel tables to formatted text PDFs.

❌ Mistake 2 — Writing Vague Tool Descriptions

Problem: Tool description says "Gets invoice data." LLM doesn't know when to call it, when not to, what parameters are needed, or what the response looks like. Agent either never calls it or calls it at wrong times.
Fix: Follow the formula: [Action verb] + [Oracle object] + [Oracle module] + [Required parameters] + [When to call] + [When NOT to call] + [What it returns]. Invest 30 minutes on each tool description. This is the highest-ROI activity in Agent development.

❌ Mistake 3 — Using Only System Prompt as Guardrail (No Architecture Gate)

Problem: System prompt says "Never post a GL journal without CFO approval." Clever prompt injection in input data overrides this. Agent posts the journal anyway.
Fix: For every WRITE-IRREVERSIBLE action, the Human Approval must be enforced at the OIC Integration level — not just as a prompt instruction. The OIC integration physically pauses execution and waits for a human task completion. This cannot be bypassed by the LLM.

❌ Mistake 4 — No Escalation Path in Human Approval

Problem: Approval task sent to manager. Manager is on vacation. No response in 3 days. Agent is stuck forever. Integration times out. HR doesn't know what happened.
Fix: Always configure SLA + Escalation in the Human Task. Set a 24-hour SLA for Tier 1 approver. On SLA breach: escalate to Tier 2 (HR Manager). After 48h total: auto-reject with notification to requester. Always configure a timeout with graceful failure response.

❌ Mistake 5 — Not Refreshing Knowledge Base When Policies Change

Problem: HR updates the leave policy in January. The Knowledge Base still has the old December version. Agent quotes the old policy to employees for 6 months until someone notices.
Fix: Set up an OCI Object Storage Event Rule: when a new document is uploaded to the HR policy bucket → trigger an OIC integration that calls the KB re-ingestion API. Never rely on manual re-indexing for production. Target: Knowledge Base freshness within 24 hours of policy change.

❌ Mistake 6 — Sending Raw Fusion Data to the LLM Context

Problem: OIC tool returns a full Fusion HCM Worker JSON (50 fields, 8,000 tokens). All of it is dumped into LLM context. Costs spike. Context fills up. Agent performance degrades.
Fix: Add a Response Summarisation Assign Activity in every OIC tool integration. Extract only the 5-8 fields the agent actually needs. The rest is discarded before it ever reaches the LLM context. This reduces per-session token cost by 60-80% on Fusion integrations.


🚀 Part 5: Production Deployment Checklist

✅ Production Readiness Checklist — HR Onboarding Agent

✅
Knowledge Base: All 5 policy documents indexed and verified. Test: ask 20 policy questions manually — expect 90%+ accurate cited answers before go-live.
✅
KB Auto-Refresh: OCI Event Rule configured on HR policy bucket. Tested by uploading a test document and verifying it appears in KB within 24 hours.
✅
Human Approval SLA: 24h Tier 1 (Manager), 48h Tier 2 escalation (HR Manager), auto-reject after 72h with notification. All tested end-to-end in UAT environment.
✅
Secrets in OCI Vault: Fusion HCM credentials, OCI GenAI API key, OCI OpenSearch credentials — all stored in OCI Vault. Zero secrets in OIC flow code or environment variables.
✅
OCI IAM Policies: Agent runs under a dedicated OCI Dynamic Group with least-privilege policies. Cannot access Finance or SCM integrations. Verified by attempting cross-domain tool calls (should 403).
✅
OCI Audit Logging: Every tool call, every approval action, every KB query logged in OCI Audit. Verified 3-way link: Agent Session ID ↔ OIC Tracking Instance ID ↔ Fusion Worker ID.
✅
Rate Limiting: OCI API Gateway rate limits configured: max 50 tool calls per session, max 10 calls/minute per tool. Tested by simulating rapid requests — gateway returns 429.
✅
PII Masking: Employee salary, grade, and personal details masked in OIC logs. Only tokenized values reach LLM context. Verified by checking OCI Logging output — no salary figures in plaintext logs.
✅
Prompt Injection Testing: Tested by submitting employee names/notes containing instruction-override text. OIC XSLT sanitizer strips injection patterns before LLM context injection. Verified with 10 injection test cases.
📊
Observability Dashboard Live: OCI Logging Analytics dashboard showing KB query rate, approval turnaround time, tool error rate, token usage per session, goal completion rate. Reviewed by Platform team before go-live sign-off.

📊 Production Monitoring Targets

Metric Target Alert At Action
KB Answer Accuracy ≥ 92% < 80% Re-index KB, split documents, tune similarity threshold
Approval Turnaround Time < 4 hours (avg) > 20 hours Review escalation rules, send reminders at 12h mark
Token/Session (avg) < 20,000 > 50,000 Add response summarisation in OIC tool integrations
Goal Completion Rate ≥ 88% < 70% Add missing tools, increase max_iterations
Approval Rejection Rate Track trend only Sudden spike >30% Review agent recommendations — likely misaligned KB or grade band

🎓 Part 6: Architect Insights and Interview Questions

6.1 Senior Architect Insights You Won't Find in the Docs

💎 Insight 1 — KB Quality Beats KB Size
Architects often think: "More documents = smarter agent." Wrong. A Knowledge Base with 10 clean, well-structured, focused documents consistently outperforms a KB with 200 poorly formatted, overlapping, or scanned files. Invest in document quality. Split large manuals into topic-specific files. Write clear section headings. The embedding model thinks in topics — make your documents think in topics too.
💎 Insight 2 — Human Approval Is a UX Problem Too
The technical implementation of Human Approval takes 2 hours. Getting humans to actually approve promptly takes months of change management. Approvers must understand what they're approving, trust the agent's recommendation, and have a frictionless approval experience. Design your approval email template as if it were a product. Include summary, risk assessment, one-click approve/reject. Every extra click = slower approvals = angry users = bypassed agent.
💎 Insight 3 — The KB-Approval Bridge Pattern
The most powerful pattern: the agent uses the Knowledge Base to justify the Human Approval request. "I am requesting Grade 5 for Priya per Section 3.1 of the Grade Structure document (attached). Her role matches the Grade 5 criteria on 6 of 7 dimensions." Approvers who receive KB-cited justifications approve 3× faster than those who receive bare requests. KB and Human Approval are not independent — they amplify each other.
💎 Insight 4 — Version Your Knowledge Base
When the HR policy changes in April and an employee claims the agent gave wrong advice in March — you need to prove what the KB contained in March. Store document versions in OCI Object Storage with version history enabled. Tag each ingestion with a timestamp. For regulated industries, this is not optional — it is a compliance requirement.

6.2 Architect-Level Interview Questions

🎤 Interview Questions — Knowledge Base in Integration Cloud

Q1 (Beginner): What is the difference between a Knowledge Base and a database in the context of OIC AI Agents?
Model Answer: A database stores structured data queried by exact values (SQL). A Knowledge Base stores unstructured documents queried by semantic meaning (vector similarity). "Find invoices above ₹10L" = database. "What does our policy say about late payment?" = Knowledge Base. In Integration Cloud, both coexist — the agent uses READ tools for database queries and Knowledge Base search for policy lookups.
Q2 (Mid-level): A user asks the HR agent a policy question. The Knowledge Base returns 5 chunks with similarity scores: 0.82, 0.79, 0.71, 0.65, 0.52. Which chunks should be used and why?
Model Answer: Only the first 3 chunks (0.82, 0.79, 0.71) meet the recommended similarity threshold of 0.70. The 4th chunk (0.65) is borderline — include only if the topic is safety-critical. Exclude the 5th chunk (0.52) as it is too loosely related and would add noise that degrades answer quality. Tune the threshold based on your domain: finance compliance = higher threshold (0.75+), general HR = 0.70 is acceptable.
Q3 (Mid-level): Why is Human Approval implemented as an OIC Integration with a Human Task node rather than just a prompt instruction?
Model Answer: Prompt instructions operate at the language level — they can be overridden by prompt injection, adversarial inputs, or LLM drift. An OIC Human Task node operates at the architecture level — it physically halts integration execution, creates an audited task record, and only proceeds on explicit human database confirmation. The LLM cannot bypass an architecture-level gate regardless of what it's told. For SOX, GDPR, and enterprise compliance, architecture-level enforcement is non-negotiable.
Q4 (Senior/Architect): Design a Knowledge Base refresh strategy for an enterprise with 300+ HR and Finance policy documents that change monthly. Include failure handling.
Model Answer: (1) Maintain all policy docs in OCI Object Storage with versioning enabled, organized by domain (HR/, Finance/, SCM/). (2) Configure OCI Events: on ObjectCreated/ObjectUpdated in policy buckets → trigger an OIC integration. (3) The OIC integration calls the OIC KB re-ingestion API for only the changed document (delta ingestion, not full re-index). (4) After ingestion, run a validation step: query the KB with 5 pre-defined golden test questions — if any response degrades below 0.80 similarity vs baseline, send alert to KB admin and roll back to previous version. (5) Log all ingestion events with document name, version, ingestion timestamp, and validation result in OCI Audit.
Q5 (Architect): A new regulation requires that every AI-generated answer given to an employee must be traceable to the exact source document version that was in effect at the time of the query. How do you architect this in Integration Cloud?
Model Answer: (1) When KB returns chunks, capture: chunk_id, source_document_name, document_version, ingestion_timestamp, similarity_score. (2) Log this as a structured JSON record to OCI Logging with the session_id and query_timestamp. (3) In the OIC tool response, include a citations array that the agent includes in its user response. (4) Store the full context (query + retrieved chunks + generated response) in OCI Object Storage under the session_id with an immutable write policy. (5) For audit retrieval: query OCI Logging by date range + employee_id → retrieve session → look up OCI Object Storage for full context including which KB document version was active. This gives you a complete, immutable, point-in-time audit trail for every AI answer.

🎤 Interview Questions — Human Approval in Integration Cloud

Q6 (Beginner): When should an OIC AI Agent use Human Approval vs proceeding autonomously?
Model Answer: Autonomous actions are appropriate for READ operations (query Fusion data, search KB, check status) and WRITE-REVERSIBLE operations (draft creation, flag for review, send notification). Human Approval is mandatory for WRITE-IRREVERSIBLE operations: financial postings, employee record creation, payment approvals, supplier contract actions, or anything that creates a legal or compliance obligation. The classification: "Can this be easily undone in under 5 minutes without regulatory consequences?" If No → Human Approval required.
Q7 (Mid-level): An approval request is stuck because the approver's email is bouncing. How does your architecture handle this?
Model Answer: (1) OIC Human Task is configured with SLA + primary assignee. (2) On SLA breach (24h): OIC escalation rule fires → task reassigned to backup approver group (pulled from configuration, not hardcoded). (3) On 48h total breach: second escalation to HR Director + high-priority alert to OIC monitoring. (4) On 72h: task auto-closes with TIMEOUT status → OIC integration returns timeout response to agent → agent notifies requester with "Approval timed out — HR escalation required." (5) All escalation events are logged with timestamps in OCI Audit. The agent never hangs indefinitely.
Q8 (Senior/Architect): How do you implement multi-level approval (Manager → HR → Finance) for a large purchase request in Integration Cloud?
Model Answer: In the OIC Orchestration integration, chain Human Task nodes sequentially with gateway conditions: (1) Task 1: Requesting Manager approval (SLA: 24h). On APPROVED → proceed to Task 2. On REJECTED → terminate. (2) Task 2: HR Head approval for headcount validation (SLA: 24h). On APPROVED → proceed to Task 3 if amount > ₹50L, else terminate with success. (3) Task 3: Finance Controller approval for budget sign-off (SLA: 48h, weekend-adjusted). Each task captures approver identity, timestamp, comments. The agent calls a single tool "submit_purchase_approval" — OIC handles the multi-level routing internally. The agent receives a final APPROVED/REJECTED/TIMEOUT with complete approval chain metadata.

📌 Quick Reference — Everything in One Place

📚 Knowledge Base — Key Facts
  • Indexed collection of your company documents
  • Uses OCI GenAI Embedding + OCI OpenSearch (RAG)
  • Supports PDF, DOCX, TXT, HTML formats
  • Configure: Top K=5, Threshold=0.7, Chunk=512 tokens
  • Always enable Citation Mode for enterprise use
  • Auto-refresh via OCI Object Storage events
  • Split large docs into focused topic files
👤 Human Approval — Key Facts
  • Required for all WRITE-IRREVERSIBLE actions
  • Implemented as OIC Orchestration + Human Task node
  • Agent tool calls → OIC pauses → human decides → resumes
  • Always configure SLA + Escalation path
  • Approval audit: WHO + WHEN + WHAT stored in OCI Audit
  • Architecture-level gate — cannot be bypassed by LLM
  • Design approval email as a product (UX matters)
🏗️ Architecture Essentials
  • KB + Human Approval amplify each other (cite KB in approval)
  • Always summarise Fusion API responses before LLM context
  • Store KB document versions for audit traceability
  • Never hardcode approver emails — pull from config
  • Test 3-way audit link: Agent ↔ OIC ↔ Fusion
  • PII masking before any LLM context injection
  • Observability dashboard live before go-live
🚨 Never Do These
  • Don't use prompt-only guardrails for financial actions
  • Don't upload scanned image-only PDFs to KB
  • Don't dump raw Fusion JSON into LLM context
  • Don't skip escalation path in Human Task configuration
  • Don't hardcode secrets in OIC flows
  • Don't rely on manual KB refresh in production
  • Don't go live without injection testing
🌱 The Architect's Closing Thought:

Knowledge Base and Human Approval are not features — they are the two pillars that make Oracle AI Agents enterprise-worthy. Knowledge Base ensures the agent is always grounded in your organisation's truth. Human Approval ensures no autonomous AI action creates an unreviewed, unaccountable outcome in your Oracle Fusion system of record.

Build agents that are knowledgeable about your policies. Build agents that are humble enough to ask for human sign-off when the stakes are high. That combination — grounded intelligence plus architectural accountability — is what your CISO, CFO, and Compliance team will actually approve for production.

And that is what separates an AI prototype from an enterprise AI system. ⚙️ 🛡️ 📚 👤

Architect with Purpose. Secure by Design. Observable Always.

Comments