Oracle AI Agent Instructions and Prompts
In Oracle AI Agent Studio, an agent's instructions and prompts are the natural-language text that tells a Fusion agent how to behave — its tone, the steps it follows, when to call a tool, when to ask a human, and what it must never do. Prompts are officially supported configuration on Studio's agent templates. Because they are natural language, a small wording change can shift behaviour in ways that are easy to miss and hard to reproduce — which makes prompt design and testing a first-class governance concern.
This page covers how to write, guardrail, version, and test agent instructions and prompts for Oracle Fusion agents. It sits under the Oracle AI Agent Studio hub and focuses only on the prompt/instruction layer.
Last reviewed: 19 July 2026
What This Page Owns (and What It Defers)
Oracle AI Agent Studio is generally available since release 25C. Its documented capabilities include natural-language instructions and prompts, topics, tools, knowledge sources, multi-agent orchestration, and 50+ prebuilt Fusion agent templates. This page treats the prompt and instruction layer in depth; it does not re-explain the product.
Scope note. The broad "what is Agent Studio" overview lives on Oracle AI Agent Studio. Two neighbouring building blocks have their own pages and are distinct from prompts: agent topics define an agent's scope — the subjects it will handle — while agent tools define the actions it can take. Instructions and prompts sit between the two: they shape how the agent reasons and responds within its scope, and when it reaches for a tool. This page does not try to rank for topics or tools; it owns prompt and instruction design, guardrails, versioning, and prompt testing.
Topics = scope
What the agent may handle. See AI Agent Topics.
Instructions = behaviour
How it reasons, responds, and when it acts. This page.
Tools = actions
What it can do in Fusion. See AI Agent Tools.
Instructions vs Prompts: The Distinction That Matters
The terms are often used interchangeably, but for governance and testing they are worth separating. Both are natural-language text and both shape behaviour — but they operate at different layers and change at different rates.
Instructions — the standing configuration
Instructions are the persistent guidance you author when you configure an agent: its role, tone, the steps it follows, when it calls a tool or defers to a human, and its explicit "do not" rules. They apply to every interaction, change through a deliberate configuration edit, and are the natural unit for versioning and change control.
Prompts — the runtime input
A prompt in the runtime sense is what a user (or calling application) actually sends to the agent. The response is a function of the standing instructions plus the incoming prompt plus the model. Because the incoming prompt is untrusted, it is the surface through which prompt-injection and scope-escape attempts arrive — which is why guardrails belong in the instructions.
Practically: you engineer the instructions to be robust, then test the agent against a wide range of prompts — including adversarial ones — to confirm the instructions hold.
Prompt Engineering Practices for Fusion Agents
Prompt engineering for enterprise Fusion agents is less about clever wording and more about being explicit, bounded, and testable. The practices below are vendor-neutral; apply them within whatever LLM your agent uses, since Oracle lets you bring your own model and behaviour can differ between models.
1. State the role and boundary first
Open with who the agent is and what it is for, then state what falls outside its remit and how to handle out-of-scope requests (defer, escalate, or decline). A clear boundary reduces the chance a cleverly phrased prompt pulls the agent into work its topics never intended.
2. Prefer explicit steps over implied ones
For any process the agent must follow — validate an input, look something up, summarise, confirm — write the steps out. Implicit "just be helpful" instructions are the hardest to test because there is no defined expected behaviour to assert against.
3. Make tool-use conditions unambiguous
Say when the agent should call a tool and when it should not, and require confirmation before any action that writes data or triggers an external call. Tie this to the tools the agent is actually granted; referencing a capability it does not have is a common source of confusing behaviour.
4. Constrain the output shape
If downstream consumers expect a particular format — a short answer, a structured field set, a specific disclaimer — state it. Constrained output is far easier to assert on than free-form prose.
5. Handle the unknown explicitly
Tell the agent what to do when it lacks the information to answer: ask a clarifying question, say it does not know, or escalate — rather than guess. Agents that fabricate to appear helpful create the highest-cost defects.
6. Ground answers in knowledge sources
Where the agent should answer from uploaded documents (a Studio knowledge source for semantic search), instruct it to base answers on that content and to flag when the content does not cover the question, rather than filling gaps from model memory.
Availability note: natural-language instructions/prompts and knowledge sources are generally available with AI Agent Studio (release 25C). Behaviour under a bring-your-own LLM depends on the model you configure — confirm current model options with Oracle.
Guardrails: Putting Limits in the Instructions
Guardrails are the explicit limits you encode so the agent behaves safely even when a prompt pushes against them. In Oracle Fusion, some limits are structural — the agent inherits the user's role-based access, and an External REST tool can require human approval before it executes — but the behavioural guardrails live in the instructions.
Scope guardrails
Refuse or defer out-of-scope requests instead of improvising. Reinforces the agent's topic definitions.
Action guardrails
Require confirmation or approval before any write or external call. Pair the wording with the "Require Human Approval" option on the tool itself.
Data guardrails
Do not reveal data the requesting user should not see, or echo sensitive values into free text. The agent still runs within role-based permissions.
Honesty guardrails
Say "I don't know" or escalate rather than fabricate. Prohibit inventing amounts, dates, IDs, or policy the agent cannot substantiate.
A guardrail that is never tested is an assumption. Every "must not" in the instructions should have a test that tries to make the agent break it — which is what the prompt test matrix below is for.
Versioning and Change Control for Prompts
Because a prompt or instruction edit changes behaviour without changing a single line of traditional code, prompt changes carry genuine regression risk. A reworded guardrail can quietly loosen a control; an added instruction can conflict with an existing one; a "small clarification" can shift output shape for thousands of interactions. Treat instruction text as a controlled artifact.
Prompt change lifecycle
- Keep the prior text. Retain the previous version so a behaviour change can be traced to a specific edit and rolled back.
- Record why. Capture the reason for each change alongside the diff, so reviewers can judge whether the edit does only what was intended.
- Re-run the prompt suite. Replay a fixed set of prompts against old and new instructions and compare responses — the regression check that catches unintended drift.
- Gate promotion. Changes reach production through review and testing, not directly in the live agent.
The broad methodology for validating agents across change is covered on Oracle AI Agent Testing, and scoring and comparing agent responses is covered on Oracle AI Agent Evaluation. This page focuses on the prompt/instruction slice: which prompt risks to test and what to assert.
Prompt Test Matrix
A starting set of prompt-related risks for a Fusion agent, what can go wrong, and the test that catches it. Use it as the backbone of a regression suite that runs whenever instructions change.
| Prompt risk | What can go wrong | Test / assertion |
|---|---|---|
| Scope escape | A user asks the agent to do something outside its topics and it complies | Send out-of-scope prompts; assert the agent defers, escalates, or declines rather than answering |
| Prompt injection | Input text like "ignore your instructions" overrides the standing guardrails | Send override/injection strings; assert instructions still hold and no restricted action fires |
| Unauthorised action | A prompt coaxes the agent to write data or call a tool without confirmation | Assert a confirmation / human-approval step precedes any write or external call |
| Fabrication | The agent invents an amount, date, ID, or policy to appear helpful | Ask questions with no grounded answer; assert it says it does not know or escalates |
| Data leakage | The agent reveals data the requesting user should not see | Run identical prompts under different roles; assert responses respect role-based access |
| Knowledge-source drift | The agent answers from model memory instead of the uploaded documents | Ask questions the source does not cover; assert it flags the gap rather than filling it |
| Output-shape break | Response format changes and breaks a downstream consumer | Assert responses match the required format, length, or field set |
| Ambiguity handling | A vague prompt yields a confident but wrong answer instead of a clarifying question | Send under-specified prompts; assert the agent asks for the missing detail |
| Regression on edit | A reworded instruction quietly changes behaviour elsewhere | Replay the fixed prompt suite against old vs new instructions; assert only intended deltas |
| Instruction conflict | A new rule contradicts an existing one, producing unpredictable results | Test the prompts that exercise both rules; assert consistent, defined precedence |
| Model swap sensitivity | The same instructions behave differently under a different configured LLM | Re-run the suite after any model change; assert guardrails still hold |
This matrix is a starting framework, not an exhaustive control set. Extend it with the specific topics, tools, and data your agent touches.
Security Notes: Prompt Injection
Prompt injection is the risk that untrusted text — typed by a user, or arriving inside a document, email, or external API response the agent processes — contains instructions that try to override the agent's standing guardrails. Because everything the agent reads is natural language, it cannot inherently tell a legitimate instruction from a malicious one embedded in data.
- Treat all incoming content as untrusted. User prompts and any text the agent ingests (documents, tool responses, email bodies) can carry injection attempts.
- Do not rely on instructions alone for high-impact actions. Back behavioural guardrails with structural ones: role-based access and human-approval gates limit what a successful injection can trigger.
- Keep least privilege on tools. An agent granted only the tools it needs has a smaller blast radius if a prompt subverts it.
- Test the failure mode, not just the happy path. Include injection strings in the prompt suite and assert the agent neither leaks data nor performs an unapproved action.
Prompt injection is an industry-wide characteristic of language-model systems, not an Oracle-specific defect. Confirm current controls for your release with Oracle, and treat injection resistance as an ongoing test target, not a one-time sign-off.
How SyntraFlow Helps
SyntraFlow is a testing platform for Oracle Fusion. It does not author your agent's prompts and is not part of Oracle AI Agent Studio — but the disciplines above (a fixed prompt suite, regression on every instruction change, assertions on guardrails) are testing problems, and that is the gap SyntraFlow is built to close.
Turn the matrix into a repeatable suite
SyntraFlow can be configured to run a fixed set of prompts against an agent and assert on the responses, so the matrix becomes something you replay rather than repeat by hand.
Regression on prompt change
SyntraFlow helps organizations assess whether an instruction edit changed behaviour beyond what was intended, by comparing responses before and after a change.
Release-aware testing
SyntraFlow can connect release intelligence with test planning, so prompt suites are re-run when an Oracle quarterly update could shift agent behaviour.
Evidence for governance
SyntraFlow can be configured to capture the prompt, response, and assertion outcome per run, giving reviewers an audit trail behind a prompt-change approval.
SyntraFlow's own testing engine is separate from Oracle's AI — it is used to test Oracle, including Oracle's agents. For how SyntraFlow approaches Oracle Fusion testing generally, see the Oracle ERP Testing Tool. Scope any engagement to your confirmed requirements.
Official Oracle References
Verify current capabilities and availability against Oracle's own documentation. These are the sources relevant to instructions, prompts, and the guardrail mechanisms referenced above:
- Oracle Fusion AI product overview — oracle.com/applications/fusion-ai
- AI Agent Studio key capabilities (instructions, topics, tools, knowledge sources) — docs.oracle.com — key capabilities
- 25C release readiness (AI Agent Studio general availability) — docs.oracle.com — 25C readiness
- External REST tool with "Require Human Approval" option — docs.oracle.com — add external REST tool
- Bring your own / external LLM — docs.oracle.com — add your LLM
Frequently Asked Questions
Are natural-language instructions and prompts officially supported in Oracle AI Agent Studio?
▼
Yes. Instructions and natural-language prompts are among the documented capabilities of Oracle AI Agent Studio, which has been generally available since release 25C. You author them when you create or configure an agent, alongside topics, tools, and knowledge sources.
What is the difference between instructions, prompts, topics, and tools?
▼
Topics define the agent's scope (what it handles); tools define its actions (what it can do). Instructions and prompts shape behaviour — how the agent reasons and responds within that scope, and when it reaches for a tool. This page owns the instruction/prompt layer.
Why does changing a prompt count as a behaviour change that needs testing?
▼
Because the agent's behaviour is driven by natural-language instructions, editing them changes what the agent does without changing conventional code. A reworded guardrail can loosen a control, and a new rule can conflict with an existing one. Re-running a fixed prompt suite before promotion catches that drift.
How do I test for prompt injection?
▼
Include override and injection strings in your prompt suite — both directly typed and embedded inside documents or tool responses the agent reads — and assert the guardrails still hold: no data leak, no unapproved action. Back the instructions with structural controls like role-based access and human-approval gates so a successful injection has a limited blast radius.
How is this page different from AI Agent Testing?
▼
This page owns prompt and instruction design — how to write, guardrail, version, and test the instruction layer specifically. The broad methodology for validating agents across change is on Oracle AI Agent Testing, and scoring/comparing responses is covered on Oracle AI Agent Evaluation.
Can SyntraFlow test my agent's prompts?
▼
SyntraFlow can be configured to run a fixed prompt suite against an agent, assert on the responses, and compare behaviour before and after an instruction change — turning the prompt test matrix into a repeatable regression suite with captured evidence. Scope any engagement to your confirmed requirements; SyntraFlow tests Oracle's agents and is separate from Oracle AI Agent Studio itself.
Generate an Oracle AI Agent Test Plan
Turn your agent's instructions and guardrails into a repeatable prompt test suite — with regression on every change and evidence for governance. See how SyntraFlow can be configured against agents like yours.