Get Started

This page provides a complete example that configures model access and executes an Agent Spec through Oracle AI Database. The example accepts a customer request, sends it to an LlmNode for summarization, and returns the summary through the Flow output contract.

Prerequisites

Before running the example, confirm that:

• Oracle AI Database includes the DBMS_AI_AGENT and DBMS_VECTOR_CHAIN packages.
• You have a database schema for executing the Agent Spec. This page uses APP_SCHEMA.
• The schema can execute DBMS_AI_AGENT and DBMS_VECTOR_CHAIN.CREATE_CREDENTIAL.
• The schema has the CREATE CREDENTIAL privilege.
• You have an API key or other authentication material for a supported model provider.
• A database administrator can grant network access to the provider endpoint.

This example uses the following provider values:

Setting	Example value
Provider	openai
Endpoint	https://api.openai.com/v1/chat/completions
Model	gpt-4.1-mini
Credential	AI_PROVIDER_CREDENTIAL
Application schema	APP_SCHEMA

Replace these values when your database uses a different provider, endpoint, model, credential name, or application schema.

Step 1: Grant the Required Database Privileges

A database administrator grants the package and credential privileges to the application schema:

COPY

GRANT EXECUTE ON DBMS_AI_AGENT TO APP_SCHEMA;
GRANT EXECUTE ON DBMS_VECTOR_CHAIN TO APP_SCHEMA;
GRANT CREATE CREDENTIAL TO APP_SCHEMA;

The administrator also grants the application schema permission to contact the host in the model endpoint:

COPY

BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE (
    HOST => 'api.openai.com',
    ACE  => XS$ACE_TYPE (
              PRIVILEGE_LIST => XS$NAME_LIST ('http'),
              PRINCIPAL_NAME => 'APP_SCHEMA',
              PRINCIPAL_TYPE => XS_ACL.PTYPE_DB
            )
  );
END;
/

The ACL HOST value is the endpoint host name without the https:// scheme or request path. For a different endpoint, replace api.example.com with the host name from that endpoint.

Step 2: Create the Provider Credential

Connect as APP_SCHEMA and create the database credential referenced by the Agent Spec:

COPY

BEGIN
  DBMS_VECTOR_CHAIN.CREATE_CREDENTIAL (
    CREDENTIAL_NAME => 'AI_PROVIDER_CREDENTIAL',
    PARAMS          => JSON ('{"access_token":"replace-with-provider-api-key"}')
  );
END;
/

Replace replace-with-provider-api-key with the provider API key. Run this step once for the credential. The credential stores the secret in the database; the Agent Spec contains only its name.

Provider credentials are created and managed through DBMS_VECTOR_CHAIN. The JSON attributes required in PARAMS depend on the provider and its authentication method. See DBMS_VECTOR_CHAIN.CREATE_CREDENTIAL for the procedure syntax and supported credential formats.

Step 3: Execute the Agent Spec

Connect as APP_SCHEMA, copy the following block into SQL*Plus, SQLcl, or another PL/SQL client, and run it:

COPY

SET SERVEROUTPUT ON SIZE UNLIMITED
SET DEFINE OFF

DECLARE
  L_AGENT_SPEC CLOB := q'~
{
  "component_type": "Flow",
  "agentspec_version": "25.4.1",
  "id": "summarize-support-request-flow",
  "name": "summarize_support_request_flow",
  "inputs": [
    {
      "title": "request",
      "type": "string"
    }
  ],
  "outputs": [
    {
      "title": "summary",
      "type": "string",
      "default": ""
    }
  ],
  "start_node": {
    "$component_ref": "request-start"
  },
  "nodes": [
    {
      "$component_ref": "request-start"
    },
    {
      "$component_ref": "summarize-request"
    },
    {
      "$component_ref": "summary-end"
    }
  ],
  "control_flow_connections": [
    {
      "component_type": "ControlFlowEdge",
      "id": "start-to-summary",
      "name": "start_to_summary",
      "from_node": {
        "$component_ref": "request-start"
      },
      "to_node": {
        "$component_ref": "summarize-request"
      }
    },
    {
      "component_type": "ControlFlowEdge",
      "id": "summary-to-end",
      "name": "summary_to_end",
      "from_node": {
        "$component_ref": "summarize-request"
      },
      "to_node": {
        "$component_ref": "summary-end"
      }
    }
  ],
  "data_flow_connections": [
    {
      "component_type": "DataFlowEdge",
      "id": "request-to-summary",
      "name": "request_to_summary",
      "source_node": {
        "$component_ref": "request-start"
      },
      "source_output": "request",
      "destination_node": {
        "$component_ref": "summarize-request"
      },
      "destination_input": "request"
    },
    {
      "component_type": "DataFlowEdge",
      "id": "summary-to-result",
      "name": "summary_to_result",
      "source_node": {
        "$component_ref": "summarize-request"
      },
      "source_output": "summary",
      "destination_node": {
        "$component_ref": "summary-end"
      },
      "destination_input": "summary"
    }
  ],
  "$referenced_components": {
    "request-start": {
      "component_type": "StartNode",
      "id": "request-start",
      "name": "request_start",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "branches": [
        "next"
      ]
    },
    "summarize-request": {
      "component_type": "LlmNode",
      "id": "summarize-request",
      "name": "summarize_request",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "summary",
          "type": "string",
          "default": ""
        }
      ],
      "branches": [
        "next"
      ],
      "llm_config": {
        "$component_ref": "application-llm-config"
      },
      "prompt_template": "Summarize this customer order-support request in one short sentence: {{request}}"
    },
    "summary-end": {
      "component_type": "EndNode",
      "id": "summary-end",
      "name": "summary_end",
      "inputs": [
        {
          "title": "summary",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "summary",
          "type": "string"
        }
      ],
      "branches": [],
      "branch_name": "next"
    },
    "application-llm-config": {
      "component_type": "DbmsVectorChainLlmConfig",
      "id": "application-llm-config",
      "name": "application_llm_config",
      "provider": "openai",
      "url": "https://api.openai.com/v1/chat/completions",
      "model": "gpt-4.1-mini",
      "credential_name": "AI_PROVIDER_CREDENTIAL",
      "transfer_timeout": 120,
      "default_generation_parameters": {
        "max_tokens": 200,
        "temperature": 0.0,
        "top_p": 1.0
      }
    }
  }
}
~';

  L_INPUTS CLOB := TO_CLOB (
    '[{"name":"request","value":"I placed order 7812 yesterday and would like to know when it will arrive."}]'
  );
  L_OUTPUTS CLOB;
BEGIN
  L_OUTPUTS := DBMS_AI_AGENT.EXECUTE_IMMEDIATE (
    AGENT_SPEC => L_AGENT_SPEC,
    INPUTS     => L_INPUTS
  );

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

The model wording can vary, but the returned JSON has the following shape:

COPY

{
  "summary": "The customer is requesting delivery information for order 7812."
}

What the Example Does

The complete execution has five stages:

1. INPUTS supplies the value named request to the top-level Flow.
2. StartNode publishes that value through its request output.
3. A data-flow edge supplies the value to LlmNode.request.
4. LlmNode renders {{request}} in the prompt, invokes the model identified by application-llm-config, and publishes summary.
5. A second data-flow edge supplies the summary to EndNode, which returns it through the Flow output contract.

Control-flow edges describe the execution path from StartNode to LlmNode and then to EndNode. Data-flow edges independently move request and summary between their named component fields.

Change the Input

To run the same specification with a different request, change only the value in L_INPUTS:

COPY

[
  {
    "name": "request",
    "value": "Please summarize my request for the status of order 8041."
  }
]

The input name remains request because it must match the title declared by the top-level Flow input.

Continue from Here

Goal	Related page
Understand model, credential, and ACL setup	LLM Configuration and Access
Understand graph scheduling and value movement	Control Flow and Data Flow
Execute supplied or stored specifications	Execute an Agent
Understand the flow components	Flow Components
Build an iterative model-and-tool Agent	Agents
Collect and interpret an execution trace	Execution Tracing
Inspect aggregate runtime measurements	Runtime Execution Statistics