APEX Chat Plug-in

The APEX Chat plug-in is an Oracle APEX region plug-in. It gives a UC AI agent a chat interface. You set one attribute, the agent code, and the region works.

The plug-in does the parts that are difficult to build: it runs the agent in a background job, it polls for the answer, and it keeps the conversation.

Where to get the plug-in

The plug-in is part of UC AI. install_uc_ai.sql and upgrade_uc_ai.sql create its tables and packages. The plug-in export file is attached to the release, next to the scripts. The plug-in has the same version as UC AI.

Why the agent needs a background job

A run takes seconds. An agent with tools takes longer. A page submit that waits five seconds blocks the user, and a gateway can stop the request before the model answers.

The plug-in never makes the page wait. One message goes through these steps:

1. The browser sends the message. The plug-in writes a row and starts a dbms_scheduler job. The request returns at once.
2. The job calls uc_ai_agents_api.execute_agent and writes the answer, the tool calls, and the reasoning to the same table.
3. The browser polls every 2 seconds. It stops when the turn is complete.

Put an Agent in APEX builds a working region on an agent in six lessons, and it covers the parts this page lists as attributes.

Before you start

You need these things:

• UC AI 26.5 or later in the database schema that parses the APEX application. If the application parses in another schema, read Use UC AI in a different schema.
• An agent with the status active. See Profile agents.
• Permission to create a dbms_scheduler job in the schema.

Install the plug-in

1. Install or upgrade UC AI

   In the schema that parses the application, run install_uc_ai.sql for a new installation. Run upgrade_uc_ai.sql for an existing installation.

   Both scripts create the table uc_ai_chat_messages, the table uc_ai_chat_widget_types, and the packages uc_ai_chat_widgets, uc_ai_chat, and uc_ai_chat_hook. The hook package lets the chat show the name of the tool that is currently active. The upgrade script adds any columns missing from an earlier version of the plug-in table, for example tool_call_id, widgets, and parts. You can run it more than once.

2. Import the plug-in

   Import the file region_type_plugin_com_united_codes_uc_ai_chat.sql into your APEX application. The file is a normal APEX component export. In APEX Builder, go to Shared Components > Plug-ins > Import.

   Import the file again after each UC AI upgrade. A region that uses an older export keeps working, but it does not get the new attributes.

Use UC AI in a different schema

The default is one schema: UC AI and the chat objects are in the schema that parses the application. If the application parses in another schema, keep UC AI in its own schema and put the chat objects in the schema of the application.

1. Install UC AI in its own schema

   Run install_uc_ai.sql in the UC AI schema. You can leave the chat objects there. The plug-in does not use them.

2. Create the chat objects in the application schema

   In the schema that parses the application, run the chat block of src/tables/install.sql. It starts at the heading UC AI CHAT PLUG-IN and ends at the end of the file. Then run these package files in this order: uc_ai_chat_widgets, uc_ai_chat, and uc_ai_chat_hook. Run each specification (.pks) before its body (.pkb).

3. Give the application schema access to UC AI

   In the UC AI schema, grant access to the objects that the chat packages use:

   grant execute on uc_ai_agents_api to app_schema;
   grant execute on uc_ai_error to app_schema;
   grant select on uc_ai_agent_sessions to app_schema;
   grant select on uc_ai_agent_messages to app_schema;
   grant select on uc_ai_agent_executions to app_schema;

   Then create a synonym for each of these objects in the application schema:

   create synonym uc_ai_agents_api for uc_ai_schema.uc_ai_agents_api;
   create synonym uc_ai_error for uc_ai_schema.uc_ai_error;
   create synonym uc_ai_agent_sessions for uc_ai_schema.uc_ai_agent_sessions;
   create synonym uc_ai_agent_messages for uc_ai_schema.uc_ai_agent_messages;
   create synonym uc_ai_agent_executions for uc_ai_schema.uc_ai_agent_executions;

   Replace uc_ai_schema and app_schema with the names of your schemas.

4. Optional: show the tool progress

   UC AI calls the hook package from its own schema. Grant it the right to run the package of the application schema:

   grant execute on uc_ai_chat_hook to uc_ai_schema;

   Without this grant, the plug-in does not show tool progress.

5. Import the plug-in

   Import the plug-in file as described in Install the plug-in.

Upgrade the chat objects in the application schema

The script upgrade_uc_ai.sql changes the tables of the UC AI schema only. It does not change the chat tables in the application schema. Do these steps after each UC AI upgrade:

1. Read the release notes. They name each change to the tables uc_ai_chat_messages and uc_ai_chat_widget_types.
2. Apply each change to the table in the application schema. The guarded steps in src/upgrade/upgrade_schema.sql, under the heading UC AI Chat plug-in, show the statements.
3. Run the specifications and the bodies of the three chat packages again in the application schema.
4. Import the plug-in file again.

Add a chat region to a page

1. Create a region

   Create a new region and set its type to UC AI Chat.

2. Set the agent

   Set Agent Code to the code of your agent. This attribute is the only required one.

3. Run the page

   The region shows the welcome message and the message box. Send a message.

The region above has the tool calls, the reasoning, the token counts, and the feedback buttons on. Debug Config controls the first three. Collect Feedback controls the buttons, and it is off by default. The feedback row has a line of its own below the answer and stays on screen. The user does not have to move the pointer on the message to find it. The question goes away after the user clicks a thumb. A thumbs down also opens a box for an optional comment.

While the agent runs, the region shows an indicator. The indicator can also give the name of the tool that runs now.

The send button becomes a Stop button while the agent runs. A stop before the job starts costs no tokens.

Region attributes

The plug-in has 20 attributes. Agent Code is the only one that you must fill in. Six more attributes are required, but each one has a default value.

Agent

Attribute	Type	Default	What it does
Agent Code	Text	—	The code of the agent. This attribute is required.
Agent Version	Number	active version	Locks the region to one version of the agent. Use it to hold a known-good version while you write a new one.
Agent Input Mapping	Textarea	{"message": "#USER_MESSAGE#"}	A JSON template for the input parameters of the first message. &ITEM. gives the value of a page item. #USER_MESSAGE# gives the text of the user. Later messages of the same conversation use the history instead.
Session Init Code	PL/SQL	—	PL/SQL that runs in the background job, before the agent. The job has no APEX session, so anything the agent needs must start here.

The scheduler job has no APEX session of its own. As a result, UC AI records the database user and the audience db. To give the run the real APEX user, attach a session in Session Init Code:

apex_session.attach(
  p_app_id     => :APP_ID,
  p_page_id    => :APP_PAGE_ID,
  p_session_id => :APP_SESSION
);

This step is necessary for every guardrail with the scope user, each_user, app, apex_session, public, or authenticated. Without it, only a global guardrail with the audience any governs a chat turn.

Run context

Attribute	Type	Default	What it does
Agent Run Context	Textarea	—	A JSON object that binds the conversation to one record. Every tool of the run gets these values under the key _ctx.
Run Context Drift	Select List	error	What the plug-in does when the values change during a conversation.

The run context is the way to make a chat region talk about one contract, one case, or one tenant. The model cannot read these values and cannot change them.

{
  "contract_id": "&P10_CONTRACT_ID.",
  "tenant_id": "&APP_USER."
}

Leave the bound value out of the parameters of the tool. The handler then reads _ctx and there is one place the value can come from.

UC AI binds the run context on the first turn of a conversation. A later turn can add a key. A later turn cannot change a key. This rule protects the conversation: the messages, and any memory files, belong to the first binding.

A page item can change while the chat is open. Run Context Drift decides what happens then:

Value	What happens
error	The plug-in refuses the turn. A notice tells the user to start a new chat. Nothing is lost without a decision from the user.
new_session	The plug-in starts a new conversation with the new values. This value is correct for a page about one record. The old messages are gone.
ignore	The plug-in keeps the first binding and ignores the change.

The run context binds the arguments of a tool, not the tools themselves

A bound DOC_SEARCH tool gives no protection when the same agent also has a tool that can read any table. Give the agent only the tools it needs.

Conversation

Attribute	Type	Default	What it does
Session Item	Page Item	—	A page item that holds the session ID. The chat continues this conversation after a page submit. Leave it empty for a conversation that starts again on every page load.
Suggested Prompts	Textarea	—	Example questions, one for each line. They show as buttons above the message box, with the label “Try asking”, while the conversation is empty. A click sends the question immediately. Each button shows the full question.
Auto Generate Title	Checkbox	N	Names the conversation after the first answer, with the language model of the browser.
Collect Feedback	Checkbox	N	Shows a row with the question “Was this helpful?” and two thumb buttons below the newest answer.
Widgets	Checkboxes	none checked	The widget types that the agent can show in an answer: stat_card, status, key_value, table, and chart. Needs UC AI 26.5.
Custom Widgets	Text	—	The names of widget types that you registered with uc_ai_chat_widgets.register_type. Separate several names with a comma, a colon, a semicolon, or a space. Needs UC AI 26.5.

Auto Generate Title uses the on-device model of the browser (Chrome 148 or later). No text goes to a server and the run costs no tokens. The plug-in never starts the download of the model. If the model is not available, the region keeps the configured Header Title.

Widgets lets the agent show a key figure, a status notice, a short list, a table, or a chart in an answer. The plug-in adds widget instructions to the system prompt of the first turn. The server checks each widget. The browser displays the widget and treats its labels and values as plain text. The Chat Widgets guide has the widget types, the data binding, the limits, and the security notes. Custom Widgets turns on a widget type that you wrote yourself, for example a list of records that the user can open. See Custom Chat Widget Types.

Chat WidgetsShow a stat card, a status, a key value list, a table, or a chart in the answer of an agent.

The title goes to uc_ai_agent_sessions.title. The rating goes to uc_ai_agent_sessions.feedback_rating, with feedback_comment and feedback_at. uc_ai_agents_api.list_sessions returns all four columns, so one query gives you the conversations with a negative rating.

Appearance

Attribute	Type	Default	What it does
Display Mode	Select List	region	region puts the chat in the page. dialog shows a small button that opens the chat in a dialog.
Header Title	Text	UC AI Chat	The title in the header of the chat.
Welcome Message	Textarea	Ask me anything...	The first message of the assistant, while the conversation is empty.
Avatar Icon	Icon	fa-robot	The icon of the assistant, and the icon of the button in dialog mode.
Min Height	Text	450px	The minimum height of the region.
Thinking Animation	Select List	dots	The animation during a run: dots, braille, plasma, or matrix.
Thinking Detail	Select List	tools	How much the indicator says: off, status, or tools.

With display_mode set to dialog, the region becomes a small button. A click on the button opens the chat above the page.

Thinking Detail controls one line of text under the animation. The value status gives Thinking… and the elapsed seconds. The value tools also tells a tool run apart from a model run, with Running a tool….

The indicator never gives the name of the tool. The tool row above it already carries the name, so a name here is the same text two times.

To keep tool names away from the user, use Debug Config. With show_tools off, no tool row reaches the browser at all. A tool name is an internal identifier and can tell a user more about your system than you want.

The value off removes the text for the eye only. A screen reader gets the announcement at every level, because a visual preference must not remove the only signal that a run is active.

The attributes above control the chat. The frame around it is an ordinary APEX region, and the region template decides that frame. The chat has a header, padding and a scroll area of its own. A region with the default template repeats all three.

To give the chat the whole region, set the region template to Standard and turn on these template options:

• Remove Header — the chat has a header of its own.
• No Padding — the messages then reach the edges of the region.
• Scroll Body — the conversation scrolls inside the region, and the page stays where it is.

The screenshots on this page use all three.

Developer

Attribute	Type	Default	What it does
Debug Config	PL/SQL Function Body	reasoning, tools, and metadata are on	A function that returns JSON. The JSON decides which parts the user sees.

The function returns up to five flags:

• show_reasoning — the reasoning of the model, above each answer.
• show_tools — each tool call, with its arguments, its result, and its status.
• show_metadata — the token counts next to each answer.
• show_debug — a panel with the details of the run.
• show_errors — the text of an error, instead of a general message. It also shows why a widget appears as text.

Every flag is false when the attribute is empty, when the function raises an error, or when the JSON is not valid.

The flags work on the server. When a flag is false, the plug-in removes those rows and fields from the response. The hidden content never reaches the browser, so a modified client cannot show it.

Because this attribute is a function, one region can show different things to different people:

if apex_authorization.is_authorized('ADMIN_AUTH') then
  return '{ "show_reasoning": true, "show_tools": true, "show_debug": true }';
else
  return '{}';
end if;

Guardrails

The plug-in makes the verdicts of the UC AI Pro guardrails visible. Without the Pro packages, this feature does nothing.

Notice	When it shows
Approaching	A limit is past its warn threshold. The user can close the notice.
Reached	A hard limit refused the turn. The notice also shows on the failed answer.

The plug-in never enforces a limit. The database guardrail stays the only enforcer. The notices give no figure, no percentage, and no name of a limit.

Security

• The region decides which agent runs. The plug-in compares the agent code in the request against the region’s own attribute and refuses a request that names a different agent. Without this check, a user of the application can make the region run any agent in the schema.
• One user owns one conversation. After the first message, only the user who sent it can read the conversation or add to it.
• A widget is rebuilt on the server. The server creates each widget specification with only allowed keys. The browser treats every value as plain text, so values cannot contain HTML, links, or images. The region decides which types the agent can use. See Security and trust.
• The answer is sanitized. The plug-in shows the answer as Markdown. It removes dangerous HTML before the browser gets it.
• Errors stay in the database. A failure of the background job writes the full error to the APEX debug log. The user gets a general message, unless show_errors is on.

Version history

The plug-in has the same version as UC AI. The first release that includes the plug-in is 26.5. This table gives the UC AI version that introduced each feature:

Feature	UC AI version
Chat region, tools, reasoning	26.1
Auto Generate Title, Collect Feedback, Agent Run Context, Run Context Drift	26.3
Widgets, Custom Widgets	26.5

The run contextHow a bound value reaches every tool of a run, and why the model must not choose it.

Put an Agent in APEXSix lessons that put this region on a page: one contract, private conversations, and an audit trail that names the person who asked.