About Including Generative AI in Applications

Learn about including Generative AI (such as an AI Assistant) in your applications.

You can include AI in your applications by creating a Generative AI Service, configuring AI Attributes for the application, and using AI-enhanced components such as dynamic actions, page processes, or workflow activities.

In general, the steps are as follows:

Create a Generative AI Service. See Creating Generative AI Service Objects.
Create an application. See Creating Applications.
Edit the application definition and configure the attributes on the AI tab. See Configuring AI Attributes for an Application.
Create an AI-enhanced component:
- Show AI Assistant - Use a Dynamic Action True Action to display the AI Assistant, an AI-powered chat service, either as a dialog or inline.
- Generate Text With AI - Use a Dynamic Action True Action, a Page Process, or a Workflow Activity to invoke the configured Generative AI Service and generate a one-time response based on user content. This action is ideal for tasks like summarizing or translating text, extracting keywords, or drafting an email.

About Show AI Assistant True Action Behaviors

The Show AI Assistant True Action displays an AI-powered chat service as a dialog or inline. You can edit the Action attributes in Page Designer to define all kinds of behavior. Consider the following examples:

Generative AI, System Prompt - Specify a system prompt to give the AI context and provide instruction on how to process the input. Supports application and page items and system variables.
Generative AI, Welcome Message - Specify a welcome message the AI Assistant will display. Supports substitutions: Application and page items and system variables.
Appearance, Display As - Select if AI Assistant should display as a dialog or inline.
Initial Prompt, Type - Specify the initial prompt (or message) that displays to the user to make it appear it’s coming from an actual person. The message can be stored as an item or a value from a JavaScript expression.
Use Response, Type - Select how the AI Assistant should return responses. The term response refers to the message content of an individual chat message. You have the option to capture this response directly in a page item value or to process it based on more complex logic using JavaScript Code.
Quick Actions, Type - Enter a message to serve as a chat-wide quick action. A quick action is a pre-defined phrase that, once clicked, will be sent as a user message. Supports template directives, application and page items. and system variables.

Tip: To view an example, see Creating a Dynamic Action to Display AI Assistant.

About Using AI-Generated Navigation in Show AI Assistant

AI Agents used by Show AI Assistant can generate application-controlled navigation links within their responses. This is a programmatic, high-code integration designed to give developers flexible control over which destinations the AI model can suggest, which parameters each destination accepts, and how every generated link is authorized and rendered.

The application-level AI Request Handler defines a catalog of navigation targets. Each target has an identifier, an AI-facing description, and optional parameter definitions. APEX converts these definitions into an additional system message that explains the available targets and link syntax to the AI model. Only the target identifiers, hints, and parameter definitions are included; application URLs, session identifiers, checksums, and other private navigation details remain on the server.

Because the target catalog becomes part of the system prompt, its definitions consume input tokens on each applicable request. Applications should therefore provide focused target sets and clear concise hints.

The AI model can embed structured link placeholders in its typical response. APEX parses each placeholder and invokes the target’s application callback. The callback validates the AI-generated parameters for the current user and returns the final URL, label, description, icon, and link attributes. APEX then expands the placeholder into the link displayed by Show AI Assistant while preserving the original, unexpanded model message for conversation history.

This flow does not use AI Tools and does not require additional AI provider roundtrips. Target selection is part of the model’s original response, and callback validation and link expansion happen locally in APEX after that response is received.

AI Navigation is available when all of the following are used together:

the Show AI Assistant dynamic action;
an AI Agent; and
the application-level AI Request Handler.

Other AI invocation paths do not process these navigation definitions.

The navigation callback is the application security boundary. Treat every AI-generated parameter as untrusted input: validate its type and syntax, convert it to a canonical value, verify that the referenced record exists in the current application or tenant, and confirm that the current user is authorized to access it. Construct the final destination with APEX_PAGE.GET_URL or another application-owned safe URL routine; never concatenate model output into SQL, PL/SQL, HTML, or URLs. A denied target can return an application-approved fallback such as # and Not allowed, or leave LINK_URL as NULL to suppress the link.

Example

The following package defines two hardcoded targets:

Orders, with no parameters.
Order Details, with one required ORDER_ID parameter.

The application-level AI Request Handler adds these targets only when the current AI Agent has the Static ID order-assistant. The example intentionally references a placeholder package named EXAMPLE_NAVIGATION_SECURITY; replace it with application-owned validation routines that enforce the requirements described above.

Package Specification

create or replace package example_ai_navigation authid definer as

--==============================================================================
-- Validates an AI-selected navigation target and returns its final URL.
--
-- Parameters:
-- * p_param:  Selected target, AI Agent context, and untrusted parameter values.
-- * p_result: Final URL and presentation properties returned to APEX.
--==============================================================================
procedure navigation_handler (
    p_param  in            apex_ai.t_chat_navigation_param,
    p_result in out nocopy apex_ai.t_chat_navigation_result );

--==============================================================================
-- Adds application-approved navigation targets to Show AI Assistant requests.
--
-- Parameters:
-- * p_param:  Context for the current AI request.
-- * p_result: Request configuration populated with navigation targets.
--==============================================================================
procedure ai_request_handler (
    p_param  in            apex_ai.t_chat_request_handler_param,
    p_result in out nocopy apex_ai.t_chat_request_handler_result );

end example_ai_navigation;
/

Package Body

create or replace package body example_ai_navigation as

--==============================================================================
-- Validates AI-generated parameters and constructs a user-authorized URL.
--==============================================================================
procedure navigation_handler (
    p_param  in            apex_ai.t_chat_navigation_param,
    p_result in out nocopy apex_ai.t_chat_navigation_result )
as
    l_order_id number;

    -------------------------------------------------------------------------------
    -- Replaces a denied destination with a non-navigating link.
    procedure deny_link
    is
    begin
        p_result.link_url        := '#';
        p_result.link_label      := 'Not allowed';
        p_result.icon_classes    := 'fa fa-lock';
        p_result.link_attributes := 'aria-disabled="true"';
    end deny_link;
    -------------------------------------------------------------------------------

begin
    case p_param.target.static_id
        when 'orders' then
            if example_navigation_security.can_view_orders (
                   p_user_name => V( 'APP_USER' ) )
            then
                p_result.link_url :=
                    apex_page.get_url (
                        p_page        => 10,
                        p_clear_cache => '10' );
            else
                deny_link;
            end if;
        when 'order-details' then
            l_order_id :=
                example_navigation_security.get_authorized_order_id (
                    p_user_name => V( 'APP_USER' ),
                    p_value     => p_param.parameters( 'ORDER_ID' ) );

            if l_order_id is null then
                deny_link;
            else
                p_result.link_url :=
                    apex_page.get_url (
                        p_page        => 20,
                        p_clear_cache => '20',
                        p_items       => 'P20_ORDER_ID',
                        p_values      => l_order_id );
            end if;
        else
            deny_link;
    end case;
end navigation_handler;

--==============================================================================
-- Adds two hardcoded targets only for the order-assistant AI Agent.
--==============================================================================
procedure ai_request_handler (
    p_param  in            apex_ai.t_chat_request_handler_param,
    p_result in out nocopy apex_ai.t_chat_request_handler_result )
as
begin
    if p_param.agent.static_id = 'order-assistant' then
        p_result.request.navigation :=
            apex_ai.t_navigation (
                callback_procedure => 'EXAMPLE_AI_NAVIGATION.NAVIGATION_HANDLER',
                targets            =>
                    apex_ai.t_navigation_targets (
                        apex_ai.t_navigation_target (
                            static_id       => 'orders',
                            ai_hint         => 'Open the report that shows orders available to the current user.',
                            link_label      => 'Orders',
                            icon_classes    => 'fa fa-table' ),
                        apex_ai.t_navigation_target (
                            static_id       => 'order-details',
                            ai_hint         => 'Open one order by its order ID.',
                            link_label      => 'Order Details',
                            ui_description  => 'View an order.',
                            icon_classes    => 'fa fa-file-text-o',
                            parameters      =>
                                apex_ai.t_navigation_target_params (
                                    apex_ai.t_navigation_target_param (
                                        static_id   => 'ORDER_ID',
                                        ai_hint     => 'The order ID explicitly provided by the user.',
                                        is_required => true ) ) ) ) );
    end if;
end ai_request_handler;

end example_ai_navigation;
/

About Generate Text with AI Behaviors

You can generate text with AI by using a Dynamic Action True Action , a Page Process , or a Workflow Activity.

Generate Text With AI calls the configured Generative AI Service and generates a one-time response based on user content. This is ideal for tasks like summarizing or translating text, extracting keywords, or drafting an email. You can edit the Action attributes in Page Designer to define all kinds of behavior. Consider the following examples:

Generative AI, System Prompt (Dynamic Action only) - Specify a system prompt to give the AI context and provide instruction on how to process the input. Supports application and page items and system variables.
Input Value, Type - Select the type of user input to be delivered to the AI service. The term input refers to the request text to be sent to the AI service. You have the option to capture to provide this input directly in a page item value or returning it with more complex logic using a JavaScript expression.
Use Response, Type - Select how the AI service should return the response. You have the option to capture this response directly in a page item value or to process it based on more complex logic using JavaScript Code. If an item is used, you can control if the response should trigger the change event.

Tip:

For an example of a Dynamic Action True Action, see Creating a Dynamic Action to Generate Text with AI.

For an example of a Page Process, see Creating a Page Process to Generate Text with AI.

For an example of a Workflow Activity, see Adding a Workflow Generate Text with AI Activity.

Utilizing AI Infrastructure Programmatically

You also access the AI infrastructure programmatically using the APEX_AI package. Note that the APEX_AI APIs require an APEX session, must linked to an APEX app that has a Generative AI Service properly configured. Consider the following SQL Developer example:

set serveroutput on;

declare
    l_result clob;
begin
    apex_session.create_session (
        p_app_id   => 102,
        p_page_id  => 1,
        p_username => 'ADMIN' );

    l_result := apex_ai.generate( 'what''s 1+1?' );

    sys.dbms_output.put_line( l_result );

    apex_session.delete_session;
exception
    when others then
        apex_session.delete_session;
        raise;
end;
/

For more information, see:

APEX_AI in Oracle APEX API Reference