Oracle APEX • Part 1 of 2

AI Agents in Oracle APEX: what they actually are

Every time a new APEX version is released, I like to explore the new features before I start building applications. When APEX 26.1 came out, one feature immediately caught my attention: AI Agents. At first, I assumed it was just the AI Assistant with a few updates. After spending some time exploring it, I realized it's actually something quite different - and that made me want to understand it better.

1Assistants answer. Agents act.

An AI assistant only talks. Ask it something and it responds using what it already knows - summarizing, rewriting, answering from a document. It never actually touches your application; it just discusses it.

An AI agent does something with the request. Instead of replying straight away, it runs a small loop:

1. Understand what you're asking
2. Work out what info it needs
3. Go fetch that info from the app
4. Take an action
5. Check the result
6. Repeat until it has a useful answer

Reading that list, I realized this is basically what I do when someone messages me asking "can you check why this order didn't ship." I don't already know the answer. I go look something up, maybe run a query, maybe check a status, and then I respond. An AI Agent is Oracle's attempt to let the model do that same loop, safely, inside your app.

2What makes it possible: tools

The model can't just run loose in your database. It only gets access to a specific list of capabilities you define - called Tools. You hand it a toolbox, not the whole workshop. No tool, no ability.

Tools in APEX can run in two different places:

• Server-side, where they execute as PL/SQL - the natural home for business logic and database operations.
• Client-side, where they run as JavaScript in the user's browser - useful when the agent needs to interact with something on the actual page, like a form item or a region.

And they can be triggered in two different ways:

• On demand, where the model decides for itself, mid-conversation, that it needs to call a tool to get an answer.
• To augment the system prompt, where the tool runs automatically on every single message, quietly injecting fresh context - things like the current user's name or today's date - before the model even starts reasoning.

Once I understood that second mode, a lot of "how would the AI even know that" questions I had going in just disappeared.

3Assistant vs. Agent

AI Assistant

Uses RAG to feed it data or vectors so it can talk about your app's content. Good for "let the user ask questions."

AI Agent

Same, plus Tools as its hands. It decides what it needs, runs a tool, checks the result, and completes the task.

Simply put: an assistant tells you your leave balance because someone already loaded it. An agent goes and checks - then submits the leave request if you ask.

4Getting familiar with the attributes

When you actually sit down to build a tool in APEX, there are a handful of attributes you need to get comfortable with. A few notes from going through this myself:

name

The Name uniquely identifies your tool. Oracle recommends using lowercase letters, underscores, and numbers, with the name starting with a letter. For example, check_customer_balance or create_support_ticket.

Although it looks like a simple naming rule, choosing a meaningful name is important because the AI model uses both the tool name and its description to determine when the tool should be invoked.

type

Every tool is one of three built-in kinds - see the table below.

Type	Runs where	Best for
Execute Client-side Code	Browser (JavaScript)	Interacting with the current page, form items, or regions
Execute Server-side Code	Database (PL/SQL)	Business logic, database operations
Retrieve Data	Database → back to the AI	Answering questions that need information - orders, balances, statistics

parameters

Parameters define the input values that the AI passes to your tool during execution.

Each parameter should include a clear description so the AI understands what information is expected. Parameters can be marked as optional, allowing them to be passed as NULL when necessary.

For VARCHAR2 and NUMBER parameters, you can also specify a list of permitted values. This helps prevent the AI from supplying unexpected or unsupported inputs.

data description

For Retrieve Data tools, a short explanation of what the data actually represents, plus a source type: SQL Query (pulled straight from your database), Function Body (sourced from a function that returns a CLOB), or Static (hard-coded text that isn't coming from the database at all).

maximum tokens

Caps how much the tool can return. If a row would push the response past that limit, it gets skipped entirely rather than truncated mid-way - worth knowing before you're confused why a record didn't show up.

---

5Where I landed

After exploring AI Agents in APEX 26.1, I realized they're not about replacing your application logic. Instead, they let an AI model use the tools and actions you define to complete tasks. You stay in control of the process, while the AI helps automate the execution. It's a practical feature that opens up new possibilities for building smarter APEX applications.

Next up: in Part 2, I'll walk through the demo app I built with this - real tools, real trade-offs, and what actually broke.