AI agent tools

The AI Pack ships six read-only tools that expose ADM to an LLM agent: browse the folder tree, search document content, read a document’s text. They are registered with uc_ai at install time, so an agent can use them without any code of yours.

Every tool runs as the current user

The tools read the identity from the session context and filter results to what that user is allowed to see. An agent cannot be talked into revealing a document its user has no access to, because the access check happens in SQL, below the model. If a tool returns nothing, the item either does not exist or the user cannot see it. See The security model.

The tools

Tool code	Does	Key parameters
ADM_LIST_FOLDERS	Lists subfolders, with counts	folder_path or folder_id, search_terms[], max_results
ADM_LIST_FILES	Lists documents in a folder	folder_path/folder_id, search_terms[], mime_type, include_subfolders, max_results
ADM_GET_FOLDER_DETAILS	One folder’s metadata, annotations and statistics	folder_path or folder_id
ADM_GET_FILE_DETAILS	One document’s versions, tags, annotations and comments	document_id or document_path
ADM_SEARCH_FILES	Full-text search over document content	search_expressions[]
ADM_READ_FILE_CONTENT	The indexed text of a document, paginated	document_id/document_path, offset, max_length

All six are functions on adm_ai_agent_tools_api that take a JSON clob and return a JSON clob, so they are equally usable outside an agent:

select adm_ai_agent_tools_api.list_files('{
  "folder_path": "/groups/finance"
, "include_subfolders": "Y"
, "mime_type": "application/pdf"
, "max_results": 20
}') from dual;

Ids are strings in these payloads

ADM ids are up to 32 decimal digits, well past what a JSON number survives. The tools return ids as strings, and expect them back unchanged. Never let an agent — or your own glue code — round-trip one through a numeric type.

ADM_READ_FILE_CONTENT returns the indexed text, not the file. A document whose text was never extracted returns “no text content available”, and retrying with different parameters does not change that. See how content becomes searchable.

The bundled assistant

Installing the AI Pack also registers a ready-made assistant that uses all six tools:

• A uc_ai prompt profile ADM_DOC_ASSISTANT, with a system prompt written for document retrieval, tools enabled and up to 30 tool calls per run.
• A profile agent adm_doc_assistant, executable through uc_ai_agents_api.execute_agent and tracked in uc_ai_agent_executions.

The tools are tagged adm_ai_assistant, which is how the profile selects them — so adding a tool with that tag makes it available to the assistant without touching the profile.

Choosing the provider and model

The profile ships pointed at OpenAI’s gpt-5.4, which suits our testing and not necessarily yours. uc_ai speaks to OpenAI, Anthropic, Google, Ollama, OCI, xAI, OpenRouter and Mistral, and the choice is a setting rather than an edit to the install script:

Setting
AI_AGENT_PROVIDER	openai, anthropic, google, ollama, oci, xai, openrouter, mistral, responses_api
AI_AGENT_MODEL	the model id, e.g. claude-sonnet-4-6
AI_AGENT_WEB_CREDENTIAL_ID	the APEX Web Credential holding that provider’s key; empty when it needs none
AI_AGENT_REASONING_LEVEL	NONE, LOW, MEDIUM, HIGH; empty keeps the profile’s own
AI_AGENT_MODEL_CONFIG	optional JSON merged over the rest

All five are empty on a fresh install, and while AI_AGENT_PROVIDER is empty ADM writes nothing — the profiles stay exactly as the install built them, or as you shaped them yourself. Setting a provider hands them over.

Set them in Administration → Settings, or from SQL — either way a trigger writes them into both shipped profiles, so the next agent run uses them:

-- Anthropic, with a bigger response budget
update adm_settings set sett_value = 'anthropic'         where sett_key = 'AI_AGENT_PROVIDER';
update adm_settings set sett_value = 'claude-sonnet-4-6' where sett_key = 'AI_AGENT_MODEL';
update adm_settings set sett_value = 'ANTHROPIC'         where sett_key = 'AI_AGENT_WEB_CREDENTIAL_ID';
update adm_settings set sett_value = '{"anthropic":{"g_max_tokens":8192}}'
 where sett_key = 'AI_AGENT_MODEL_CONFIG';
commit;

-- A local Ollama: no credential, no reasoning, a base url of its own
update adm_settings set sett_value = 'ollama'   where sett_key = 'AI_AGENT_PROVIDER';
update adm_settings set sett_value = 'llama3.1' where sett_key = 'AI_AGENT_MODEL';
update adm_settings set sett_value = null       where sett_key = 'AI_AGENT_WEB_CREDENTIAL_ID';
update adm_settings set sett_value = 'NONE'     where sett_key = 'AI_AGENT_REASONING_LEVEL';
update adm_settings set sett_value = '{"g_base_url":"http://localhost:11434"}'
 where sett_key = 'AI_AGENT_MODEL_CONFIG';
commit;

Only the model-related parts of a profile are rewritten. The system prompt, the tool tags — including the one uc_ai_memory adds, so agent memory survives — and the tool-call limit are left alone. An unusable value is refused as you save it, not at the first agent run.

The five settings are a subset

They cover what an ADM administrator normally changes. uc_ai accepts a good deal more in a model config — base urls, extra headers and request body properties, programmatic tool calling, per-provider sections such as Anthropic’s g_max_tokens or Google’s reasoning budget — and all of it goes through AI_AGENT_MODEL_CONFIG verbatim. The UC AI documentation is the reference for what that JSON takes, which providers and models are supported, and how credentials are set up per provider.

Or take the profiles over entirely

Empty AI_AGENT_PROVIDER and ADM stops writing to the profiles altogether: they are then yours to shape through uc_ai_prompt_profiles_api, and nothing here will overwrite you. Put a provider back in the setting, or call adm_ai_agent_profile_api.apply_model_settings, to hand them back.

What the assistant is instructed to do

• Answer only from tool results. Its own training knowledge is off-limits for content. Asked a general programming question, it searches your documents for the answer rather than answering from memory — and says it found nothing if it did not.
• Search broadly, in short keywords. Oracle Text matches single words best, so the prompt pushes several short synonyms in one call rather than one long phrase, and alternate spellings (PLSQL, PL/SQL) where both occur.
• Disambiguate rather than guess. Several plausible matches are presented for the user to choose between, not silently narrowed to one.
• Cite the path of every document it answers from.
• Refuse to write. The tools are read-only, and the prompt tells it to say so and point at the UI.

Building your own agent

Use the tools as they are and write your own profile when you want different behaviour — a narrower scope, a different tone, a mix of ADM tools and tools of your own. Register your profile with uc_ai_prompt_profiles_api, and select the ADM tools by the adm_ai_assistant tag or by their individual codes.

If you need something the six tools cannot do, call the ADM APIs from a tool of your own rather than querying tables: the access control functions keep an agent inside its user’s permissions.

Retrieval and RAG are different things

These tools search and read documents directly. A RAG collection embeds chunks and searches them semantically. Tools suit “find the file and read it”; RAG suits “answer this question from across many documents”. Both can be used in the same agent.

Also refer to

• RAG configurations
• Installing the AI Pack
• adm_ai_agent_tools_api
• adm_ai_agent_profile_api — what the AI_AGENT_* settings write into the profiles
• Settings reference
• UC AI documentation — providers, models, credentials and the full model-config surface behind AI_AGENT_MODEL_CONFIG