Create an Agent

DBMS_AI_AGENT.CREATE_AGENT validates a complete Agent Spec and stores it in the database under a name. The stored specification can later be executed by passing that name to DBMS_AI_AGENT.EXECUTE_AGENT.

A stored agent contains the complete Agent Spec, including its top-level executable component and referenced components. Creating an agent stores the specification; it does not execute it.

Syntax

DBMS_AI_AGENT.CREATE_AGENT (
    AGENT_NAME IN VARCHAR2,
    AGENT_SPEC IN CLOB
);

Parameters

Parameter	Description
AGENT_NAME	Specifies the database name assigned to the stored Agent Spec. Subsequent API calls pass this name to identify the stored agent.
AGENT_SPEC	Specifies a CLOB containing the complete Agent Spec JSON document.

AGENT_NAME is separate from the component names and IDs inside the Agent Spec. In the following example, the stored agent is named ORDER_REQUEST_FLOW, while the top-level Flow has the component ID order-request-flow.

Example: Create an Order-Request Flow

The following example creates a simple order-support Flow and stores it as ORDER_REQUEST_FLOW. The Flow accepts an order_id and returns the same value through its output contract when it is executed later.

This focused example does not require an LLM configuration, database credential, or tool definition. It demonstrates how to supply a complete Agent Spec to CREATE_AGENT independently of those additional components.

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"
    }
  }
}
~';

BEGIN
  DBMS_AI_AGENT.CREATE_AGENT (
    AGENT_NAME => 'ORDER_REQUEST_FLOW',
    AGENT_SPEC => L_AGENT_SPEC
  );
END;
/

How the Example Works

The example performs the following operations:

1. The PL/SQL block assigns the complete Agent Spec JSON document to L_AGENT_SPEC.
2. CREATE_AGENT validates the document and stores it under the database name ORDER_REQUEST_FLOW.
3. The stored document includes the top-level Flow, its StartNode and EndNode, and the control-flow and data-flow connections between them.
4. The stored name ORDER_REQUEST_FLOW becomes the identifier used by APIs that operate on the stored specification.

The stored name ORDER_REQUEST_FLOW identifies the complete stored specification. It does not need to match the top-level component ID, component name, or any $component_ref value inside the document.

What Happens During Creation

CREATE_AGENT validates the Agent Spec before storing it. Validation includes the document structure, supported component types and fields, component references, graph connections, and input and output contracts.

If validation succeeds, the complete specification is stored under AGENT_NAME. CREATE_AGENT is a procedure and does not execute the specification or return an execution result.

The stored specification can be executed later by passing ORDER_REQUEST_FLOW to DBMS_AI_AGENT.EXECUTE_AGENT, as described in Execute an Agent.