Execution Tracing

An execution trace is a structured JSON record of one Agent Spec execution. It identifies the components that participated, organizes nested component activity into frames, records lifecycle events, and captures component input and output state.

A trace can help determine:

Which components participated in an execution.
Which component instances started and completed.
What inputs and outputs were captured for each component.
How nested, mapped, parallel, or repeated work relates to its enclosing component.

Trace collection is optional. Include the TRACES output parameter in an EXECUTE_IMMEDIATE or EXECUTE_AGENT call when trace information is required. The execution output remains the function return value, while TRACES receives the trace as a separate JSON CLOB.

Complete Tracing Example

The following example defines a complete order-request flow, executes it with tracing enabled, and displays both the execution output and trace.

The Flow accepts an order_id, transfers it from its StartNode to its EndNode, and returns the same value through the Flow output contract.

SET SERVEROUTPUT ON

DECLARE
  L_AGENT_SPEC CLOB := q'~
{
  "component_type": "Flow",
  "agentspec_version": "26.1.0",
  "id": "order-request-flow",
  "name": "order_request_flow",
  "inputs": [
    {
      "title": "order_id",
      "type": "string"
    }
  ],
  "outputs": [
    {
      "title": "order_id",
      "type": "string"
    }
  ],
  "start_node": {
    "$component_ref": "order-request-start"
  },
  "nodes": [
    {
      "$component_ref": "order-request-start"
    },
    {
      "$component_ref": "order-request-end"
    }
  ],
  "control_flow_connections": [
    {
      "component_type": "ControlFlowEdge",
      "id": "start-to-end",
      "name": "start_to_end",
      "from_node": {
        "$component_ref": "order-request-start"
      },
      "to_node": {
        "$component_ref": "order-request-end"
      }
    }
  ],
  "data_flow_connections": [
    {
      "component_type": "DataFlowEdge",
      "id": "order-id-to-end",
      "name": "order_id_to_end",
      "source_node": {
        "$component_ref": "order-request-start"
      },
      "source_output": "order_id",
      "destination_node": {
        "$component_ref": "order-request-end"
      },
      "destination_input": "order_id"
    }
  ],
  "$referenced_components": {
    "order-request-start": {
      "component_type": "StartNode",
      "id": "order-request-start",
      "name": "order_request_start",
      "inputs": [
        {
          "title": "order_id",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "order_id",
          "type": "string"
        }
      ],
      "branches": ["next"]
    },
    "order-request-end": {
      "component_type": "EndNode",
      "id": "order-request-end",
      "name": "order_request_end",
      "inputs": [
        {
          "title": "order_id",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "order_id",
          "type": "string"
        }
      ],
      "branches": [],
      "branch_name": "next"
    }
  }
}
~';

  L_INPUTS CLOB :=
    TO_CLOB('[{"name":"order_id","value":"7812"}]');
  L_OUTPUTS CLOB;
  L_TRACES  CLOB;
BEGIN
  L_OUTPUTS := DBMS_AI_AGENT.EXECUTE_IMMEDIATE (
    AGENT_SPEC => L_AGENT_SPEC,
    INPUTS     => L_INPUTS,
    TRACES     => L_TRACES
  );

  DBMS_OUTPUT.PUT_LINE ('Execution output:');
  DBMS_OUTPUT.PUT_LINE (
    DBMS_LOB.SUBSTR (L_OUTPUTS, 32767, 1)
  );

  DBMS_OUTPUT.PUT_LINE ('Execution trace:');
  DBMS_OUTPUT.PUT_LINE (
    DBMS_LOB.SUBSTR (L_TRACES, 32767, 1)
  );
END;
/

The function returns the Flow output:

{
  "order_id": "7812"
}

The L_TRACES CLOB contains a separate trace document:

{
  "version": 1,
  "roots": [
    {
      "component_type": "Flow",
      "node_id": "order-request-flow",
      "node_name": "order_request_flow",
      "instance": 1,
      "depth": 0,
      "events": [
        {
          "type": "component_lifecycle",
          "phase": "start"
        },
        {
          "type": "component_state",
          "phase": "inputs",
          "io": {
            "order_id": "7812"
          }
        },
        {
          "type": "component_state",
          "phase": "outputs",
          "io": {
            "order_id": "7812"
          }
        },
        {
          "type": "component_lifecycle",
          "phase": "end"
        }
      ],
      "children": [
        {
          "component_type": "StartNode",
          "node_id": "order-request-start",
          "node_name": "order_request_start",
          "instance": 1,
          "depth": 0,
          "events": [
            {
              "type": "component_lifecycle",
              "phase": "start"
            },
            {
              "type": "component_state",
              "phase": "inputs",
              "io": {
                "order_id": "7812"
              }
            },
            {
              "type": "component_state",
              "phase": "outputs",
              "io": {
                "order_id": "7812"
              }
            },
            {
              "type": "component_lifecycle",
              "phase": "end"
            }
          ],
          "children": []
        },
        {
          "component_type": "EndNode",
          "node_id": "order-request-end",
          "node_name": "order_request_end",
          "instance": 1,
          "depth": 0,
          "events": [
            {
              "type": "component_lifecycle",
              "phase": "start"
            },
            {
              "type": "component_state",
              "phase": "inputs",
              "io": {
                "order_id": "7812"
              }
            },
            {
              "type": "component_state",
              "phase": "outputs",
              "io": {
                "order_id": "7812"
              }
            },
            {
              "type": "component_lifecycle",
              "phase": "end"
            }
          ],
          "children": []
        }
      ]
    }
  ]
}

Follow the Example Trace

The trace corresponds directly to the executed Agent Spec:

The object in roots represents the top-level Flow with ID order-request-flow.
The Flow's inputs state event captures the order_id supplied by the execution call.
The StartNode child frame captures the value received at the Flow entry and the value made available through StartNode.order_id.
The data-flow connection transfers that value to EndNode.order_id.
The EndNode child frame captures the value received at the completion boundary.
The Flow's outputs state event captures the value returned in the execution output.
The end lifecycle event on each frame indicates that processing for that component instance completed.

The trace hierarchy and the data-flow connection describe different relationships. children associates component activity with the enclosing Flow. The data-flow edge in the Agent Spec describes how order_id moved from the StartNode output to the EndNode input.

Trace Document Fields

Field	Description
`version`	Identifies the structured trace format version.
`roots`	Contains the top-level component frames recorded for the execution.

Each object in roots uses the component-frame structure described in the following section.

Component Frame Fields

A component frame represents one execution instance of a component:

Field	Description
`component_type`	Identifies the component type represented by the frame.
`node_id`	Contains the component's `id` from the Agent Spec.
`node_name`	Contains the component's human-readable `name` from the Agent Spec.
`instance`	Distinguishes repeated execution instances of the component.
`depth`	Records the nested child-execution depth associated with the frame.
`events`	Contains lifecycle and state events recorded for the component instance.
`children`	Contains component frames recorded within the enclosing component frame.

node_id and node_name connect the frame to its Agent Spec definition. instance distinguishes repeated activity, such as separate map iterations or repeated execution of the same component.

depth is not the frame's position in the children hierarchy. It records nested child-execution boundaries used by components such as FlowNode, MapNode, ParallelFlowNode, and ParallelMapNode. In the simple example, the Flow, StartNode, and EndNode frames all have depth 0 even though the node frames appear in the Flow's children array.

Trace Events

Lifecycle Events

A lifecycle event records the start or end of component processing:

{
  "type": "component_lifecycle",
  "phase": "start"
}

Phase	Description
`start`	Processing began for the component instance.
`end`	Processing ended for the component instance.

The order of events in a frame shows the lifecycle activity recorded for that component instance.

State Events

A state event captures component inputs or outputs:

{
  "type": "component_state",
  "phase": "outputs",
  "io": {
    "order_id": "7812"
  }
}

Field	Description
`phase`	Contains `inputs` for captured input state or `outputs` for captured output state.
`io`	Contains the named values captured for that phase.

The members of io correspond to the component's declared input or output titles. The values reflect the state available when the event was recorded.

Nested and Repeated Activity

Frames in children represent component activity recorded within an enclosing component frame. Nested Flows, map iterations, parallel work, and tool activity can add further child frames.

The combination of node_id, instance, depth, and the children hierarchy helps distinguish:

Components in an outer Flow from components executed within a nested boundary.
Separate executions of the same component definition.
Individual mapped or parallel component instances.

Parallel child frames can appear in nondeterministic completion order. Applications should identify them through their component and instance fields rather than rely on array position as a stable execution order.