Package com.oracle.database.selectai.agent

Interface Tool

public interface Tool
Contract for Select AI agent tool lifecycle, description, and execution operations.

A tool is a database-side resource managed by the DBMS_CLOUD_AI_AGENT PL/SQL package. Tools expose callable functionality to agents or teams and may define an input schema.

A Tool instance can represent an existing database tool or be configured for creation. The name-only SelectAIAgent.tool(String) factory verifies that the tool exists and loads its metadata and attributes before returning. SelectAIAgent.listTools() also returns handles with loaded metadata and attributes. A handle configured for creation is obtained with SelectAIAgent.tool(String, ToolAttributes, String, ToolStatus).

A creation-configured handle retains its supplied attributes, description, and status without querying the database. Only such a handle can call create(); after creation succeeds, it becomes database-backed. enable(), disable(), drop(boolean), describe(), and run(String) require an existing database-side tool. Existing tools can update individual attributes with setAttribute(String, String) or multiple attributes with setAttributes(ToolAttributes); both operations reload the typed attributes after the database update succeeds.

Before creation, getStatus() and getToolAttributes() return the configured values. For a database-backed handle, each call to either method queries the database. getStatus() does not change the description returned by getDescription(). The description is supplied or loaded when the handle is initialized; getDescription() does not query the database. Use describe() to retrieve the database-generated tool definition.

Names and required Java arguments are checked locally. Loading metadata and executing tool operations require database access; the database checks privileges and validates tool attributes when they are submitted. The input supplied to run(String) must be a JSON payload accepted by the configured tool; the Java method checks only that it is not null or blank.

For a complete runnable example, see CreateToolSample source.

Since:
1.1.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    create()
    Creates this creation-configured tool in the database.
    String
    describe()
    Returns the database-generated tool definition and input metadata as raw JSON.
    boolean
    disable()
    Disables this database-backed tool.
    boolean
    drop(boolean force)
    Drops this database-backed tool.
    boolean
    enable()
    Enables this database-backed tool.
    String
    getDescription()
    Returns the description supplied or loaded when this handle was initialized.
    ToolStatus
    getStatus()
    Returns the configured status before creation or the current database status for an existing tool.
    ToolAttributes
    getToolAttributes()
    Returns tool attributes for this handle.
    String
    getToolName()
    Returns the configured or database-reported tool name without database access.
    ToolRunResult
    run(String inputJson)
    Runs this tool with a JSON input payload.
    boolean
    setAttribute(String attributeName, boolean attributeValue)
    Updates one boolean tool attribute in the database.
    boolean
    setAttribute(String attributeName, Float attributeValue)
    Updates one floating-point tool attribute in the database.
    boolean
    setAttribute(String attributeName, Integer attributeValue)
    Updates one integer tool attribute in the database.
    boolean
    setAttribute(String attributeName, String attributeValue)
    Updates one tool attribute in the database.
    boolean
    setAttributes(ToolAttributes toolAttributes)
    Updates multiple tool attributes in one database operation.