# Oracle AI Database Agent Engine

This file contains the text from each Oracle AI Database Agent Engine article landing page, release 23.26.3.2.

# Oracle AI Database Agent Engine

## Overview

Oracle AI Database Agent Engine executes supported Agent Spec `26.1.0` agents and workflows inside Oracle AI Database, coordinating LLM calls, PL/SQL tools, database operations, transactions, security, and data flow while preserving Agent Spec portability. It validates specifications before execution, supports immediate and stored execution through `DBMS_AI_AGENT`, and can return structured traces. Flows execute connected graphs from start to end nodes, while Agents perform iterative model-and-tool processing. Key benefits include governed information disclosure, data locality, transaction-aware execution, supported resumability and conversations, and simpler deployment for database-centric workflows without a separate orchestration service.

Read More: [Overview](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/oracle-ai-database-agent-engine/overview.html)

## Agent Architecture and Components

Oracle AI Database executes supported Agent Specs through the Database Agent Engine and its public `DBMS_AI_AGENT` interface, separating portable workflow definitions from the database execution environment. Agent Spec defines typed inputs and outputs, executable Flows, Agents, nodes, control-flow and data-flow edges, tools, and model configuration. Flows execute explicit graphs that may include model calls, tools, branching, mapping, parallelism, and nested Flows, while Agents perform ReAct-style iterative model-and-tool interactions. Supporting tools expose operations such as database procedures, model configuration enables LLM capabilities, and `DBMS_AI_AGENT` supports immediate or named stored execution plus listing, describing, and deleting stored agents through JSON-based interfaces.
Read More: [Agent Architecture and Components](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/oracle-ai-database-agent-engine/agent-architecture-and-components.html)


# Get Started with Oracle AI Database Agent Engine

## Get Started

This page provides an end-to-end example for configuring Oracle AI Database model access and executing an Agent Spec through `DBMS_AI_AGENT`. It covers prerequisites, required package, credential, and network privileges, provider credential creation with `DBMS_VECTOR_CHAIN`, and execution of a Flow that passes a customer request from a `StartNode` to an `LlmNode` for summarization and then to an `EndNode`. The example demonstrates the distinction between control-flow and data-flow connections, shows the expected JSON output, explains how to change the request input, and directs readers to related topics covering configuration, execution, flow components, agents, tracing, and runtime statistics.
Read More: [Get Started](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/get-started-with-oracle-ai-database-agent-engine/get-started.html)


# Agent Building Blocks

## Building Blocks

Agent Spec building blocks are JSON components with a schema-selected component\_type and scope-specific id, supplemented by recurring fields such as name, description, and metadata. Component references use exact IDs through $component\_ref and $referenced\_components, while flow connections reference nodes by ID rather than name. Inputs and outputs establish case-sensitive, typed contracts supporting scalar, structured, nullable, union, and nested values, and tools define independently configured operations callable by Flows or Agents. In an order-status example, runtime validation, start and end nodes, tool references, control-flow sequencing, and data-flow transfers combine to receive an order ID, invoke a lookup tool, and publish the resulting status.

Read More: [Building Blocks](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/agent-building-blocks/building-blocks.html)

## Common Component Fields

Agent Spec components are typed JSON objects representing workflows, nodes, edges, model configurations, or tools, with schemas determined by the case-sensitive component\_type. Common fields include id for unique identity within scope, name for human-readable labeling, optional description and metadata, and agentspec\_version where supported; component-specific schemas determine which fields are valid or required. IDs resolve references and graph connections, names do not establish identity, descriptions document purpose, metadata carries application information without controlling execution, and the declared Agent Spec version must be supported by the target database release.

Read More: [Common Component Fields](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/agent-building-blocks/common-component-fields.html)

## Inputs Outputs and Data Types

Inputs and outputs define typed, validated contracts for callers, components, and connected Flow nodes, using unique case-sensitive titles referenced by execution parameters and data-flow edges. Supported declarations include strings, numbers, integers, booleans, nulls, objects, arrays, nested structures, and unions through anyOf; arrays require items, objects may define properties, required members, additionalProperties, and string key types. Defaults must match declared types, with type-based defaults derived when omitted. Data-flow validation requires existing endpoints, compatible source and destination types, providers or defaults for required inputs, and output compatibility at Flow and nested-flow boundaries.

Read More: [Inputs Outputs and Data Types](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/agent-building-blocks/inputs-outputs-and-data-types.html)

## Control Flow and Data Flow

Flows use independent ControlFlowEdge and DataFlowEdge components: control edges define possible execution continuations, including exact branch-specific routes, while data edges transfer named values between declared outputs and inputs. Control references must resolve within the same graph, every selectable branch must lead through an appropriate edge toward an EndNode, and branch selection does not transfer data. Data edges require valid, case-sensitive endpoint names and compatible types, but do not determine execution timing. Because the graphs are independent, values can move directly from producers to later consumers without pass-through nodes, allowing each node to declare only the data it uses or produces.

Read More: [Control Flow and Data Flow](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/agent-building-blocks/control-flow-and-data-flow.html)

## Define Tools and Built-In Tool Types

Tools are predefined operations whose definitions specify operation type, location, configuration, and execution boundaries, while Flow ToolNodes and Agents determine how they are invoked. BuiltinTool requires an identity, executor, supported case-sensitive tool\_type, and applicable configuration; the plsql\_exec type resolves a stored procedure by schema, package, and procedure names, binds declared endpoints to supported PL/SQL parameters, enforces compatible Agent Spec types and parameter directions, and requires database EXECUTE privilege. A ToolNode owns graph-facing inputs and outputs and references the tool by ID, whereas an Agent’s declared tool list limits executable choices and cannot be expanded by model requests.

Read More: [Define Tools and Built-In Tool Types](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/agent-building-blocks/define-tools-and-built-in-tool-types.html)

## LLM Configuration and Access

LlmNode and Agent model calls use DbmsVectorChainLlmConfig to specify provider, complete endpoint URL, model, optional local host mode, credential name, generation parameters, and transfer timeout. External calls require three separately managed elements: Agent Spec configuration, a database credential containing authentication material, and a network ACL authorizing the executing database principal to reach the endpoint host; credentials do not grant network access and ACLs do not authenticate requests. Provider-compatible settings include max\_tokens, temperature, top\_p, and reasoning\_effort. Supported local OpenAI-compatible or Ollama endpoints may set host to local and omit credentials, but host and credential\_name are mutually exclusive and local mode does not authorize arbitrary remote endpoints.
Read More: [LLM Configuration and Access](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/agent-building-blocks/llm-configuration-and-access.html)


# Agents

## Overview

An Agent is an executable component that combines required system instructions and an LLM configuration with optional typed inputs, outputs, and tools. It uses an iterative ReAct-style model-and-tool loop in which the model selects available tools, receives validated results, and continues until producing a final response or reaching an error or execution limit. Unlike a Flow, which follows a predetermined graph, an Agent provides bounded, goal-directed autonomy with dynamic tool selection, iterative refinement, runtime validation, privilege enforcement, and traceable model and tool activity.

Read More: [Overview](https://orahub.oci.oraclecorp.com/db-ua-dev/text-editor-poc/-/tree/no-doc-repo/agents/23.26.3.2/overview.md?ref_type=heads)

## Define an Agent

Defining an Agent requires a component type, unique identifier, name, supported LLM configuration, and system prompt, with optional inputs, outputs, tools, toolboxes, human participation, and referenced component definitions. The example order-support Agent accepts a request, uses separate order lookup and return-eligibility tools, and returns a response through symbolically resolved components whose references and identifiers must match exactly. Its system prompt may include case-sensitive input variables such as `{{request}}`, but instructions do not grant permissions; runtime validation, database privileges, credentials, network controls, tool contracts, and model-and-tool round limits govern execution.
Read More: [Define an Agent](https://orahub.oci.oraclecorp.com/db-ua-dev/text-editor-poc/-/tree/no-doc-repo/agents/23.26.3.2/define_an_agent.md?ref_type=heads)


# Design and Run Flows

## Overview of Flows

A Flow is a standalone executable workflow represented as an explicit graph of typed inputs, outputs, nodes, control-flow connections, and optional data-flow connections. Execution begins at one StartNode, follows declared paths, transfers values through explicit edges, and completes at an EndNode; control flow determines which nodes may execute, while data flow determines which values they receive. Flows support branching, mapping, parallelism, nested subflows, reusable agents, tools, and model invocations, providing validated, inspectable, and repeatable workflow structure.

Read More: [Overview of Flows](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/overview-of-flows.html)

## StartNode

A StartNode is the entry point of a Flow, identified by the Flow’s start\_node field. It exposes caller-supplied Flow inputs as named outputs, which downstream nodes can receive only through declared data-flow connections. Its contract defines component identity, optional inputs and outputs, and branch names for outgoing control-flow edges; it does not itself determine downstream data or execution beyond the graph connections.

Read More: [StartNode](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/startnode.html)

## EndNode

An EndNode marks completion of a Flow path and maps values received through data-flow edges to the enclosing Flow’s output contract. A Flow may contain multiple EndNodes for different valid outcomes, with each reachable EndNode returning compatible output values and optionally identifying a branch\_name. For top-level Flows, these mapped values are returned to the caller; for nested Flows, they become outputs of the enclosing component.

Read More: [EndNode](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/endnode.html)

## ToolNode

A ToolNode invokes one predefined Tool at a declared point in a Flow, using typed inputs and producing typed outputs without model-selected operation choice. The node defines the graph-facing contract, branches, and reference to the Tool, while the referenced Tool defines operation-specific details such as PL/SQL configuration. Control-flow edges determine when the node executes, data-flow edges supply arguments and transfer results, and compatible Tool and ToolNode contracts are required.

Read More: [ToolNode](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/toolnode.html)

## LLMNode

An LlmNode performs one predetermined model invocation, such as summarization, classification, or generation, without iterative reasoning or tool calling. It receives typed inputs, renders them into a required prompt\_template using case-sensitive variable names, invokes the referenced LLM configuration, and maps the model response to declared outputs. Provider, endpoint, model, credentials, generation parameters, and expected response format must be compatible, while explicit data-flow edges connect the node’s inputs and outputs to other components.

Read More: [LLMNode](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/llmnode.html)

## AgentNode

An AgentNode executes a referenced Agent as one component within a Flow, exposing its own typed input, output, branch, and graph identity contracts. The referenced Agent performs iterative model reasoning and tool-calling using its instructions, LLM configuration, and available Tools, then returns a result through the AgentNode outputs. Flow edges connect to the AgentNode rather than the Agent internals, and the AgentNode and Agent contracts must remain compatible.

Read More: [AgentNode](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/agentnode.html)

## BranchingNode

A BranchingNode selects one declared branch by evaluating exactly one typed input against its mapping. The selected branch must be declared in branches and correspond to an outgoing control-flow edge with the matching from\_branch; edges for other branches are not followed. Branch selection controls execution only and does not transfer values, so separate data-flow edges must provide the decision or other required inputs to downstream handlers.

Read More: [BranchingNode](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/branchingnode.html)

## FlowNode

A FlowNode embeds a reusable subflow within an enclosing Flow while presenting the subflow as a single graph component. It maps compatible inputs into the referenced Flow, starts that subflow at its StartNode, maps the reached EndNode’s outputs back to its own outputs, and exposes the resulting branch for continuation. The enclosing and nested graphs remain separate, and their input and output counts, names, and types must satisfy the required compatibility rules.

Read More: [FlowNode](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/flownode.html)

## MapNode

A MapNode executes the same subflow once for each item in an input collection, maps each item to the subflow’s compatible scalar input, and combines selected outputs through reducers. Its contract defines collection-boundary names, while the subflow handles one item per execution and runs from StartNode to EndNode. Supported reducers include append, sum, average, min, and max; omitted reducers default to append. The example maps order IDs to an order-lookup subflow, appends returned statuses, and exposes the combined array through the enclosing Flow. A complete runnable specification demonstrates execution with three order IDs and returns their corresponding statuses.

Read More: [MapNode](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/mapnode.html)

## Parallelism

Parallel execution runs independent work concurrently without changing component contracts, reference resolution, type compatibility, or reducer behavior. ParallelFlowNode executes multiple different, independent subflows and exposes each subflow’s uniquely provided outputs, while ParallelMapNode executes the same subflow concurrently for every item in a collection and reduces the results according to configured reducers. Completion order is nondeterministic, and dependencies between operations require sequential control and data flow instead. Examples show concurrent shipment, payment, and return checks for one order, plus concurrent status lookups for multiple orders using an append reducer.

Read More: [Parallelism](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/parallelism.html)

## End-to-End Workflow Example

This order-support workflow demonstrates coordinated control flow, data flow, and processing nodes for three request types: order-status inquiries use a reusable FlowNode, return requests invoke a predetermined ToolNode, and general questions use an AgentNode. The StartNode publishes request data, a BranchingNode maps request\_type to one declared branch, and only the selected path executes before transferring its result to the corresponding EndNode and common response output. Data-flow edges explicitly supply each node’s required inputs, while control-flow edges determine execution. The runnable specification includes database operations, nested flow and tool references, agent configuration, and an example return-request execution that produces a customer-facing eligibility response.
Read More: [End-to-End Workflow Example](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/design-and-run-flows/end-to-end-workflow-example.html)


# Create and Manage Agents

## Create an Agent

`DBMS_AI_AGENT.CREATE_AGENT` validates and stores a complete Agent Spec under a database name without executing it. The procedure accepts the stored name and the specification as a CLOB, including the top-level executable component and all referenced components; the stored name is independent of internal component IDs, names, and references. Successful validation covers document structure, supported components, references, graph connections, and input/output contracts, after which the agent can be executed later with `DBMS_AI_AGENT.EXECUTE_AGENT`.

Read More: [Create an Agent](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/create-and-manage-agents/create-an-agent.html)

## Execute an Agent

`DBMS_AI_AGENT.EXECUTE_IMMEDIATE` runs a complete Agent Spec supplied for one call, while `DBMS_AI_AGENT.EXECUTE_AGENT` runs a specification previously stored by name with `CREATE_AGENT`. Both functions accept execution inputs as a JSON CLOB array of name/value pairs, return output values as a JSON CLOB based on the top-level component’s output contract, and optionally provide execution traces through an OUT CLOB. Input names must exactly match declared input titles and values must conform to their declared types; immediate execution does not persist the specification, whereas stored agents remain available for subsequent calls.

Read More: [Execute an Agent](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/create-and-manage-agents/execute-an-agent.html)

## List and Describe Agents

`DBMS_AI_AGENT.LIST_AGENTS` returns a JSON array describing stored agents visible to the current user, while `DBMS_AI_AGENT.DESCRIBE_AGENT` returns the corresponding description for one named agent. Both read-only procedures use CLOB OUT parameters and report metadata such as the stored name, creation time, description, top-level inputs and outputs, and the JSON call contract requiring name/value input pairs. Listing returns an empty array when no visible agents exist, and describing an unknown or inaccessible agent produces an error.

Read More: [List and Describe Agents](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/create-and-manage-agents/list-and-describe-agents.html)

## Delete an Agent

`DBMS_AI_AGENT.DELETE_AGENT` permanently removes a stored Agent Spec identified by the database name assigned during creation. The procedure accepts only the stored agent name, returns no execution result on success, and makes the name unavailable to execution and description APIs. Deletion affects only the stored agent specification; referenced database objects, credentials, tables, indexes, retrieval resources, model endpoints, procedures, and external services remain unchanged.
Read More: [Delete an Agent](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/create-and-manage-agents/delete-an-agent.html)


# 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.

Read More: [Tracing](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/observability-and-diagnostics/tracing.html)

## 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](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/observability-and-diagnostics/agent-catalog-and-runtime-statistics-views.html)


# Appendix - Parameters

## Session Parameters

Database initialization parameters control In-Database Agent Runtime behavior independently of Agent Specs and `DBMS_AI_AGENT` APIs. They govern parallel execution, statistics flushing thresholds, maximum model-and-tool iterations, JSON Schema validation and reporting, and structured-output generation modes for `LlmNode`; because these settings can affect all applicable Agent Specs, verify their supported values and scope for the target database release.
Read More: [Session Parameters](https://docs.oracle.com/en/database/oracle/oracle-database/26/odbae/appendix-parameters/session-parameters.html)