A Deep Link in Oracle Fusion AI Agent Studio is a Tool type that lets an AI Agent hand a user off from a chat response straight into a specific Oracle Fusion Cloud page or record — skipping the menu tree entirely. Instead of an agent trying to complete a transaction on the user's behalf, it resolves a parameterized URL (built from a relative path plus live record identifiers) and returns it as a clickable link, so the person lands exactly where they need to be, inside the standard Fusion UI, with their existing role-based security intact. 🔗
📑 In This Post
🔀 Quick Comparison: Deep Link Tool vs. the Other AI Agent Studio Tool Types
| Tool Type | What It Does | Executes the Transaction? | Best For |
|---|---|---|---|
| Deep Link | Returns a URL that navigates the user into a Fusion page or record | No — hands off to the UI | Multi-step or judgment-heavy transactions (approvals, edits, submissions) |
| Business Object Tool | Reads or writes Fusion business objects directly through the agent | Yes — inline, in chat | Simple lookups or single-field updates |
| External REST Tool | Calls a third-party API outside the Fusion estate | Yes — against an external system | Integrating non-Oracle systems into the conversation |
| Email Tool | Sends a notification through the Fusion HCM alert channel | No — informational only | Asynchronous, role-targeted alerts |
1. What a Deep Link Actually Is
Oracle Cloud Applications has supported deep-linked navigation for years, long before AI agents existed — reporting tools, email notifications, and third-party portals have always been able to construct a URL that drops a user onto a specific Fusion page instead of the generic sign-in landing page. The Deep Links work area (Navigator > Tools > Deep Links) is where every one of those pre-built links lives, seeded across product families like HCM, SCM, Procurement, and CX.
AI Agent Studio doesn't invent a new navigation mechanism — it exposes that existing catalog to agents as a first-class Tool Type. When an agent decides a deep link is the right response, it isn't opening the page itself; it's assembling a URL string and handing it to the user as a clickable link. The click, the authentication, the role check, and the transaction itself all still happen through Fusion's normal Redwood UI, under the user's own privileges. This is a deliberate architectural boundary: the agent reasons and routes, the application executes.
✅ Worked example (Oracle HCM, Center of Excellence build): A deep link named COE Add Absences is seeded with the relative URL /fscmUI/redwood/absences/manage-absences/view-add-absences. Its system code is auto-generated as ORA_HCM_ABSENCES_COEADDABSENCES. When an employee tells the Leave and Absence Analyst agent "add PTO from July 1st through July 5th," the agent doesn't file the absence itself — it responds with this deep link, and the employee lands directly in the Redwood absence-submission flow with the request context already understood.
🎯 Use this when...
the action a user needs involves judgment, multi-field input, approval routing, or anything Oracle's own transactional UI already handles well — don't try to replicate that logic inside an agent conversation when a one-click handoff will do the job more safely.
2. The Three-Layer Deep Link Architecture
Every working deep link in AI Agent Studio is really three separate records, built in sequence and bound together. Skipping or misordering any layer is the single most common reason a "finished" deep link never actually appears in a conversation.
Layer 1 — The Deep Link Definition
This is the raw navigation record: a Family, a Product, a unique Name and Code, the target page's relative URL, a Description for administrators, and a user-facing Message the agent will show alongside the link. It has no awareness of AI yet — it's the same kind of record that has always powered Deep Links work area navigation.
Layer 2 — The Tool of Type "Deep Link"
Under the Tools tab, a new Tool is created with Tool Type set to Deep Link. It gets its own Tool Name and Code, is classified by Family and Product, and is then bound to the definition from Layer 1. This is the layer an agent's runtime engine actually understands and can invoke — the definition alone is inert until it's wrapped this way.
Layer 3 — Attachment to the Agent, Governed by the Prompt
On the Agent canvas, the Tools panel is filtered to Tool Type: Deep Link, and the new tool is added to the agent's toolset. But having the tool available isn't the same as the agent using it correctly — that's controlled entirely by the agent's prompt. A production HCM agent's instructions typically contain an explicit routing rule under something like an "Absence Actions" section: when a user's intent matches adding time off, call the specific Deep Link tool by name. Without that instruction, an agent with the tool attached may still answer conversationally and never surface the link.
💡 Contrasting example — a seeded Procurement deep link: Oracle ships a standard tool, ORA_VIEW_PURCHASE_REQUISITION_DETAILS, bound to a deep link that opens a specific requisition record. Its relative URL pattern is /fscmUI/redwood/procurement/requisitions/tabbar/shopping/requisitiondetails?requisitionHeaderId={RequisitionHeaderId}. Notice the curly-brace placeholder — unlike the Absences example above, which routes to a general entry flow, this one requires the agent to substitute a real numeric ID at runtime. Get that substitution wrong (wrong field name, unresolved variable) and the link resolves to a blank or error page even though every layer was configured "correctly."
🎯 Use this when...
you're debugging a deep link that "isn't showing up" — check the layers in order: does the definition resolve on its own when pasted into a browser, does the Tool bind to it correctly, and does the agent's prompt actually instruct a call to that Tool by name for the intents you're testing?
3. Anatomy of a Deep Link URL
Every deep link URL in Oracle Fusion Applications follows a common pattern, documented at the platform level and reused by every module-specific implementation:
https://<pod-name>/fndSetup/faces/deeplink?objType=<objID>&objKey=<name1=value1;name2=value2>&action=<action>&returnApp=<returnAppURL>&returnAppParams=<returnAppParameter>
| Parameter | What It Controls | Example |
|---|---|---|
pod-name |
The environment host name | yourcompany.oraclecloud.com |
objType |
Which work area or object family the link targets | SUPPLIER, CONTRACT |
objKey |
The specific record identifier(s), often multiple name/value pairs | contractId=100293 |
action |
What the user can do once they land — defaults to NONE (overview/search) if omitted | VIEW, CREATE, EDIT |
returnApp / returnAppParams |
Where the user is sent back to once the task is complete | MyOracle, type=photo |
Inside AI Agent Studio specifically, what you enter in the Deep Link definition is only the relative portion — everything after the pod name. The Requisition example from Layer 2 above resolves, once a real record ID is substituted, to a full address like this in a browser:
https://yourcompany.oraclecloud.com/fscmUI/redwood/procurement/requisitions/tabbar/shopping/requisitiondetails?requisitionHeaderId=300000303705247&tabSelected=tab_requisitions
Caption: the pod name is stripped out of the Tool's stored definition — only the path after it is configured, which is what keeps the same deep link portable across Test, UAT, and Production pods.
4. Security, Privileges & Governance
A deep link never bypasses Fusion's role-based access control — it can't. If an agent hands a purchasing clerk a link into a supplier's financial terms page they aren't authorized to view, Fusion still redirects them to a high-level landing page or an access-denied state, exactly as it would if they had typed the URL themselves. This is the single most important security property of the pattern: the AI layer proposes navigation, the existing security model disposes of it.
Three access points govern the pattern administratively:
- Viewing and managing the underlying catalog requires the View Administration Link privilege (
FND_VIEW_ADMIN_LINK_PRIV), scoped to the Deep Links work area under Navigator > Tools. - Enabling AI Agent Studio's broader external-integration surface (including agent-initiated navigation) requires the profile option
ORA_ASE_SAS_INTEGRATION_ENABLEDto be set to Yes, plus the correct permission groups assigned to the roles that will use agents. - The end user's own duty roles determine what the destination page actually shows or allows once they arrive — the deep link Tool's configuration has no ability to elevate that.
💡 Key warning, tied back to the Absences example: Testing COE Add Absences as an HR administrator will always look successful, because administrators typically hold broad access. The link only proves itself once it's tested as the actual target persona — a regular employee with a standard self-service role — because that's the account most likely to hit a privilege gap the admin account never sees.
🎯 Use this when...
signing off on a deep link for production — never approve based on an admin-account test alone; re-test with a representative low-privilege role from each business unit the agent will serve.
5. Beginner Hands-On Lab: Build Your First Deep Link Tool
This lab uses a low-risk, non-transactional target — the My Team overview page — so you can practice the full three-layer pattern without touching anything that submits or approves real data. Work in a Test or Development pod, not Production.
Sign in to your Test pod and open Navigator > Tools > Deep Links. Confirm you can see the seeded list — if the page won't load, you're missing the View Administration Link privilege; ask your security administrator to grant it before continuing.
Navigate to AI Agent Studio > Deep Link and click + Add. Set Family to a family available in your pod (e.g., Common), give it Name Lab My Team View, and paste in a relative URL such as /hcmUI/faces/MyTeam (confirm the exact path for your release by opening the My Team page yourself and copying everything after the pod name from your browser's address bar). Add a Message like "Here's your team overview." Save.
Go to the Tools tab, click + Add, and set Tool Type to Deep Link. Name it Lab My Team Tool, then bind it to the Lab My Team View definition from Step 2. Expect to see: the deep link definition appear as a selectable option in the binding field — if it doesn't, the definition in Step 2 didn't save correctly.
Open a disposable test agent (or clone one you're already experimenting with) on the Agent canvas. In the Tools panel, filter by Tool Type: Deep Link, find Lab My Team Tool, and add it. Then open the agent's prompt and add one line under its instructions, for example: "If the user asks to see their team, use the Lab My Team Tool." Save and publish the agent version to your test environment.
Open the agent in the Playground/Preview panel and type: "show me my team." Expect to see: a conversational reply containing a clickable link with the Message text you set in Step 2. Click it — it should open the My Team page in a new tab, already signed in as you.
💡 Most common first-timer mistake: pasting the full URL — including https://yourpod.oraclecloud.com — into the relative URL field in Step 2. The field expects only the path that comes after the pod name (as shown in the URL Anatomy section above); including the domain produces a malformed link that fails silently or opens a broken page when clicked.
Bridge to production: this lab used a static, parameter-free page on purpose. The COE Add Absences and ORA_VIEW_PURCHASE_REQUISITION_DETAILS examples earlier in this post follow the exact same three-layer pattern — the only difference is that their relative URLs carry a placeholder (like {RequisitionHeaderId}) that the agent fills in dynamically from conversation or business-object context at runtime. Once you're comfortable with the static case, the next skill to practice is wiring a Business Object Tool's output into a Deep Link Tool's parameter.
6. Enterprise Rollout at Scale
A handful of deep links built by one enthusiastic admin doesn't need governance. A catalog of dozens, spanning HCM, Procurement, SCM, and CX, shared across multiple agent teams and business units, absolutely does. Enterprises standardizing on AI Agent Studio typically put four controls in place:
- A named ownership model. Each deep link and its bound Tool has an accountable owner (usually the functional COE for that product family — HCM, Procurement, etc.) responsible for re-validating it every release, since Redwood page paths can shift between quarterly updates.
- Naming and coding conventions. Prefixing custom codes (e.g., a consistent
COE_or department-specific prefix, distinct from Oracle's ownORA_seeded codes) prevents collisions and makes it immediately clear in an audit which links are custom-built versus delivered. - Promotion through environments, not direct edits in Production. New or changed deep links and tools are built and tested in a Development or Test pod first, then migrated forward using the same environment-promotion process the organization already uses for other Fusion configuration — never hand-edited directly against Production.
- Usage and health metrics. AI Agent Studio's monitoring and execution-timeline capabilities let a governance team see which Deep Link tools are actually being invoked, how often, and whether invocations are resolving cleanly — turning "is this agent actually helping people navigate" into a measurable question instead of a guess.
🎯 Use this when...
you're moving from a pilot with two or three agents to a program with dozens — stand up the ownership and naming conventions before the catalog grows past the point where anyone can audit it by memory.
7. Best Practices
- Double-check every identifier before it goes into the URL. A stale or mismatched value — like an old requisition header ID still cached in the conversation — routes the person to the wrong record entirely, which does more damage to trust than sending them nowhere at all.
- Test across roles and environments, not just as an administrator — see the Security section above for why this matters more than it sounds like it should.
- Avoid over-linking. Not every response needs a deep link; reserve them for moments that genuinely reduce navigation friction. An agent that appends a link to every answer trains users to ignore all of them.
- Write the routing instruction explicitly into the prompt rather than assuming the agent will infer when to use a Deep Link Tool from its description alone.
- Re-validate seeded and custom links after every quarterly update, since Redwood page paths are not contractually frozen between releases.
8. Common Mistakes
Pasting the full URL into the relative URL field. The field is designed to hold only the pod-independent path. Including the domain doesn't just look messy — it produces a URL that's wrong for every environment the configuration gets promoted to, because the domain changes between Test and Production but the relative path shouldn't.
Attaching the tool but never updating the prompt. Tool attachment and prompt instruction are two separate configuration surfaces, and it's entirely possible to complete one and forget the other. The agent will look "broken" in testing even though every individual component was configured without error — because nothing is telling it when to reach for the tool.
Treating a deep link as a way to grant access. Some teams build a deep link hoping it will let a user reach a page their role doesn't otherwise permit. It won't — and shouldn't. The correct fix is a role/security change, not a navigation shortcut, because the deep link inherits the destination page's existing access rules by design.
Hard-coding a record ID instead of a parameter placeholder. A deep link built and tested against one specific requisition or contract works perfectly in the demo and then does nothing useful in production, because every real conversation needs a different record. The placeholder syntax exists specifically so the agent can substitute a live value at runtime.
Skipping cross-environment re-testing after a quarterly update. A relative URL that resolved correctly last quarter can silently break after a Redwood UI restructuring. Because deep links fail quietly — often falling back to a generic landing page rather than throwing a visible error — broken links can go unnoticed for weeks unless someone is actively monitoring tool invocation health.
❓ FAQ
Can a Deep Link Tool submit or complete a transaction by itself?
No. A Deep Link Tool only returns a URL; the actual transaction — submission, approval, edit — happens when the user clicks through and completes it inside the standard Fusion UI, under their own security and approval workflow.
Do I need to rebuild deep links separately for Test, UAT, and Production?
No — because deep link definitions store only the relative URL (the path after the pod name), the same definition and Tool can be promoted across environments without editing the URL itself; only the pod name changes automatically based on where it's clicked from.
What privilege do I need just to browse the existing deep link catalog?
The View Administration Link privilege (FND_VIEW_ADMIN_LINK_PRIV) is required to open the Deep Links work area under Navigator > Tools > Deep Links and see what's already been seeded or built.
Why did my deep link work for me but not for a regular employee?
Deep links inherit the destination page's existing role-based security — they cannot grant access a user doesn't already have. If it worked for you as an administrator but fails for a standard employee role, the fix is to review that role's privileges, not the deep link configuration.
Is a Deep Link Tool the same thing as the Redwood Quick Actions panel?
They're related but distinct: Redwood Quick Actions are a UI-level shortcut mechanism inside Fusion pages, while a Deep Link Tool in AI Agent Studio is how an agent programmatically surfaces a navigation URL — which can, in some cases, point at a Redwood Quick Action destination as its target.
🔗 References & Further Reading
Official / Primary Documentation
Oracle, Oracle Fusion Cloud, AI Agent Studio, and Redwood are trademarks of Oracle Corporation and/or its affiliates. This post synthesizes and explains publicly available product behavior in original wording for educational purposes; it does not reproduce source text verbatim and is not official Oracle documentation.
📝 Summary
- A Deep Link Tool hands a user off from AI Agent Studio into a specific Fusion page or record — it navigates, it doesn't transact.
- Every working deep link is three bound records: the Deep Link definition, a Tool of type Deep Link, and an explicit prompt instruction on the Agent.
- The standard URL pattern (pod-name / objType / objKey / action / returnApp) governs every deep link across Fusion, with only the relative path stored inside AI Agent Studio.
- Security is inherited, not granted — deep links respect existing role-based access exactly as if the user typed the URL themselves.
- The beginner lab builds a static, parameter-free My Team link as a safe bridge into parameterized, production-style deep links.
- Enterprise rollout requires ownership, naming conventions, environment promotion, and usage metrics once the catalog grows past a handful of links.
That's the full pattern, from a single seeded link to a governed enterprise catalog. Happy building! 🚀
Comments
Post a Comment