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_CALLS.

C_ROLE_TOOL uses TOOL.

type t_chat_message is record (
    chat_role                      t_chat_role,
    message                        clob,
    tool_calls                     t_chat_message_tool_calls,
    tool                           t_chat_message_tool,
    attachments                    t_attachments
);

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;

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_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
);

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),
    message                        t_chat_message,
    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_system`	`'system'`	Role constant for system messages.
`c_role_tool`	`'tool'`	Role constant for tool result messages.
`c_role_user`	`'user'`	Role constant for end user messages.

t_detail_level

t_detail_level describes attachment detail levels understood by support 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

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_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;

3.1 Constants and Data Types