Agent Catalog and Runtime Statistics Views

Oracle AI Database provides catalog views for inspecting stored agents and dynamic performance views for examining Agent Spec execution activity.

View	Purpose
`USER_AI_AGENTS`	Describes the stored agents owned by the current user.
`DBA_AI_AGENTS`	Describes stored agents across the database.
`V$AGENT_EXEC_STAT`	Reports execution statistics collected on the current database instance.
`GV$AGENT_EXEC_STAT`	Reports the corresponding execution statistics across database instances.

View Stored Agents

USER_AI_AGENTS

USER_AI_AGENTS describes the stored agents owned by the current user. Each row represents one stored Agent Spec created through DBMS_AI_AGENT.CREATE_AGENT.

The following query lists the current user's stored agents and their creation times:

SELECT agent_id,
       agent_name,
       create_time
FROM   user_ai_agents
ORDER  BY agent_name;

USER_AI_AGENTS contains the following columns:

Column	Data type	Description
`AGENT_ID`	`NUMBER`	Unique identifier for the stored agent.
`AGENT_NAME`	`VARCHAR2(128)`	Name assigned to the stored agent. This is the name supplied to stored-agent management and execution APIs.
`CREATE_TIME`	`DATE`	Date and time at which the agent was created.
`INPUTS`	`CLOB`	JSON input schema for executing the stored agent.
`OUTPUTS`	`CLOB`	JSON output schema produced by the stored agent.

For example, the following query displays the call contract for one stored agent:

SELECT agent_name,
       inputs,
       outputs
FROM   user_ai_agents
WHERE  agent_name = 'ORDER_ASSISTANT';

DBA_AI_AGENTS

DBA_AI_AGENTS describes stored agents across the database. It contains the same agent identity, creation-time, and call-contract information as USER_AI_AGENTS, together with the owner of each agent. Querying this view requires the applicable catalog privilege. The following query lists stored agents by owner:

SELECT owner,
       agent_id,
       agent_name,
       create_time
FROM   dba_ai_agents
ORDER  BY owner, agent_name;

DBA_AI_AGENTS contains the following columns:

Column	Data type	Description
`AGENT_ID`	`NUMBER`	Unique identifier for the stored agent.
`OWNER`	`VARCHAR2(128)`	Owner of the stored agent.
`AGENT_NAME`	`VARCHAR2(128)`	Name assigned to the stored agent.
`CREATE_TIME`	`DATE`	Date and time at which the agent was created.
`INPUTS`	`CLOB`	JSON input schema for executing the stored agent.
`OUTPUTS`	`CLOB`	JSON output schema produced by the stored agent.

The catalog views describe stored Agent Specs; they do not contain statistics for individual executions. Use the dynamic performance views in the following sections to examine runtime activity.

Runtime Execution Statistics

V$AGENT_EXEC_STAT reports runtime measurements collected for Agent Spec executions on the current database instance. Each row contains node call counts, elapsed times, and LLM token usage accumulated during one execution.

GV$AGENT_EXEC_STAT reports the corresponding rows across database instances.

How Statistics Rows Are Formed

The runtime creates one statistics record after an execution completes successfully. The values in that record are accumulated across the work performed during that execution, including repeated and nested node activity.

The rows are not cumulative summaries of several executions. For example, a row whose AGENT_EXECUTOR_LLM_CALL_COUNT is 3 describes three LLM calls made during one execution; it does not combine one LLM call from each of three executions.

Executions that fail before statistics are recorded do not produce a completed statistics row.

The dynamic performance views expose runtime statistics rather than durable execution history. Rows can change as executions complete and as runtime statistics are managed.

Correlate Statistics with an Execution

The statistics views support workload measurement and performance diagnosis. They do not expose an execution identifier or timestamp that can be used to associate a row reliably with a particular call when several executions are occurring concurrently.

CON_ID identifies the container associated with a row. GV$AGENT_EXEC_STAT additionally exposes INST_ID, which identifies the database instance. These columns provide database context but do not uniquely identify an execution.

In a controlled test environment with no concurrent Agent Engine activity, querying the view immediately before and after one execution can isolate the newly recorded row. When diagnostic information must be associated directly with a particular execution call, request the TRACES output from that call. The trace is returned to the caller that requested it and can therefore be correlated with that execution. For more information, see Tracing.

Query Runtime Statistics

The following query selects commonly used measurements from the current instance:

SELECT con_id,
       agent_executor_llm_call_count    AS llm_calls,
       agent_executor_tool_call_count   AS tool_calls,
       agent_executor_branch_call_count AS branch_calls,
       agent_executor_total_time_exec   AS total_time_ms,
       agent_executor_input_tokens      AS input_tokens,
       agent_executor_output_tokens     AS output_tokens
FROM   v$agent_exec_stat;

A row can have the following form:

CON_ID  LLM_CALLS  TOOL_CALLS  BRANCH_CALLS  TOTAL_TIME_MS  INPUT_TOKENS  OUTPUT_TOKENS
------  ---------  ----------  ------------  -------------  ------------  -------------
     3          2           1             1           1840           640            120

This row records two LLM calls, one tool call, one branching evaluation, 1,840 milliseconds of total execution time, 640 input tokens, and 120 output tokens for one execution in container 3.

Diagnose Execution Performance

The statistics views can identify which category of work accounts for most of an execution's elapsed time. The following query examines executions whose recorded duration exceeded two seconds and compares LLM and ToolNode processing with the total execution time:

SELECT con_id,
       agent_executor_total_time_exec AS total_time_ms,
       agent_executor_total_time_llm  AS llm_time_ms,
       agent_executor_total_time_tool AS tool_time_ms,
       ROUND(
         100 * agent_executor_total_time_llm /
         NULLIF(agent_executor_total_time_exec, 0), 1) AS llm_time_pct,
       ROUND(
         100 * agent_executor_total_time_tool /
         NULLIF(agent_executor_total_time_exec, 0), 1) AS tool_time_pct,
       agent_executor_llm_call_count  AS llm_calls,
       agent_executor_tool_call_count AS tool_calls,
       agent_executor_input_tokens    AS input_tokens,
       agent_executor_output_tokens   AS output_tokens
FROM   v$agent_exec_stat
WHERE  agent_executor_total_time_exec > 2000
ORDER  BY agent_executor_total_time_exec DESC;

A row can have the following form:

CON_ID  TOTAL_TIME_MS  LLM_TIME_MS  TOOL_TIME_MS  LLM_TIME_PCT  TOOL_TIME_PCT  LLM_CALLS  TOOL_CALLS  INPUT_TOKENS  OUTPUT_TOKENS
------  -------------  -----------  ------------  ------------  -------------  ---------  ----------  ------------  -------------
     3           4200         3500           280          83.3            6.7          5           2          8200            640

In this example, LLM processing accounts for most of the recorded execution time. The five LLM calls and 8,200 input tokens indicate that model-call frequency and prompt size are useful areas to examine. A trace from a representative execution can then identify the LlmNode, Agent round, mapped iteration, or nested component responsible for those calls.

The same query supports other diagnoses:

A high ToolNode percentage directs attention to the invoked database procedures, vector searches, or external tool operations.
A high LLM call count can indicate repeated Agent rounds, mapped model calls, or several LLM nodes in one execution.
High input-token usage can indicate that prompts or accumulated Agent context contain more data than the model task requires.
High total execution time with comparatively low LLM and ToolNode time directs attention to other node categories and runtime processing.

The statistics identify the category of work to investigate. The execution trace identifies the component hierarchy and activity for the specific call.

Interpret the Measurements

Node Call Counts

The call-count columns report how many times each node category ran during the execution represented by the row. AGENT_EXECUTOR_BRANCH_DEFAULT_CALL_COUNT reports how many branching evaluations selected the default branch.

Execution Time

Columns whose names begin with AGENT_EXECUTOR_TOTAL_TIME_ report time in milliseconds. AGENT_EXECUTOR_TOTAL_TIME_EXEC reports the total execution time, while the other time columns attribute time to node categories or individual operations.

The component times do not necessarily add up to AGENT_EXECUTOR_TOTAL_TIME_EXEC. Total time can include runtime work that is not attributed to a listed component category. Concurrent work can also overlap in elapsed time.

LLM Token Usage

AGENT_EXECUTOR_INPUT_TOKENS and AGENT_EXECUTOR_OUTPUT_TOKENS report the LLM token usage accumulated during the execution. An execution that does not invoke an LLM does not contribute LLM token usage.

V$AGENT_EXEC_STAT Columns

V$AGENT_EXEC_STAT contains the following columns:

Column	Description
`AGENT_EXECUTOR_LLM_CALL_COUNT`	Number of `LlmNode` calls.
`AGENT_EXECUTOR_TOOL_CALL_COUNT`	Number of `ToolNode` calls.
`AGENT_EXECUTOR_BRANCH_CALL_COUNT`	Number of `BranchingNode` evaluations.
`AGENT_EXECUTOR_BRANCH_DEFAULT_CALL_COUNT`	Number of branching evaluations that selected the default branch.
`AGENT_EXECUTOR_MAP_NODE_CALL_COUNT`	Number of `MapNode` calls.
`AGENT_EXECUTOR_PARALLEL_MAP_NODE_CALL_COUNT`	Number of `ParallelMapNode` calls.
`AGENT_EXECUTOR_START_NODE_CALL_COUNT`	Number of `StartNode` calls.
`AGENT_EXECUTOR_END_NODE_CALL_COUNT`	Number of `EndNode` calls.
`AGENT_EXECUTOR_FLOW_NODE_CALL_COUNT`	Number of `FlowNode` calls.
`AGENT_EXECUTOR_PARALLEL_FLOW_NODE_CALL_COUNT`	Number of `ParallelFlowNode` calls.
`AGENT_EXECUTOR_TOTAL_TIME_LLM`	Time attributed to `LlmNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_TOOL`	Time attributed to `ToolNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_EXEC`	Total execution time, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_START_NODE`	Time attributed to `StartNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_END_NODE`	Time attributed to `EndNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_FLOW_NODE`	Time attributed to `FlowNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_PARALLEL_FLOW_NODE`	Time attributed to `ParallelFlowNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_MAP_NODE`	Time attributed to `MapNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_PARALLEL_MAP_NODE`	Time attributed to `ParallelMapNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BRANCH_NODE`	Time attributed to `BranchingNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_ANSWER`	Time attributed to the get-key-answer operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_ANSWER_FOUND`	Time attributed to the get-key-answer-found operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_INSERT_CURRENT_QUESTION_LIST`	Time attributed to insertion into the current question list, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_QUESTIONS`	Time attributed to the get-key-questions operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_VECTOR_SEARCH_SIMPLIFIED`	Time attributed to the simplified vector-search operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_VECTOR_SEARCH`	Time attributed to the vector-search operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_AND_DEDUPLICATE_CHUNKS_SIMPLIFIED`	Time attributed to simplified chunk merging and deduplication, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_AND_DEDUPLICATE_CHUNKS`	Time attributed to chunk merging and deduplication, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FILTER_ALREADY_RETRIEVED_CHUNKS_SIMPLIFIED`	Time attributed to simplified filtering of previously retrieved chunks, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FILTER_ALREADY_RETRIEVED_CHUNKS`	Time attributed to filtering of previously retrieved chunks, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_QUESTION_LISTS`	Time attributed to merging question lists, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GROUP_CHUNKS`	Time attributed to grouping chunks, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FLATTEN_QUERIES`	Time attributed to flattening queries, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_REMOVE_SOURCE`	Time attributed to removing source information, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_SELECT_CHOICES`	Time attributed to the get-key-select-choices operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FILTER_UNWANTED_CHUNKS`	Time attributed to filtering unwanted chunks, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FLATTEN_CHUNK_LISTS`	Time attributed to flattening chunk lists, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_RETRIEVED_CONTEXT_SIMPLIFIED`	Time attributed to simplified merging of retrieved context, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_RETRIEVED_CONTEXT`	Time attributed to merging retrieved context, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_INC_COUNT`	Time attributed to the legacy increment-count operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_INCREMENT_COUNTER`	Time attributed to the increment-counter operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_FINAL_ANSWER_READY`	Time attributed to checking whether the final answer is ready, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_FEEDBACK`	Time attributed to the get-key-feedback operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_STRINGIFY_VALUE`	Time attributed to conversion of a value to its string representation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_PLSQL_EXEC`	Time attributed to the `plsql_exec` operation, in milliseconds.
`AGENT_EXECUTOR_INPUT_TOKENS`	Number of LLM input tokens.
`AGENT_EXECUTOR_OUTPUT_TOKENS`	Number of LLM output tokens.
`CON_ID`	Identifier of the container associated with the row.

GV$AGENT_EXEC_STAT Columns

GV$AGENT_EXEC_STAT contains the following columns:

Column	Description
`INST_ID`	Identifier of the database instance associated with the row.
`AGENT_EXECUTOR_LLM_CALL_COUNT`	Number of `LlmNode` calls.
`AGENT_EXECUTOR_TOOL_CALL_COUNT`	Number of `ToolNode` calls.
`AGENT_EXECUTOR_BRANCH_CALL_COUNT`	Number of `BranchingNode` evaluations.
`AGENT_EXECUTOR_BRANCH_DEFAULT_CALL_COUNT`	Number of branching evaluations that selected the default branch.
`AGENT_EXECUTOR_MAP_NODE_CALL_COUNT`	Number of `MapNode` calls.
`AGENT_EXECUTOR_PARALLEL_MAP_NODE_CALL_COUNT`	Number of `ParallelMapNode` calls.
`AGENT_EXECUTOR_START_NODE_CALL_COUNT`	Number of `StartNode` calls.
`AGENT_EXECUTOR_END_NODE_CALL_COUNT`	Number of `EndNode` calls.
`AGENT_EXECUTOR_FLOW_NODE_CALL_COUNT`	Number of `FlowNode` calls.
`AGENT_EXECUTOR_PARALLEL_FLOW_NODE_CALL_COUNT`	Number of `ParallelFlowNode` calls.
`AGENT_EXECUTOR_TOTAL_TIME_LLM`	Time attributed to `LlmNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_TOOL`	Time attributed to `ToolNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_EXEC`	Total execution time, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_START_NODE`	Time attributed to `StartNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_END_NODE`	Time attributed to `EndNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_FLOW_NODE`	Time attributed to `FlowNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_PARALLEL_FLOW_NODE`	Time attributed to `ParallelFlowNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_MAP_NODE`	Time attributed to `MapNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_PARALLEL_MAP_NODE`	Time attributed to `ParallelMapNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BRANCH_NODE`	Time attributed to `BranchingNode` processing, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_ANSWER`	Time attributed to the get-key-answer operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_ANSWER_FOUND`	Time attributed to the get-key-answer-found operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_INSERT_CURRENT_QUESTION_LIST`	Time attributed to insertion into the current question list, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_QUESTIONS`	Time attributed to the get-key-questions operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_VECTOR_SEARCH_SIMPLIFIED`	Time attributed to the simplified vector-search operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_VECTOR_SEARCH`	Time attributed to the vector-search operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_AND_DEDUPLICATE_CHUNKS_SIMPLIFIED`	Time attributed to simplified chunk merging and deduplication, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_AND_DEDUPLICATE_CHUNKS`	Time attributed to chunk merging and deduplication, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FILTER_ALREADY_RETRIEVED_CHUNKS_SIMPLIFIED`	Time attributed to simplified filtering of previously retrieved chunks, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FILTER_ALREADY_RETRIEVED_CHUNKS`	Time attributed to filtering of previously retrieved chunks, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_QUESTION_LISTS`	Time attributed to merging question lists, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GROUP_CHUNKS`	Time attributed to grouping chunks, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FLATTEN_QUERIES`	Time attributed to flattening queries, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_REMOVE_SOURCE`	Time attributed to removing source information, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_SELECT_CHOICES`	Time attributed to the get-key-select-choices operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FILTER_UNWANTED_CHUNKS`	Time attributed to filtering unwanted chunks, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_FLATTEN_CHUNK_LISTS`	Time attributed to flattening chunk lists, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_RETRIEVED_CONTEXT_SIMPLIFIED`	Time attributed to simplified merging of retrieved context, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_MERGE_RETRIEVED_CONTEXT`	Time attributed to merging retrieved context, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_INC_COUNT`	Time attributed to the legacy increment-count operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_INCREMENT_COUNTER`	Time attributed to the increment-counter operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_FINAL_ANSWER_READY`	Time attributed to checking whether the final answer is ready, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_GET_KEY_FEEDBACK`	Time attributed to the get-key-feedback operation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_STRINGIFY_VALUE`	Time attributed to conversion of a value to its string representation, in milliseconds.
`AGENT_EXECUTOR_TOTAL_TIME_BUILTIN_PLSQL_EXEC`	Time attributed to the `plsql_exec` operation, in milliseconds.
`AGENT_EXECUTOR_INPUT_TOKENS`	Number of LLM input tokens.
`AGENT_EXECUTOR_OUTPUT_TOKENS`	Number of LLM output tokens.
`CON_ID`	Identifier of the container associated with the row.