Create and Manage Agents

Create an Agent

DBMS_AI_AGENT.CREATE_AGENT validates and stores a complete Agent Spec under a database name without executing it. The procedure accepts the stored name and the specification as a CLOB, including the top-level executable component and all referenced components; the stored name is independent of internal component IDs, names, and references. Successful validation covers document structure, supported components, references, graph connections, and input/output contracts, after which the agent can be executed later with DBMS_AI_AGENT.EXECUTE_AGENT.

Execute an Agent

DBMS_AI_AGENT.EXECUTE_IMMEDIATE runs a complete Agent Spec supplied for one call, while DBMS_AI_AGENT.EXECUTE_AGENT runs a specification previously stored by name with CREATE_AGENT. Both functions accept execution inputs as a JSON CLOB array of name/value pairs, return output values as a JSON CLOB based on the top-level component’s output contract, and optionally provide execution traces through an OUT CLOB. Input names must exactly match declared input titles and values must conform to their declared types; immediate execution does not persist the specification, whereas stored agents remain available for subsequent calls.

List and Describe Agents

DBMS_AI_AGENT.LIST_AGENTS returns a JSON array describing stored agents visible to the current user, while DBMS_AI_AGENT.DESCRIBE_AGENT returns the corresponding description for one named agent. Both read-only procedures use CLOB OUT parameters and report metadata such as the stored name, creation time, description, top-level inputs and outputs, and the JSON call contract requiring name/value input pairs. Listing returns an empty array when no visible agents exist, and describing an unknown or inaccessible agent produces an error.

Delete an Agent

DBMS_AI_AGENT.DELETE_AGENT permanently removes a stored Agent Spec identified by the database name assigned during creation. The procedure accepts only the stored agent name, returns no execution result on success, and makes the name unavailable to execution and description APIs. Deletion affects only the stored agent specification; referenced database objects, credentials, tables, indexes, retrieval resources, model endpoints, procedures, and external services remain unchanged.
Read More: Delete an Agent