Constants and Data Types

The section describes constants and data types used by the APEX_AI package.

t_agent

t_agent describes the agent configuration context passed into AI handler procedures. STATIC_ID identifies the agent that triggered the callback. ID is populated for Shared Components AI Agents and NULL for ad-hoc or programmatic agents.

type t_agent is record (
    id                             number,
    static_id                      varchar2(255)
);

t_attachment

t_attachment describes an attachment record.

type t_attachment is record (
    mime_type                      varchar2(255),
    content_blob                   blob,
    content_clob                   clob,
    file_name                      varchar2(255),
    detail_level                   t_detail_level
);

Name	Value	Description
`mime_type`	`varchar2(255)`	The MIME type of the file. Required.
`content_blob`	`blob`	The file content as a `BLOB`. Use this for images, audio, PDFs, etc.
`content_clob`	`clob`	The file content as a `CLOB`. Use this for text-based files.
`file_name`	`varchar2(255)`	The file name. It might be required depending on the AI provider and file type.
`detail_level`	`t_detail_level`	The detail level for processing. Optional.

t_attachments

t_attachments describes a collection of attachments.

type t_attachments is table of t_attachment;

t_chat_message

Note:

C_ROLE_SYSTEM, C_ROLE_ASSISTANT and C_ROLE_USER use CHAT_ROLE and MESSAGE.

C_ROLE_ASSISTANT can also use TOOL_CALL.

C_ROLE_TOOL uses TOOL.

type t_chat_message is record (
    chat_role                      t_chat_role,
    message                        clob,
    tool_call                      t_chat_message_tool_call,
    tool                           t_chat_message_tool,
    attachments                    t_attachments,
    ui_message                     clob
);

t_chat_message_tool

t_chat_message_tool describes a tool response entry added to chat history.

type t_chat_message_tool is record (
    id                             varchar2(255),
    content                        clob
);

t_chat_message_tool_call

t_chat_message_tool_call describes a tool call emitted by the AI service.

type t_chat_message_tool_call is record (
    id                             varchar2(255),
    name                           varchar2(255),
    args                           clob,
    args_json                      sys.json_object_t
);

t_chat_message_tool_calls

t_chat_message_tool_calls describes a collection of tool calls.

type t_chat_message_tool_calls is table of t_chat_message_tool_call;

Note: t_chat_message_tool_calls is deprecated and will be removed in a future release.

t_chat_messages

t_chat_messages describes a collection of chat history entries.

type t_chat_messages is table of t_chat_message index by pls_integer;

t_chat_navigation_param

t_chat_navigation_param is the read-only input passed to the navigation callback.

AGENT identifies the AI Agent. COMPONENT identifies the component that initiated the request. TARGET is the application-defined target selected by the AI model. PARAMETERS contains the AI-generated values declared for that target.

type t_chat_navigation_param is record (
    agent       t_agent,
    component   wwv_flow.t_component,
    target      t_navigation_target,
    parameters  t_navigation_param_values );

t_chat_navigation_result

t_chat_navigation_result is the read-write output returned by the navigation callback.

APEX initializes all presentation members from the target definition but deliberately does not internalize LINK_URL. The callback must set the final LINK_URL. It may also replace the label, description, icon, and link attributes.

type t_chat_navigation_result is record (
    link_url        varchar2(32767),
    link_label      varchar2(32767),
    ui_description  varchar2(32767),
    icon_classes    varchar2(255),
    link_attributes varchar2(255) );

t_chat_request

t_chat_request describes a normalized chat request passed into response handlers.

type t_chat_request is record (
    service_id                     number,
    system_prompt                  clob,
    messages                       t_chat_messages,
    tools                          t_tools,
    temperature                    number,
    response_json_schema           clob,
    navigation                     t_navigation,
    model                          varchar2(255),
    reasoning_effort               t_reasoning_effort
);

t_chat_request_handler_param

t_chat_request_handler_param describes the read-only input passed into a request handler procedure.

type t_chat_request_handler_param is record (
    agent                          t_agent,
    invocation                     pls_integer
);

t_chat_request_handler_result

t_chat_request_handler_result describes the read-write output passed into a request handler procedure.

type t_chat_request_handler_result is record (
    request                        t_chat_request
);

t_chat_response

t_chat_response describes a normalized chat response returned from AI providers.

type t_chat_response is record (
    type                           t_response_type,
    error                          t_response_error,
    refusal                        varchar2(32767),
    messages                       t_chat_messages,
    input_tokens                   number,
    output_tokens                  number,
    total_tokens                   number
);

t_chat_response_handler_param

t_chat_response_handler_param describes the read-only input passed into a response handler procedure.

type t_chat_response_handler_param is record (
    agent                          t_agent,
    invocation                     pls_integer,
    request                        t_chat_request,
    pending_tool_calls             t_chat_message_tool_calls
);

t_chat_response_handler_result

t_chat_response_handler_result describes the read-write output passed into a response handler procedure.

type t_chat_response_handler_result is record (
    response                       t_chat_response,
    messages                       t_chat_messages,
    early_exit                     boolean
);

t_chat_role

t_chat_role describes chat role values used in t_chat_message.

subtype t_chat_role is varchar2(10);

Name	Value	Description
`c_role_assistant`	`'assistant'`	Role constant for assistant messages.
`c_role_other`	`'other'`	Role constant for other messages.
`c_role_system`	`'system'`	Role constant for system messages.
`c_role_tool`	`'tool'`	Role constant for tool result messages.
`c_role_tool_call`	`'tool_call'`	Role constant for tool call messages.
`c_role_user`	`'user'`	Role constant for end user messages.

t_detail_level

t_detail_level describes attachment detail levels understood by supported AI providers.

subtype t_detail_level is varchar2(15);

Name	Value	Description
`c_detail_level_auto`	`'auto'`	Automatic provider-controlled detail level for attachment processing
`c_detail_level_high`	`'high'`	High detail level for attachment processing
`c_detail_level_low`	`'low'`	Low detail level for attachment processing
`c_detail_level_original`	`'original'`	Original detail level for attachment processing.

t_navigation_param_values

t_navigation_param_values contains the AI-generated parameter values for the selected target.

Parameter values are untrusted model output. The callback must validate their type, format, existence, application or tenant ownership, and authorization for the current user.

type t_navigation_param_values is table of varchar2(4000) index by varchar2(255);

t_navigation_target_param

t_navigation_target_param defines one parameter that an AI model may provide for a navigation target.

STATIC_ID is the parameter name exposed to the AI model.

AI_HINT explains the expected value to the AI model.

IS_REQUIRED specifies whether the model must provide a nonempty value.

type t_navigation_target_param is record (
    static_id   varchar2(255),
    ai_hint     varchar2(4000),
    is_required boolean default true );

t_navigation_target_params

t_navigation_target_params is a collection of parameter definitions for a navigation target.

type t_navigation_target_params is table of t_navigation_target_param;

t_navigation_target

t_navigation_target defines an application-approved destination.

The AI model receives STATIC_ID, AI_HINT, and the parameter definitions. It does not receive LINK_URL, LINK_LABEL, UI_DESCRIPTION, ICON_CLASSES, or LINK_ATTRIBUTES.

STATIC_ID and LINK_LABEL are required. LINK_URL is unverified configuration input and is not used as the final destination until the navigation callback validates or replaces it.

type t_navigation_target is record (
    static_id       varchar2(255),
    ai_hint         varchar2(4000),
    parameters      t_navigation_target_params default t_navigation_target_params(),
    --
    link_url        varchar2(32767),
    link_label      varchar2(32767),
    ui_description  varchar2(32767),
    icon_classes    varchar2(255),
    link_attributes varchar2(255) );

t_navigation_targets

t_navigation_targets is a collection of application-approved navigation tagets.

type t_navigation_targets is table of t_navigation_target;

t_navigation

t_navigation defines the target collection and the callback that validates and expands selected targets.

CALLBACK_PROCEDURE is required whenever TARGETS is provided. Navigation targets cannot be combined with a response JSON schema.

type t_navigation is record (
    targets             t_navigation_targets,
    callback_procedure  varchar2(255) );

t_notification

t_notification describes a notification returned from a tool execution.

type t_notification is record (
    type                           t_notification_type,
    content                        varchar2(32767)
);

t_notification_type

t_notification_type describes notification types returned from the tool execution.

subtype t_notification_type is varchar2(10);

Name	Value	Description
`c_notification_type_error`	`'error'`	Error notification type
`c_notification_type_generic`	`null`	Notification type indicating no explicit severity
`c_notification_type_info`	`'info'`	Informational notification type
`c_notification_type_success`	`'success'`	Success notification type
`c_notification_type_warning`	`'warning'`	Warning notification type

t_notifications

t_notifications describes a collection of notifications.

type t_notifications is table of t_notification;

t_reasoning_effort

t_reasoning_effort is the reasoning effort levels understood by supported AI providers.

subtype t_reasoning_effort is varchar2(7);

Name	Value	Description
`c_reasoning_effort_none`	`'none'`	Role constant for no additional reasoning effort.
`c_reasoning_effort_minimal`	`'minimal'`	Role constant for minimal reasoning effort.
`c_reasoning_effort_low`	`'low'`	Role constant for low reasoning effort.
`c_reasoning_effort_medium`	`'medium'`	Role constant for medium reasoning effort.
`c_reasoning_effort_high`	`'high'`	Role constant for high reasoning effort.
`c_reasoning_effort_xhigh`	`'xhigh'`	Role constant for extra-high reasoning effort.
`c_reasoning_effort_max`	`'max'`	Role constant for maximum reasoning effort.

t_response_error

t_response_error describes recoverable AI response error types.

subtype t_response_error is varchar2(20);

Name	Value	Description
`c_resp_err_content_filter`	`'content_filter'`	Recoverable response error indicating provider-side content filtering. Maps to `e_content_filter`.
`c_resp_err_generic`	`'generic'`	Generic response error raised when no more specific error type applies. Maps to `e_service_error`.
`c_resp_err_invalid_response`	`'invalid_response'`	Recoverable response error indicating invalid JSON content. Maps to `e_invalid_json_response`.
`c_resp_err_invalid_tool_call`	`'invalid_tool_call'`	Recoverable response error indicating an invalid tool call payload. Maps to `e_invalid_json_tool_call`.
`c_resp_err_max_length`	`'max_length'`	Recoverable response error indicating the model hit a maximum length limit. Maps to `e_max_length`.
`c_resp_err_refusal`	`'refusal'`	Recoverable response error indicating the model refused the request. Maps to `e_refusal_filter`.

t_response_type

t_response_type describes high-level chat response types.

subtype t_response_type is varchar2(10);

Name	Value	Description
`c_response_type_complete`	`'complete'`	Response type indicating completion without additional tool calls.
`c_response_type_error`	`'error'`	Response type indicating an error.
`c_response_type_tool_calls`	`'tool_calls'`	Response type indicating pending tool calls.

t_tool

**t_tool** describes a tool definition passed to CHAT or GENERATE.

type t_tool is record (
    name                           varchar2(64),
    description                    varchar2(32767),
    parameters                     t_tool_parameters,
    parameters_json_schema         clob,
    callback_procedure             varchar2(255)
);

t_tool_exec_param

t_tool_exec_param describes tool execution input passed to a callback procedure.

type t_tool_exec_param is record (
    tool                           t_tool,
    args                           clob,
    args_json                      sys.json_object_t
);

t_tool_exec_result

t_tool_exec_result describes tool execution output returned from a callback procedure.

type t_tool_exec_result is record (
    result                         clob,
    early_exit                     boolean,
    is_safe                        boolean default false
);

t_tool_parameter

t_tool_parameter describes the tool parameter definition used in t_tool.

type t_tool_parameter is record (
    name                           varchar2(64),
    description                    varchar2(32767),
    data_type                      t_tool_parameter_data_type,
    is_required                    boolean,
    allowed_values                 apex_t_varchar2
);

t_tool_parameter_data_type

t_tool_parameter_data_type describes the tool parameter data types supported by t_tool_parameter.

subtype t_tool_parameter_data_type is varchar2(8);

Name	Value	Description
`c_tool_param_type_boolean`	`'BOOLEAN'`	Tool parameter data type for `BOOLEAN` values.
`c_tool_param_type_clob`	`'CLOB'`	Tool parameter data type for `CLOB` values.
`c_tool_param_type_number`	`'NUMBER'`	Tool parameter data type for `NUMBER` values.
`c_tool_param_type_varchar2`	`'VARCHAR2'`	Tool parameter data type for `VARCHAR2` values.

t_tool_parameters

t_tool_parameters describes a collection of tool parameter definitions.

type t_tool_parameters is table of t_tool_parameter;

t_tools

t_tools describes a collection of tool definitions.

type t_tools is table of t_tool;