18.9.4.3 Managing AI Agents and AI Tools

Create AI Agents and AI Tools to enable richer interactions with Generative AI services.

Parent topic: Including Generative AI in Applications

18.9.4.3.1 About AI Agents and AI Tools

Learn about AI Agents and AI Tools.

An AI Agent is a shared component that centralizes key Generative AI settings, including the System Prompt, Welcome Message, and AI Tools. Creating an AI Agent enables the reusability of these settings across multiple AI-enabled components such as Show AI Assistant and Generate Text With AI dynamic actions. You can also use AI Agents with PL/SQL APIs available in the APEX_AI package.

About AI Agents

An AI Agent contains the following:

  • Name - Identifies the AI Agent in the App Builder UI.
  • Static ID - Use this ID to reference the AI Agent in the APIs in the APEX_AI package.
  • Service - Refers to the AI Service to be used by the AI Agent. By default, the Application Default is used.
  • System Prompt - Initial instructions or context for the AI Service.
  • Welcome Message - The first message shown by the AI Assistant. Note that only components with a UI, such as Show AI Assistant, can utilize this setting.
  • Temperature - Sets the level of randomness or predictability of the generated content.
  • System Prompt Augmentation Tools - Tools called on each request and used to augment the above-defined System Prompt.
  • On Demand Tools - Tools called by the AI Service only when needed, either to fetch data or perform tasks.
  • Response Format Type - Determines whether the AI Assistant returns plain text or a JSON object.

See Also:

APEX_AI in Oracle APEX API Reference

Parent topic: Managing AI Agents and AI Tools

18.9.4.3.2 Creating an AI Agent

Create an AI Agent in Shared Components on the Generative AI Agents page.

Tip:

Before you can create an AI Agent, you must define a Generative AI Service and create an application. See Managing Generative AI Services and Creating Applications.

To create an AI Agent:

  1. Navigate to the Generative AI Agent page:
    1. On the Workspace home page, click the App Builder icon.
    2. Select the application.
    3. On the Application Home page, click Shared Components.
      The Shared Components page appears.
    4. Under Generative AI and click AI Agents.
      The Generative AI Agents page appears.
  2. Click Create.
    The Create / Edit page appears.
  3. Configure the AI Agent attributes:
    1. Identification, Name - Enter the name of the AI Agent.
    2. Generative AI, Service - Select the Generative AI Service to be used by the AI Agent. By default, the Application Default is used.
    3. Generative AI, System Prompt - Specify the initial instructions or context for the AI service. A well-crafted system prompt guides the AI's behavior and sets the tone for its responses. See item Help for more details.
    4. Generative AI, Welcome Message - Enter optional welcome message shown by the AI Assistant, for example:

      How may I help you today?

      To learn more about support for server-side template directives, see item Help.

    5. Response Format, Type - Select the type of response that should be generated by the AI provider. Options include:
      • Text - Choose Text if the AI Service should return plain text answers. Such Agents can be used by the Show AI Assistant and Generate Text With AI components, as well as programatically using the APEX_AI APIs.
      • JSON Object - Choose JSON Object and specify a JSON Schema if the AI Service should respond with a structured output, adhering to a specific schema. Such Agents can currently only be used with the APEX_AI APIs.

        To see a JSON Schema example, see item Help. For more information on JSON Schemas, see the JSON Schema documentation.

    6. Advanced, Static ID - Unique Static ID that identifies this component in API calls or functions as a reference in application export files. If you change the Static ID, dependent components will retain their references, but any existing API calls using the old ID must be updated manually.
    7. Advanced, Temperature - Specify the creativity and randomness of the responses. A lower temperature makes the output more focused, deterministic, and conservative, favoring common or predictable answers. A higher temperature increases the models creativity, making it more likely to produce varied and less conventional responses. Adjust the temperature based on the desired balance between precision and creativity in the responses.

      Temperature may vary depending on the AI Provider. Oracle recommends the temperature values of the AI Service be evaluated when choosing the appropriate value.

    8. Advanced, Comments - Enter comments or notes.
    9. Click Create.

    Once you create an AI Agent, you can continue to edit it or create a AI Tool are used by the Generative AI Service to improve response quality by providing relevant information

To create a AI Tool:

  1. To create a AI Tool, click the Tools tab.
  2. Click Add Tool.
    Generative AI Tool page appears.
  3. Configure the AI Tool.
  4. Under Identification:
    1. Identification, Name - Provide the name of the tool. By convention, tool names are written in lowercase, and underscore separated. The tool name must only contain letters, numbers and underscores, and must start with a letter, for example send_invoice.
    2. Identification, Type - Provide the type of tool. The built-in types, Retrieve Data, Execute Server-side Code and Execute Client-side Code are generic tools that can be used to achieve most use cases.

      Note:

      You can create custom and reusable Generative AI Tool plug-ins under Shared Components
    3. Identification, Execution Point - Specify the execution point of the tool. Augment System Prompt tools are run with each new message. On Demand tools are only run when requested by the AI Service
    4. (On Demand only) Identification, Description - Provide a description for the tool, including its purpose, expected parameters, and return value.
  5. (On Demand only) Under Parameters - Define any parameters the AI Service should provide when calling the tool. For more information, see item- level Help.

    To add parameters:

    • Click Add Parameter.
    • Enter the columns: Parameter Name, Descriptions, Data Type, Required, and Allowed Values.
  6. Under Settings, set the tool-specific settings. The example below is for Retrieve Data.
    1. Settings, Data Description - Enter a brief description of the data that will be sent to the AI service. This description should clearly explain the nature and content of the data being provided, helping the AI to better understand and process the information.
    2. Settings, Type - Select the source type of the data. Options include:
      • SQL Query - Data is sourced from a SQL Query from the local database.
      • Function Body - Data is sourced from a Function Body that returns a CLOB.
      • Static - User-defined static text, suitable for entering hard-coded text information that is not sourced from your database.

      Depending upon your selection, enter the SQL Query, Function Body, or text in the Code Editor. See item Help adjacent to the Code Editor to learn more and view examples for each option.

    3. Settings, Maximum Tokens - Only displays if Type is SQL Query. Specify the maximum number of tokens produced by this tool. If a row exceeds the remaining token limit, it will be entirely skipped to ensure the response stays within the specified token count.

      Note:

      The token calculation is only an approximate estimate of the exact calculation used by the AI service.
  7. (On Demand only) Under User Approval, Requires Confirmation - Specify whether users are required to approve the tool before it runs.
  8. (On Demand only) Under Notification:
    1. Notification, Message - Specify an optional notification to be displayed once the tool has completed. For more information, see item-level Help.
    2. Notification, Type - Specify the type of notification.
  9. Server-Side Condition, Type - Select a condition type that must be met in order for the Augment System Prompt tool to be executed, or the On Demand tool to be made available to the AI Service.

    For the condition types Any User Prompt contains and Last User Prompt contains, provide a comma-separated list of words to check for in the user's prompt.

    You can use the following special bind variables to access and evaluate the user's prompt:

    • APEX$AI_LAST_USER_PROMPT - Contains the most recent user-entered prompt.
    • APEX$AI_ALL_USER_PROMPTS - Contains all user prompts, concatenated into a single string.
  10. Security, Authorization Scheme - Optionally select an authorization scheme which must evaluate to TRUE in order for the Augment System Prompt tool to execute or the On Demand tool to be made available to the AI Service.
  11. Advanced, Static ID - Enter a unique Static ID to identify this component in API calls or refer to it in application export files.
  12. Agent, Build Option - Select a build option for this component
  13. Comments, Comments - Enter any comments or notes.
  14. Click Create.

Related Topics

Parent topic: Managing AI Agents and AI Tools

18.9.4.3.3 Editing or Deleting an AI Agent

Edit or delete an AI Agent or AI Tool from the Generative AI Agents page.

To edit or delete an AI Agent or AI Tool:

  1. Navigate to the AI Agent page:
    1. On the Workspace home page, click the App Builder icon.
    2. Select the application.
    3. On the Application Home page, click Shared Components.
      The Shared Components page appears.
    4. Under Generative AI and click AI Agents.
      The Generative AI Agents page appears.
  2. To edit an AI Agent:
    1. On the Generative AI Agents page, click the agent Name.

      The Create / Edit page appears.

    2. Edit the appropriate attributes. To learn more about a specific attribute, see item Help.
    3. Click Apply Changes.
  3. To delete an AI Agent:

    Tip:

    If an AI Agent is in use, you cannot delete it.
    1. On the Generative AI Agents page, click the agent Name.
    2. Click Delete.
    3. Confirm your selection and click Delete again.
  4. To edit a AI Tool:
    1. On the Generative AI Agents page, click the AI Agent Name.
    2. Under Tools, click the AI Tool name.

      The AI Tool page appears.

    3. Edit the appropriate attributes. To learn more about a specific attribute, see item Help.
    4. Click Apply Changes.
  5. To delete a AI Tool:
    1. On the Generative AI Agents page, click the AI Agent Name.
    2. Under Tools, click the AI Tool name.

      The AI Tool page appears.

    3. Click Delete.
    4. Confirm your selection and click Delete again.

Parent topic: Managing AI Agents and AI Tools

18.9.4.3.4 Copying or Subscribing to an AI Agent

Copy an AI Agent from the current application or from another application. When copying an AI Agent from another application, you can also subscribe to it.

To copy an AI Agent:

  1. Navigate to the AI Agent page:
    1. On the Workspace home page, click the App Builder icon.
    2. Select the application.
    3. On the Applicatioin Home page, click Shared Components.
      The Shared Components page appears.
    4. Under Generative AI and click AI Agents.
      The Generative AI Agents page appears.
  2. Find the AI Agent and click Copy.
  3. Copy From - Choose where to copy the AI Agent from. Options include:
    • This Application
    • Other Application
  4. To copy from the current application:
    1. Copy From - Select This Application.
    2. Copy Agent - Select the agent to copy.
    3. Name - Enter the name of the agent you would like to create.
    4. Click Copy.
  5. To copy from another application:
    1. Copy From - Select Other Application.
    2. Application - Select the application from which you want to copy.
    3. Copy Agent - Select the agent to copy.
    4. Subscribe - Enable Subscribe to subscribe to the agent.
    5. Click Copy.

Related Topics

Parent topic: Managing AI Agents and AI Tools

18.9.4.3.5 Viewing AI Agent Utilization

View a report that details where AI Agents are used within the current workspace.

To view the AI Agents Utilization report:

  1. Navigate to the Generative AI Services page:
    1. On the Workspace home page, click the App Builder icon.
    2. Select the application.
    3. On the Application Home page, click Shared Components.
      The Shared Components page appears.
    4. Under Generative AI and click AI Agents.
      The Generative AI Agents page appears.
  2. On Generative AI Agents page, click Utilization.

    The Generative AI Agents Utilization report appears.

Parent topic: Managing AI Agents and AI Tools

18.9.4.3.6 Viewing AI Agent History

View a report of recent modifications made to AI Agents in this workspace.

To view the AI Agents History report:

  1. Navigate to the Generative AI Services page:
    1. On the Workspace home page, click the App Builder icon.
    2. Select the application.
    3. On the Application Home page, click Shared Components.
      The Shared Components page appears.
    4. Under Generative AI and click AI Agents.
      The Generative AI Agents page appears.
  2. On the Generative AI Agents page, click History.

    The Generative AI Agents History report appears.

Parent topic: Managing AI Agents and AI Tools