Quickstart

This guide takes you from a new installation to a working AI agent in three steps. The examples cover text generation and tool calls. The Tools and Agentic AI guides provide more detail.

Note

The Glossary explains the terms token, tool, and structured output.

Before you start

• UC AI is installed in your schema.
• You have an API key for one provider, in the uc_ai_get_key function or in an APEX Web Credential. See Set up API Keys.

The examples use OpenAI, but every provider works. To change the provider, replace the p_provider and p_model constants.

1. Say hello

   The smallest useful call sends a prompt and gets text back. Run this in your SQL client with set serveroutput on.

   set serveroutput on
   declare
     l_result json_object_t;
   begin
     l_result := uc_ai.generate_text(
       p_user_prompt => 'In one sentence, what is Oracle APEX?',
       p_provider    => uc_ai.c_provider_openai,
       p_model       => uc_ai_openai.c_model_gpt_5_6_luna
     );
   
     dbms_output.put_line(l_result.get_clob('final_message'));
   end;
   /

   If the output shows a sentence, your provider and your key are correct.

2. Give the AI a tool

   Alone, the model knows only its training data. A tool is a PL/SQL function that the model can call. The model uses a tool to get live information, or to do an action. This step creates a tool that returns the current date.

   First, create the function. It takes no input and returns a CLOB, because the AI communicates in text:

   create or replace function get_today
     return clob
   as
   begin
     return 'The current date is ' || to_char(sysdate, 'YYYY-MM-DD Dy');
   end;
   /

   Then register it as a tool so the model knows it exists:

   declare
     l_tool_id uc_ai_tools.id%type;
   begin
     l_tool_id := uc_ai_tools_api.create_tool_from_schema(
       p_tool_code     => 'GET_TODAY',
       p_description   => 'Returns the current date. Use this whenever you need to know today''s date.',
       p_function_call => 'return get_today();',
       p_json_schema   => null,   -- this tool takes no parameters
       p_tags          => apex_t_varchar2('demo')
     );
     commit;
   end;
   /

   Tip

   p_json_schema => null means that the tool has no parameters. A tool that needs input describes the input with a JSON schema. Its function then reads the values from a CLOB parameter.

3. Watch the AI use it

   Now ask a question that the model can answer only with your tool. One flag enables tools:

   set serveroutput on
   declare
     l_result json_object_t;
   begin
     uc_ai.g_enable_tools := true;              -- allow tool use
     uc_ai.g_tool_tags := apex_t_varchar2('demo');  -- only offer our demo tool
   
     l_result := uc_ai.generate_text(
       p_user_prompt => 'What day of the week is it today?',
       p_provider    => uc_ai.c_provider_openai,
       p_model       => uc_ai_openai.c_model_gpt_5_6_luna
     );
   
     dbms_output.put_line(l_result.get_clob('final_message'));
     -- e.g. "Today is a Wednesday."
   end;
   /

   Internally, the model decided that it needed the date. It called GET_TODAY, read the result, and answered in plain language. This loop — reason, call a tool, use the result — is the core of an agent.

Agent execution

The model requested GET_TODAY and used its result to answer the question. The PL/SQL tool runs in your database. OpenAI processes the model requests.

Where to go next

• Build a complete agent — the Build an Agent tutorial takes this loop to an agent that reads your tables, checks business rules before writing a row, and records every run. Seven lessons, with recorded output.
• Give it real data — register tools that query your tables. See the Tools guide.
• Get structured results — force JSON output you can insert into columns with the Structured Output guide.
• Reuse prompts — manage versioned prompt templates with Prompt Profiles.
• Build bigger agents — orchestrate multi-step and multi-agent workflows in Agentic AI.
• Browse ideas — see the Use Cases page.