It is 7:04 AM. The CFO of a global manufacturing company — 60,000 employees, 22 countries, Oracle Fusion across Finance, HCM, and SCM — types a single message into the Oracle dashboard chatbot:
By 7:27 AM, the CFO's inbox has a complete, audit-ready close pack — 15 entity summaries, all reconciliations run, all exceptions flagged with root cause, two pending approvals routed to the right controllers, and OCI audit references linked to every Fusion transaction.
No one ran a report. No one wrote a query. No one called a stored procedure.
An AI agent did it — by moving through 7 architectural layers, calling 47 Oracle Fusion API operations, reasoning over the results, and adapting its plan when Entity 7 showed the same intercompany pattern it saw in Q2.
If you want to build systems like that — or design, govern, or defend them in a design review — you need to understand the architecture behind them. Completely. That is what this article delivers.
Every architectural decision in this article is explained with three things: (1) Why this layer exists — the exact problem it solves. (2) What it contains — components and responsibilities. (3) How it connects — what it talks to and why that matters.
🏛️ Section 1: The 7-Layer Oracle Agent Architecture
Think of Oracle Agent Architecture like the OSI networking model — each layer has one job, serves the layer above it, and depends on the layer below it. When layers try to do each other's jobs, the system becomes unmaintainable, insecure, and impossible to audit.
🏛️ Oracle Agent Architecture — 7-Layer Stack
goal enters here
→ Observe → Adapt
Data never leaves OCI.
+ routing to Layer 3
flows = agent tools
Source of truth.
Invisible but absolute.
When an engineer puts authentication logic inside the Agent Orchestration layer, you get two problems: every new agent type must re-implement auth, and auth bugs are distributed across many codebases. When auth lives only in Layer 1, it is tested once, governed centrally, and audited in one place. Separation of concerns is not a preference here — it is what makes the architecture auditable at enterprise scale.
🔬 Section 2: Each Layer — What It Does and Why It Matters
🛡️ Layer 1 — Security & Governance: The Foundation Everything Rests On
Security is Layer 1 — not Layer 7 — because every other layer assumes security is already in place. An agent that cannot prove who is acting, cannot restrict dangerous actions, and cannot produce an audit trail is not an enterprise asset — it is an enterprise liability.
raise_payment_approval(), IAM checks permission before the OIC endpoint is reached.
If the agent lacks the right policy → rejected at Layer 1 — Fusion never even sees the request.
💡 The Most Critical Pattern — Identity Propagation Through All 7 Layers
When Priya (Finance Controller) asks the agent to process invoices, her identity must travel all the way to the Fusion GL posting. Otherwise the posting shows "agent_service_account" — which fails SOX audit. Here is how identity flows through every layer:
{user:"priya@company.com", role:"finance_controller"}
X-Initiated-By: priya@company.com to every Fusion REST call.
🔧 Layer 3 — OIC Integration Fabric: Your Tools Are Already Built
This is the layer that makes Oracle Agent Architecture uniquely valuable for every OIC developer. Every OIC integration you have ever built is already a potential agent tool. OIC serves six distinct roles in the agent stack — none of which can be safely skipped.
| 🔧 OIC Role in Agent Stack | What It Does | Why It Cannot Be Skipped |
|---|---|---|
| Tool Endpoint Host | Exposes REST triggers that become agent tools | Agent needs clean REST; Fusion needs OAuth, specific headers, Fusion-format payloads — OIC bridges both worlds |
| Response Summariser | XSLT extracts 5 relevant fields from 4,000-token Fusion response → returns 80 tokens to agent | Without this, 4 Fusion calls fill the LLM context window. The agent becomes useless. |
| Retry & Resilience | Fusion 503? OIC retries 1s→2s→4s. Agent never sees the transient failure. | Agent cannot implement retry logic — it just calls a tool and expects a result |
| Identity Propagation | Adds X-Initiated-By header carrying original user identity to all Fusion calls | Required for SOX — every Fusion transaction must carry the human requestor identity |
| Audit Trail | Every OIC instance = tracking record linked to agent session + Fusion transaction ID | Creates the three-way audit link: Agent Trace → OIC Instance → Fusion Record |
| Human Approval Gate | For irreversible actions: OIC pauses, sends BPM approval request, resumes only on approval | The agent literally cannot bypass this — the OIC step will not call Fusion without approval confirmation |
Some teams give agents direct access to Fusion REST APIs, thinking OIC adds unnecessary latency. The result: raw 8,000-token Fusion responses blow up the context window, there is no retry logic, no audit trail, no identity propagation, and no human gate. Every agent-to-Fusion interaction must go through OIC. Always. No exceptions.
🔗 Layer 4 — The MCP Gateway: How Agents Discover and Call Tools
MCP (Model Context Protocol) is the architectural nerve system between the intelligent agent and the tools it uses. Before MCP, connecting an agent to Oracle systems required custom integration code for every API — like every device needing its own charger. MCP is the USB standard for AI tools.
🔗 What Happens on the Wire — MCP Protocol Step by Step
POST /mcp/v1 → {"jsonrpc":"2.0","method":"tools/list","id":"disc-001"}MCP responds with a catalogue of all available tools — names, descriptions, required parameters, examples.
"name": "get_pending_invoices", "description": "Retrieves pending supplier invoices from Oracle Fusion Payables filtered by minimum amount, business unit, and fiscal period. Returns invoice ID, supplier, amount, currency, AP status."The description field is what the LLM uses to select the right tool. This is why tool descriptions are architecture-critical — not just documentation.
{"method":"tools/call","params":{"name":"get_pending_invoices","arguments":{"min_amount":1000000,"business_unit":"IN_CORP","period":"2024-09"}}}
X-Initiated-By: priya@company.com
5. Log to OCI Audit → toolcall_id: TC-2024-08471
6. Forward to OIC → await response
7. Receive 2,800-token Fusion response → summarise to 91 tokens → return to agent
| 🔧 Tool Name | ❌ Bad Description | ✅ Good Description | Impact |
|---|---|---|---|
get_invoices |
"Gets invoices from Oracle" | "Retrieves pending supplier invoices from Oracle Fusion Payables with filters for amount, BU, period, and validation status" | Tool selection: 97% vs 61% accuracy |
raise_workflow |
"Raises a workflow" | "Creates and submits an Oracle BPM approval workflow for invoice exceptions, routing to a named approver with full context and evidence" | Prevents confusion with HCM leave approval tools |
search_policy |
"Searches documents" | "Semantic search across Oracle implementation policies, approval matrices, and compliance rules in OCI OpenSearch RAG index" | Agent uses RAG correctly instead of hallucinating policy |
[Action verb] + [specific Oracle data object] + [Oracle module] + [parameters] + [business purpose]
"Retrieves pending supplier invoices from Oracle Fusion Payables for a specified amount threshold, business unit, and period to support three-way match validation before payment approval."
🧠 Layer 5 — LLM Inference: The Reasoning Engine That Stays Inside OCI
The LLM is the intelligence of the agent — but it is a very specific kind of intelligence. It does not know your Oracle data. It knows how to reason. Everything else comes from the other layers.
- Reads the tool catalogue and understands each tool's purpose
- Parses the goal and generates an execution plan
- Selects the right tool for each plan step
- Generates valid JSON parameters for each tool call
- Reads tool results and understands their business meaning
- Decides whether to continue, adapt, or terminate the loop
- Synthesises a final structured output from all observations
- Call Fusion REST APIs directly — that is OIC's job
- Store persistent data — that is Object Storage's job
- Enforce security — that is IAM's job
- Know your live Oracle data without a tool call
- Be trusted with secrets — all credentials stay in Vault
- Self-grant permissions — all authorisation is pre-configured
| 🧠 OCI GenAI Model | Best Oracle Use Case | Context Window | Latency/Call |
|---|---|---|---|
| Cohere Command R+ | Complex Finance/SCM reasoning, multi-step tasks, 40+ tool catalogue | 128K tokens | 2–5s |
| Meta Llama 3.1 70B | HCM analysis, policy interpretation, report generation | 128K tokens | 1–3s |
| BYOM (Fine-tuned) | Domain-tuned on your Oracle implementation data, specialist compliance agents | Model-dependent | Variable |
🤖 Layer 6 — Agent Orchestration: The Brain Running in Oracle AI Agent Studio
Layer 6 is where the agent's behaviour is defined and executed. Oracle AI Agent Studio is the workbench — the low-code environment for building and deploying agent runtime configurations. Six components work together inside this layer:
🎬 Section 3: Complete Runtime Flow — Quarter-End Close in 23 Seconds
Theory becomes real when you trace a single enterprise goal through all 7 layers. Let us follow the CFO's 7:04 AM message — step by step, timing included.
🎬 Quarter-End Close Agent — Complete 7-Layer Runtime Flow
get_gl_trial_balance(entity=X) calls received simultaneously.
Rate limiter: 15 < 20/min. OK. All 15 authenticated, identity headers added, forwarded to OIC simultaneously.
OCI Audit: TC-2024-03001 through TC-2024-03015, all linked to CFO session AGT-Q3-2024-001.
get_intercompany_transactions() → 2 unapproved postings found → policy search confirms "VP Finance must approve" → BPM workflow queued.
Entity 12: get_received_not_invoiced() → 3 accrual candidates → journal drafts prepared for Controller review.
Entity 4: agent calls run_fx_revaluation() → WRITE-IRREVERSIBLE detected by Guardrail Engine → OIC Human Approval Gate triggered → Teams notification sent to Finance Controller.
🤝 Section 4: Multi-Agent Architecture — When One Agent Is Not Enough
Complex enterprise scenarios require specialised agents working in parallel, coordinated by an orchestrator — like a hospital where specialists work simultaneously under a lead consultant's direction.
🤝 Multi-Agent System — Oracle Supply Chain Crisis Response
Scenario: "Typhoon hits SE Asia — 40% of component supply disrupted. Respond."
find_alt_suppliers · issue_rfq
get_stock · flag_critical_skus
reroute · update_customer_eta
calculate_impact · insurance_claim
🏗️ Section 5: Three Proven Enterprise Architecture Patterns
Pattern 1 — The Sidecar Agent (Augment, Don't Replace OIC)
95% of your invoices match cleanly — OIC handles them deterministically, fast and cheap. 5% have exceptions that need reasoning. A sidecar agent activates only for those 5%.
3-way match check
(OIC handles, no agent needed)
(investigates, reasons, resolves)
95% fast OIC path + 5% intelligent agent path = best performance + best coverage.
Pattern 2 — Scheduled Autonomous Agent
OIC schedules trigger the agent on a recurring basis. The agent runs autonomously, takes pre-approved actions, generates a report — no human needed for routine runs.
| Oracle Use Case | Trigger | Agent Actions | Human Gate? |
|---|---|---|---|
| Daily AP 3-Way Match | OIC Schedule 06:00 | Fetch → Match → Flag → Route BPM | Only for BPM submission (WRITE-IRREVERSIBLE) |
| Weekly HCM Overtime Analysis | OIC Schedule Mon 07:00 | Analyse overtime → Draft manager notifications | Yes — manager approves before sending |
| Monthly GL Reconciliation | OIC Schedule Month-end | Reconcile → Close pack → Flag anomalies | Yes — Controller approves before period close |
Pattern 3 — Event-Driven Agent Trigger
Business events in Fusion trigger agents automatically — no schedule, no human initiation needed. A supplier invoice status changes to EXCEPTION → Fusion Business Event fires → OIC receives event → Agent launches with full context of that invoice.
Invoice → EXCEPTION
Receives Fusion event
With invoice context pre-loaded
Within minutes of event
🚫 Section 6: Common Architecture Mistakes
No retry logic, no XSLT summarisation, no identity propagation, no audit trail, no human gates. Raw 8,000-token Fusion responses consume the context window within 3–4 calls. Every Fusion interaction must go through OIC. Always.
200+ tools in one catalogue overwhelms the LLM's tool selection accuracy. Also creates a security hole where any agent can access any Oracle module. One MCP server per Oracle domain. Assign agents only the MCP servers relevant to their domain.
Returning full Fusion payloads to the agent. After 3–4 tool calls the context window fills, performance degrades, LLM loses focus on the goal, and OCI GenAI costs spike 10–50x. Every OIC tool must summarise Fusion responses to only the fields the agent needs.
Approval thresholds, entity hierarchies, and policy rules written directly into the agent config. When rules change, you redeploy the agent. The agent cannot explain where rules came from — fails audit. Store all business rules in OCI OpenSearch. Agent retrieves them via RAG. Rules are versioned, auditable, and live-updated.
CFO's invoice analysis context leaks into an AP Clerk's next session. Information disclosure vulnerability + corrupted agent reasoning. Partition Object Storage memory by user_id + domain + environment. Never share memory across security domains.
✅ Section 7: Best Practices
Don't create get_invoice_by_id (CRUD). Create get_invoices_pending_3way_match (business event).
Business-event tools are more useful to the LLM (it understands business context) and more secure (return only what is needed for that operation).
SUMMARY (5 fields, ~80 tokens) for initial scan. STANDARD (20 fields, ~300 tokens) for analysis. DETAILED (full payload) only when the agent specifically needs it. Default to SUMMARY — the agent requests more detail if needed. Reduces token usage by 85%.
Agent can autonomously call READ tools. WRITE-REVERSIBLE tools create drafts or flags. WRITE-IRREVERSIBLE tools (GL postings, payments, employee terminations) must go through OIC Human Approval Gate — no exceptions. This is your most critical governance control.
When an OIC integration's response schema changes, agents tested on v1 break silently on v2. Run v1 and v2 in parallel during transitions. Test agents against the new schema in staging before switching production. A tool contract change that breaks an agent mid-quarter-close is a P1 incident.
Standard OIC monitoring is not sufficient. Build: session dashboard (active sessions, iterations, token usage), tool effectiveness metrics (most-called, most-failed, slowest), goal completion rate, and OCI GenAI cost-per-agent-type dashboard. You cannot optimise what you cannot see.
🛡️ Section 8: Security Considerations
| 🛡️ Security Concern | Oracle Enterprise Risk | ✅ Mitigation |
|---|---|---|
| Prompt Injection | Malicious content in a Fusion invoice description tricks the agent into calling unintended tools | Sanitise all tool results in OIC before returning to agent. OCI Content Filter. Input validation at MCP Gateway. |
| Over-Privileged Agent | Agent with GL posting + employee termination + payment approval = catastrophic risk surface | Principle of Least Privilege. Separate agents per domain. OCI IAM role-based tool permissions. |
| Data Leakage via LLM | Fusion payroll, GL, and supplier contract data sent to external public LLM APIs | OCI Generative AI only. All inference within OCI tenancy boundary. Never use public LLM APIs with Fusion data. |
| Missing Identity Trail | Agent GL postings show "service_account" — impossible to trace to human requestor for SOX | Identity propagation through all 7 layers. X-Initiated-By header on every Fusion call. Fails SOX without this. |
| Runaway Tool Calls | Agent enters infinite reasoning loop — hammers Fusion APIs with thousands of calls | max_iterations in agent config. Rate limiting at MCP Gateway. Circuit breaker pattern in OIC. |
⚡ Section 9: Performance & Scalability
When the plan has 15 independent entity queries, they fire simultaneously via async OIC invocation + OCI Queue for response collection. Serial: 15 × 3s = 45s. Parallel: 3s total. 15× performance gain — essential for quarter-end close scenarios.
Deploy Agent Runtime on Oracle Kubernetes Engine with HPA (Horizontal Pod Autoscaler) based on concurrent session count + LLM token throughput. MCP Gateway scales independently. OIC already scales horizontally. Target: 50 concurrent agent sessions without performance degradation.
Cache stable reference data with configurable TTL: Approval hierarchy (24h), Exchange rates (1h), Employee master (4h), GL account structure (12h), Invoice status (TTL=0 — always live). OCI Cache (Redis). Target: 40%+ cache hit rate on reference data queries.
🎉 Final Summary — Oracle Agent Architecture at a Glance
Build with Purpose. Architect with Clarity. Deploy with Confidence. 🏛️
Comments
Post a Comment