Agent Architecture and Components
Oracle AI Database executes supported Agent Specs through the Database Agent Engine, which applications access through the public DBMS_AI_AGENT package. The calling application supplies an Agent Spec and its inputs, and the runtime validates the definition, coordinates its components, and returns the output with an optional execution trace.
The architecture separates the portable workflow definition from the database environment that executes it.
Agent Spec
Agent Spec is a portable, declarative format for describing agents and workflows. An Agent Spec identifies the work that can occur, the components that perform that work, the values exchanged between components, and the execution paths through the workflow. For additional information, please see this page.
What an Agent Spec Defines
| Element | Description |
|---|---|
| Inputs and outputs | A typed public contract between the caller and the workflow. |
| Flow | An executable graph containing nodes and edges. |
| Nodes | Components that begin, complete, route, repeat, invoke models, call tools, or run nested work. |
| Control-flow edges | Connections that describe the possible execution paths between nodes. |
| Data-flow edges | Connections that transfer named values between components. |
| Agent | Instructions and tools available for supported, iterative model-and-tool processing. |
| Tool | A declared operation that a ToolNode or Agent can invoke. |
The Agent Spec describes what can execute and how its components relate. The Database Agent Engine supplies the execution environment and applies the controls associated with that environment.
Architecture at a Glance
Description of the illustration Oracle AI Database Agent Engine Runtime Architecture
Flow and Agent are the two top-level executable component types. A specification selects Flow or Agent as its top-level executable component. A Flow follows an explicitly connected graph. An Agent performs supported iterative model-and-tool processing. Tool definitions and model configuration provide capabilities referenced by those components.
Flow Component
A Flow represents an executable graph. Nodes perform work. The control-flow edges describe the possible execution paths between nodes; data-flow edges describe how named values move between declared endpoints.
Description of the illustration Flow Component Execution Model
The graph can contain model calls, tool calls, branching, mapping, parallel work, and other structured operations. It can also include another Flow through a FlowNode, allowing the included Flow to run as a reusable step within the larger workflow. A Flow can be the top-level executable component supplied to the runtime. Its node types and composition rules are described in the Flow chapter.
Agent Component
An Agent implements a ReAct-style interaction in which a language model alternates between making decisions and invoking declared tools until it produces a final output or reaches an applicable execution limit. Its definition specifies the instructions, model configuration, and tools available during execution.
Description of the illustration Agent Component Decision and Tool Loop
An Agent can be the top-level executable component supplied to the runtime. Its instructions, model interactions, tool use, and completion behavior are described in the Agents chapter.
Supporting Tool Definitions
A Tool describes an operation that can be invoked during execution. Tools enable the Database Agent Engine to invoke supported capabilities, such as database procedures and built-in operations provided for supported Agent Spec tool types.
Both top-level component types can reference tools:
| Component | Tool relationship |
|---|---|
| Flow | A node can invoke a declared tool during graph execution. |
| Agent | An Agent can invoke a declared tool during iterative model-and-tool processing. |
The tool definition describes the operation and its input and output contract. Database privileges, credentials, and network controls remain part of the
database execution environment.
Supporting Model Configuration
Model configuration supplies language-model capabilities to Flows and Agents. The two top-level components incorporate those capabilities differently:
| Component | Model relationship |
|---|---|
| Flow | An LlmNode or AgentNode performs a supported model invocation as an explicit step in the graph. |
| Agent | An Agent performs supported model invocations as part of an iterative model-and-tool loop. |
DBMS_AI_AGENT Package
DBMS_AI_AGENT is the public application interface to the Database Agent Engine. Its APIs support two execution forms:
| Form | Description |
|---|---|
| Immediate execution | The caller supplies the Agent Spec and inputs for the current call. |
| Stored execution | The caller creates a named stored agent and executes it by name. |
The package also provides operations for listing, describing, and deleting stored agents. Agent Specs, inputs, outputs, and optional traces are JSON documents exchanged through CLOB parameters and return values. For more information, please see Create and Manage Agents.