List and Describe Agents

DBMS_AI_AGENT.LIST_AGENTS returns descriptions of the stored agents visible to the current user. DBMS_AI_AGENT.DESCRIBE_AGENT returns the description of one stored agent identified by name.

Both procedures are read-only. They return JSON through CLOB output parameters and do not execute or modify an Agent Spec.

LIST_AGENTS

Syntax

DBMS_AI_AGENT.LIST_AGENTS (
    AGENTS OUT CLOB
);

Parameter

Parameter	Description
AGENTS	Receives a JSON array containing descriptions of the stored agents visible to the current user.

Example

The following example lists the stored agents visible to the current user and displays the first 32,767 characters of the returned CLOB:

SET SERVEROUTPUT ON

DECLARE
  L_AGENTS CLOB;
BEGIN
  DBMS_AI_AGENT.LIST_AGENTS (
    AGENTS => L_AGENTS
  );

  DBMS_OUTPUT.PUT_LINE (
    DBMS_LOB.SUBSTR (L_AGENTS, 32767, 1)
  );
END;
/

When no stored agents are visible to the current user, the procedure returns an empty JSON array.

When stored agents are available, the array contains one description object for each agent. For example, after completing the Create an Agent example, the result includes a description for ORDER_REQUEST_FLOW:

[
  {
    "name": "ORDER_REQUEST_FLOW",
    "create_time": "2026-08-20T12:34:56",
    "description": null,
    "inputs": [
      {
        "title": "order_id",
        "type": "string"
      }
    ],
    "outputs": [
      {
        "title": "order_id",
        "type": "string"
      }
    ],
    "call_contract": {
      "input_format": "json_array_name_value_pairs",
      "required_keys": ["name", "value"],
      "name_matches": "inputs[].title (exact match)"
    }
  }
]

The actual creation timestamp reflects when the stored agent was created. The array can also contain other agents visible to the current user, and their order is not guaranteed.

DESCRIBE_AGENT

Syntax

DBMS_AI_AGENT.DESCRIBE_AGENT (
    AGENT_NAME    IN VARCHAR2,
    AGENT_DETAILS OUT CLOB
);

Parameters

Parameter	Description
AGENT_NAME	Specifies the database name assigned when the Agent Spec was stored.
AGENT_DETAILS	Receives a JSON object describing the stored agent.

Example

The following example describes the ORDER_REQUEST_FLOW stored by the creation example:

SET SERVEROUTPUT ON

DECLARE
  L_AGENT_DETAILS CLOB;
BEGIN
  DBMS_AI_AGENT.DESCRIBE_AGENT (
    AGENT_NAME    => 'ORDER_REQUEST_FLOW',
    AGENT_DETAILS => L_AGENT_DETAILS
  );

  DBMS_OUTPUT.PUT_LINE (
    DBMS_LOB.SUBSTR (L_AGENT_DETAILS, 32767, 1)
  );
END;
/

The procedure returns one description object rather than the array returned by LIST_AGENTS:

{
  "name": "ORDER_REQUEST_FLOW",
  "create_time": "2026-08-20T12:34:56",
  "description": null,
  "inputs": [
    {
      "title": "order_id",
      "type": "string"
    }
  ],
  "outputs": [
    {
      "title": "order_id",
      "type": "string"
    }
  ],
  "call_contract": {
    "input_format": "json_array_name_value_pairs",
    "required_keys": ["name", "value"],
    "name_matches": "inputs[].title (exact match)"
  }
}

The procedure reports an error when AGENT_NAME does not identify a stored agent visible to the current user.

Returned Information

LIST_AGENTS and DESCRIBE_AGENT use the same stored-agent description structure:

JSON member	Description
name	Contains the stored database name accepted by EXECUTE_AGENT, DESCRIBE_AGENT, and DELETE_AGENT.
create_time	Contains the time at which the stored agent was created.
description	Contains the description from the top-level Agent Spec component, or null when no description was supplied.
inputs	Contains the input declarations of the top-level executable component.
outputs	Contains the output declarations of the top-level executable component.
call_contract	Describes the JSON input structure expected by the execution APIs.