adm_ai_agent_tools_api

AI Agent Tools for read-only exploration of the document management system. Each function takes a JSON clob parameter and returns a JSON clob result. These functions are designed to be registered as UC AI tools.

The current user is determined from the session context (sys_context). Results are filtered to only include folders and documents the user has access to.

Functions and Procedures

list_folders

Lists subfolders of a given folder that the user has access to.

Parameters (JSON): folder_path (optional) - Path of the parent folder (e.g. ‘/projects’). Defaults to root. folder_id (optional) - ID of the parent folder. Alternative to folder_path. search_terms (optional) - Array of terms to filter folder names (case-insensitive, OR match). Example: [“reports”, “invoices”, “billing”] max_results (optional) - Maximum number of results (default 50).

Signature:

function list_folders (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object with the parameters

Returns: clob - JSON array of folder objects

---

list_files

Lists documents/files in a given folder that the user has access to.

Parameters (JSON): folder_path (optional) - Path of the folder. Defaults to root. folder_id (optional) - ID of the folder. Alternative to folder_path. search_terms (optional) - Array of terms to filter document names (case-insensitive, OR match). Example: [“hotel”, “booking”, “reservation”] mime_type (optional) - Filter by MIME type (e.g. ‘application/pdf’). include_subfolders (optional) - ‘Y’ to include files from subfolders recursively. Default ‘N’. max_results (optional) - Maximum number of results (default 50).

Signature:

function list_files (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object with the parameters

Returns: clob - JSON array of document objects

---

get_file_details

Gets detailed information about a specific document including versions, tags, annotations, and comments. Only returns data if the user has access to the document.

Parameters (JSON): document_id (optional) - ID of the document. document_path (optional) - Full path of the document (folder_path + ’/’ + document_name).

Signature:

function get_file_details (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object with the parameters

Returns: clob - JSON object with document details

---

get_folder_details

Gets detailed information about a specific folder including annotations and statistics. Only returns data if the user has access to the folder.

Parameters (JSON): folder_path (optional) - Path of the folder. folder_id (optional) - ID of the folder. Alternative to folder_path.

Signature:

function get_folder_details (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object with the parameters

Returns: clob - JSON object with folder details

---

search_files

Searches documents the user has access to using full-text search. Supports multiple search expressions to search with different keywords in a single call. Results from all expressions are combined and deduplicated, keeping the highest score per document.

Parameters (JSON): search_expressions (required) - Array of full-text search expressions. Example: [“hotel booking”, “reservation”, “accommodation”] folder_path (optional) - Restrict search to this folder path and its subfolders. max_results (optional) - Maximum number of results (default 20).

Signature:

function search_files (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object with the parameters

Returns: clob - JSON array of matching documents with scores

---

read_file_content

Reads the text content of a document version. Only works for documents that have indexed text content (index_content). Only returns data if the user has access to the document.

Parameters (JSON): document_id (optional) - ID of the document (reads latest version). document_path (optional) - Full path of the document. version_id (optional) - Specific version ID to read. version_number (optional) - Specific version number (requires document_id or document_path). max_length (optional) - Maximum characters to return (default 10000). offset (optional) - Character offset to start reading from (default 0).

Signature:

function read_file_content (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object with the parameters

Returns: clob - JSON object with text content and metadata

---

get_current_view

Reports what the user is currently looking at in the <adm-file-browser> region: the folder they have open and the rows they have selected.

The model supplies nothing. Both values are read from the UC AI run context under the reserved _ctx key, which the model can neither see nor set:

fs_page_id (required) - the APEX page the file browser region sits on. The item names follow from it (P<page>_FS_FOLDER_ID and the two selection items), so the caller binds one stable value instead of three item names. fs_folder_item, fs_selected_docs_item, fs_selected_folders_item (optional) - name an item outright, overriding the convention. The component takes its own item names from config.itemNames, so an install may rename them; these keep this tool working when one does.

The values themselves are read from APEX session state at call time, not from the run context, because the folder changes as the user navigates and a run-context key is frozen on the first turn of a conversation. That needs a live APEX session: the chat plug-in’s Session Init Code has to apex_session.attach first, or every item reads as null and this returns has_view: false.

Every id read from an item is re-resolved against the caller’s own permissions before it is reported. Those items are value_protected => 'N' and therefore user-writable, so a forged id must not become a document the model can read - it is dropped instead.

Signature:

function get_current_view (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object; only the _ctx entry is read

Returns: clob - JSON object with the current folder, the selected documents and folders

---

resolve_view

The authorization half of get_current_view, split out from the APEX half.

Takes the three raw item values and answers the same JSON. get_current_view reads the items with v() and hands them straight here, so this is where every id is resolved and every unauthorized one is dropped.

It is public because that dropping is the security-critical part and reading a page item needs a live APEX session, which a test cannot create for an item the application does not define. Splitting it means the rule can be tested directly with forged ids.

Signature:

function resolve_view (
  p_folder_id_raw in varchar2,
  p_doc_ids_raw in varchar2 default null,
  p_folder_ids_raw in varchar2 default null
) return clob;

Parameters:

Name	Direction	Type	Description
p_folder_id_raw	in	varchar2	The current-folder item’s value; a single id
p_doc_ids_raw	in	varchar2 default null	The selected-documents item’s value; colon separated
p_folder_ids_raw	in	varchar2 default null	The selected-folders item’s value; colon separated

Returns: clob - JSON object with the resolved folder, documents and folders

---

search_document

Semantic (vector) search inside ONE document, for an agent bound to that document.

Parameters (JSON): query (required) - what to look for in the document.

The document is NOT a parameter. It is read from _ctx.document_id, so the model cannot name a document at all and there is exactly one place the value can come from. A run that carries no document id gets a readable error string back rather than an exception, because the model has to be able to act on it.

Needs the document to be in a RAG collection backed by the native Oracle vector store. Falls back to nothing: when the document is in no collection the tool says so, and the agent is expected to use read_document_content instead.

Signature:

function search_document (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object with the parameters

Returns: clob - JSON object with the matching passages

---

read_document_content

Reads the text of the document the run is bound to, with paging.

Parameters (JSON): max_length (optional) - Maximum characters to return (default 10000). offset (optional) - Character offset to start reading from (default 0).

As with search_document, the document comes from _ctx.document_id and is absent from the parameters.

Signature:

function read_document_content (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object with the parameters

Returns: clob - JSON object with text content and metadata

---

get_document_details

Metadata for the document the run is bound to: versions, tags, annotations, comments. The document comes from _ctx.document_id.

Signature:

function get_document_details (
  p_parameters in clob
) return clob;

Parameters:

Name	Direction	Type	Description
p_parameters	in	clob	JSON object; only the _ctx entry is read

Returns: clob - JSON object with document details

---