Execute an Agent

The DBMS_AI_AGENT execution functions run an Agent Spec and return the values produced through the output contract of its top-level executable component. The caller can supply the complete Agent Spec for the current call or execute a specification previously stored under a name.

Execution Forms

Function	Agent Spec source
DBMS_AI_AGENT.EXECUTE_IMMEDIATE	A complete Agent Spec supplied as a CLOB for the current call.
DBMS_AI_AGENT.EXECUTE_AGENT	An Agent Spec previously stored under a name by DBMS_AI_AGENT.CREATE_AGENT.

Both functions accept execution inputs as JSON in a CLOB and return execution outputs as JSON in a CLOB. Each function can also return execution trace information through the optional TRACES output parameter.

Syntax

EXECUTE_IMMEDIATE

DBMS_AI_AGENT.EXECUTE_IMMEDIATE (
    AGENT_SPEC IN CLOB,
    INPUTS     IN CLOB
) RETURN CLOB;

DBMS_AI_AGENT.EXECUTE_IMMEDIATE (
    AGENT_SPEC IN CLOB,
    INPUTS     IN CLOB,
    TRACES     OUT CLOB
) RETURN CLOB;

EXECUTE_AGENT

DBMS_AI_AGENT.EXECUTE_AGENT (
    AGENT_NAME IN VARCHAR2,
    INPUTS     IN CLOB
) RETURN CLOB;

DBMS_AI_AGENT.EXECUTE_AGENT (
    AGENT_NAME IN VARCHAR2,
    INPUTS     IN CLOB,
    TRACES     OUT CLOB
) RETURN CLOB;

Parameters

Parameter	Mode	Applies to	Description
AGENT_SPEC	IN	EXECUTE_IMMEDIATE	Specifies a CLOB containing the complete Agent Spec JSON document.
AGENT_NAME	IN	EXECUTE_AGENT	Specifies the database name assigned to a stored Agent Spec by CREATE_AGENT.
INPUTS	IN	Both functions	Specifies a CLOB containing the named input values supplied to the top-level executable component.
TRACES	OUT	When trace collection is requested	Receives trace information for the current execution as a CLOB.

Each function returns a CLOB containing the execution outputs.

EXECUTE_IMMEDIATE

EXECUTE_IMMEDIATE accepts the complete Agent Spec and its execution inputs in the same call. It validates and runs the supplied specification without storing it under a database name.

The following example executes a simple order-support Flow. The Flow accepts an order_id and returns the same value through its output contract. It does not require an LLM configuration, database credential, or tool definition.

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 (
    DBMS_LOB.SUBSTR (L_OUTPUTS, 32767, 1)
  );
END;
/

The function returns a JSON object containing the Flow output.

{
  "order_id": "7812"
}

The specification and inputs apply only to this call:

complete Agent Spec + inputs
             |
             v
     EXECUTE_IMMEDIATE
             |
             v
      execution output

EXECUTE_AGENT

EXECUTE_AGENT runs an Agent Spec previously stored by CREATE_AGENT. The Create an Agent example stores the order-request Flow under the name ORDER_REQUEST_FLOW.

After creating that stored agent, the following example executes it with a new order_id input:

SET SERVEROUTPUT ON

DECLARE
  L_INPUTS CLOB :=
    TO_CLOB('[{"name":"order_id","value":"7812"}]');
  L_OUTPUTS CLOB;
  L_TRACES  CLOB;
BEGIN
  L_OUTPUTS := DBMS_AI_AGENT.EXECUTE_AGENT (
    AGENT_NAME => 'ORDER_REQUEST_FLOW',
    INPUTS     => L_INPUTS,
    TRACES     => L_TRACES
  );

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

ORDER_REQUEST_FLOW is the stored database name assigned by CREATE_AGENT. It is not a component ID or component name inside the Agent Spec.

The stored specification remains available for later calls. Each call can supply different input values that conform to its declared input contract.

Input JSON

The INPUTS CLOB contains a JSON array. Each array member supplies a named value:

[
  {
    "name": "order_id",
    "value": "7812"
  }
]

The runtime matches name to the title of an input declared by the top-level executable component. The supplied value must conform to that input's declared type. The example therefore supplies a string value for the order_id input.

When an Agent Spec declares multiple inputs, each supplied value appears as a separate array member. Every supplied name must correspond to a declared input. For example, a Flow declares two inputs:

"inputs": [
    {"title": "order_id", "type": "string"},
    {"title": "include_delivery_details", "type": "boolean"}
  ]

  The execution call supplies:

  [
    {"name": "order_id", "value": "7812"},
    {"name": "include_delivery_details", "value": true}
  ]

The runtime matches each supplied name to the corresponding declared Flow input. The value becomes available through the StartNode output with that name, and data-flow edges transfer it to the node inputs that consume it. Each array member supplies one Flow input; when a supplied value is an object, its properties remain part of that single value and are not treated as separate inputs.

Returned Output

The function return value is a CLOB containing a JSON object. Its member names correspond to the output titles declared by the top-level executable component:

{
  "order_id": "7812"
}

Trace Output

Trace collection is optional. Include the TRACES output parameter when trace information is required.

Overload	Result
Without TRACES	Returns the execution output as a CLOB.
With TRACES OUT CLOB	Returns the execution output and assigns trace information to the supplied CLOB variable.

The TRACES value describes component activity recorded during that execution. It is separate from the business values returned by the function. For more information, see Tracing.