Observability and Diagnostics

Tracing

Execution tracing provides an optional structured JSON record for each Agent Spec execution, capturing participating components, nested execution frames, lifecycle events, and component input and output state. Traces are requested through the TRACES output parameter of EXECUTE_IMMEDIATE or EXECUTE_AGENT, while the function return value remains the execution result. The trace hierarchy links root components to child activity, including nested, mapped, parallel, repeated, and tool operations; frame fields identify component type, Agent Spec IDs and names, execution instance, depth, events, and children. Lifecycle events mark component start and completion, state events record declared inputs and outputs, and data-flow connections explain value movement independently of the frame hierarchy. Repeated or parallel instances should be distinguished by component and instance fields rather than array order, which may be nondeterministic.

Agent Catalog and Runtime Statistics Views

Oracle AI Database provides catalog views for stored-agent definitions and dynamic performance views for execution statistics. USER_AI_AGENTS lists agents owned by the current user, while DBA_AI_AGENTS lists agents across the database with ownership details; both expose identifiers, names, creation times, and JSON input and output contracts. V$AGENT_EXEC_STAT reports completed execution measurements for the current instance, and GV$AGENT_EXEC_STAT provides the corresponding multi-instance information, including instance identifiers. Statistics rows represent one successful execution and accumulate nested or repeated activity, but do not provide a reliable execution identifier or timestamp, so traces are preferred for correlating details with a specific call. The views expose node call counts, total and category-specific elapsed times, built-in operation timings, LLM input and output tokens, container context, and diagnostic measures useful for identifying model, tool, branching, mapping, or runtime bottlenecks; component times may overlap or not sum to total execution time.
Read More: Agent Catalog and Runtime Statistics Views