AgentNode

An AgentNode represents the execution of an Agent within a Flow. The AgentNode node provides the graph-facing identity, typed inputs and outputs, branches, and reference to the Agent. The enclosing Flow defines the control-flow and data-flow edges associated with the node.

When the AgentNode executes, it supplies its input values to the referenced Agent. The Agent performs its iterative model reasoning and tool-calling loop using its instructions, LLM configuration, and the tools available to it. The Agent's result is returned through the AgentNode outputs. The Agent supports native tool calling, allowing supported models to request tool invocations through structured responses rather than prompt-based action instructions.

Component	Responsibility
`AgentNode`	Represents the Agent in the Flow and defines its graph-facing input, output, and branch contracts.
`Agent`	Performs iterative model reasoning and tool calling to produce the requested output.

Flow edges refer to the AgentNode, not directly to the referenced Agent. The AgentNode and Agent input and output contracts must be compatible. Tool implementations remain separate Tool definitions and are not defined by the AgentNode.

AgentNode Fields

Field	Requirement	Purpose
`component_type`	Required	Identifies the component as an AgentNode.
`id`	Required	Uniquely identifies the node for references and graph connections.
`name`	Required	Provides a human-readable component name.
`agent`	Required	Identifies the Agent executed by the node.
`inputs`	Optional	Declares the typed values supplied to the Agent when the node executes.
`outputs`	Optional	Declares the typed values returned from the Agent to the enclosing Flow.
`branches`	Optional	Declares named branches that outgoing control-flow edges can reference.

AgentNode Example

The surrounding Flow supplies a customer request to an AgentNode. The referenced Agent can use the order-lookup Tool while reasoning about the request and then produce a response.

Description of the illustration AgentNode Invocation in a Flow

AgentNode Component

The AgentNode defines how the Agent participates in the Flow:

{
  "component_type": "AgentNode",
  "id": "resolve-order-question",
  "name": "resolve_order_question",
  "inputs": [
    {
      "title": "request",
      "type": "string"
    }
  ],
  "outputs": [
    {
      "title": "response",
      "type": "string"
    }
  ],
  "branches": ["next"],
  "agent": {
    "$component_ref": "order-support-agent"
  }
}

The fields define the node's Flow-facing contract:

inputs declares the request value supplied through a data-flow edge.
outputs declares the response value made available after the Agent completes.
branches declares the next branch that an outgoing control-flow edge can reference.
agent identifies the Agent executed by the node. In this example, its $component_ref resolves to the Agent whose ID is order-support-agent.

The AgentNode does not contain model instructions, an LLM configuration, or tool definitions. These belong to the referenced Agent and the separately defined Tools.

Agent Component

The referenced Agent defines the model instructions, LLM configuration, and tools available during its iterative model reasoning and tool-calling loop:

{
  "component_type": "Agent",
  "id": "order-support-agent",
  "name": "order_support_agent",
  "inputs": [
    {
      "title": "request",
      "type": "string"
    }
  ],
  "outputs": [
    {
      "title": "response",
      "type": "string"
    }
  ],
  "llm_config": {
    "$component_ref": "application-llm-config"
  },
  "system_prompt": "Answer this order-support request using the tools available to you: {{ request }}",
  "tools": [
    {
      "$component_ref": "lookup-orders-tool"
    }
  ]
}

The Agent fields have the following roles:

id matches the $component_ref in the AgentNode.
inputs and outputs define a contract compatible with the AgentNode contract.
llm_config identifies the configuration used for model invocations.
system_prompt defines the Agent's task and incorporates named Agent inputs through prompt-template variables. For more information, see Prompt Templates and Rendering.
tools identifies the Tools available to the Agent. The referenced Tool definitions provide the corresponding implementations.

The Agent is not a node in the Flow and does not participate directly in the Flow's control-flow or data-flow connections.

How the Components Execute Together

A data-flow edge transfers StartNode.request to AgentNode.request.
When the AgentNode executes, the runtime resolves order-support-agent and supplies the request value to it.
The Agent renders {{ request }} with the supplied value and invokes the configured model.
During its iterative reasoning and tool-calling loop, the Agent can invoke lookup-orders-tool and provide the Tool result to a subsequent model invocation.
The Agent produces a final value that satisfies its response output contract. That value becomes AgentNode.response.
A data-flow edge transfers AgentNode.response to EndNode.response, while the outgoing control-flow edge describes the possible continuation to the EndNode.

Complete Runnable Agent Spec

The complete example uses a PL/SQL Tool so the Agent can retrieve an order status before producing its response.

Before running the example:

Create the database credential named AI_PROVIDER_CREDENTIAL.
Grant the executing database principal network access to api.openai.com.
Replace the provider, endpoint, model, and credential name if your environment uses different values.
Connect as the application schema before creating the example package and executing the Agent Spec.
Confirm that the application schema can create the example package and can execute DBMS_AI_AGENT.

For model-access setup, see LLM Configuration, Credentials, and Network Access.

Create the Example Tool

The following package provides the database operation available to the Agent:

CREATE OR REPLACE PACKAGE ORDER_TOOLS AS
  PROCEDURE LOOKUP_ORDER (
    ORDER_ID     IN  VARCHAR2,
    ORDER_STATUS OUT VARCHAR2
  );
END ORDER_TOOLS;
/

CREATE OR REPLACE PACKAGE BODY ORDER_TOOLS AS
  PROCEDURE LOOKUP_ORDER (
    ORDER_ID     IN  VARCHAR2,
    ORDER_STATUS OUT VARCHAR2
  ) IS
  BEGIN
    IF ORDER_ID = '7812' THEN
      ORDER_STATUS := 'OUT_FOR_DELIVERY';
    ELSE
      ORDER_STATUS := 'PROCESSING';
    END IF;
  END LOOKUP_ORDER;
END ORDER_TOOLS;
/

The Tool input and output titles in the Agent Spec match the PL/SQL parameter names ORDER_ID and ORDER_STATUS.

Execute the Complete Agent Spec

SET SERVEROUTPUT ON SIZE UNLIMITED
SET DEFINE OFF

DECLARE
  L_AGENT_SPEC CLOB := q'~
{
  "component_type": "Flow",
  "agentspec_version": "25.4.1",
  "id": "agent-node-example-flow",
  "name": "agent_node_example_flow",
  "inputs": [
    {
      "title": "request",
      "type": "string"
    }
  ],
  "outputs": [
    {
      "title": "response",
      "type": "string",
      "default": ""
    }
  ],
  "start_node": {
    "$component_ref": "start"
  },
  "nodes": [
    {
      "$component_ref": "start"
    },
    {
      "$component_ref": "resolve-order-question"
    },
    {
      "$component_ref": "end"
    }
  ],
  "control_flow_connections": [
    {
      "component_type": "ControlFlowEdge",
      "id": "start-to-agent",
      "name": "start_to_agent",
      "from_node": {
        "$component_ref": "start"
      },
      "to_node": {
        "$component_ref": "resolve-order-question"
      }
    },
    {
      "component_type": "ControlFlowEdge",
      "id": "agent-to-end",
      "name": "agent_to_end",
      "from_node": {
        "$component_ref": "resolve-order-question"
      },
      "to_node": {
        "$component_ref": "end"
      }
    }
  ],
  "data_flow_connections": [
    {
      "component_type": "DataFlowEdge",
      "id": "request-to-agent",
      "name": "request_to_agent",
      "source_node": {
        "$component_ref": "start"
      },
      "source_output": "request",
      "destination_node": {
        "$component_ref": "resolve-order-question"
      },
      "destination_input": "request"
    },
    {
      "component_type": "DataFlowEdge",
      "id": "agent-response-to-end",
      "name": "agent_response_to_end",
      "source_node": {
        "$component_ref": "resolve-order-question"
      },
      "source_output": "response",
      "destination_node": {
        "$component_ref": "end"
      },
      "destination_input": "response"
    }
  ],
  "$referenced_components": {
    "start": {
      "component_type": "StartNode",
      "id": "start",
      "name": "start",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "branches": [
        "next"
      ]
    },
    "resolve-order-question": {
      "component_type": "AgentNode",
      "id": "resolve-order-question",
      "name": "resolve_order_question",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string",
          "default": ""
        }
      ],
      "branches": [
        "next"
      ],
      "agent": {
        "$component_ref": "order-support-agent"
      }
    },
    "end": {
      "component_type": "EndNode",
      "id": "end",
      "name": "end",
      "inputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "branches": [],
      "branch_name": "next"
    },
    "order-support-agent": {
      "component_type": "Agent",
      "id": "order-support-agent",
      "name": "order_support_agent",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string",
          "default": ""
        }
      ],
      "llm_config": {
        "$component_ref": "application-llm-config"
      },
      "system_prompt": "Answer this order-support request. For current order status, invoke lookup_order instead of inferring a value. Request: {{request}}",
      "tools": [
        {
          "$component_ref": "lookup-orders-tool"
        }
      ],
      "$referenced_components": {
        "lookup-orders-tool": {
          "component_type": "BuiltinTool",
          "id": "lookup-orders-tool",
          "name": "lookup_order",
          "description": "Return the current status of an order.",
          "inputs": [
            {
              "title": "order_id",
              "type": "string"
            }
          ],
          "outputs": [
            {
              "title": "order_status",
              "type": "string"
            }
          ],
          "requires_confirmation": false,
          "executor_name": "Oracle In-DB Agent Executor",
          "tool_version": "1.0",
          "tool_type": "plsql_exec",
          "configuration": {
            "package_name": "ORDER_TOOLS",
            "procedure_name": "LOOKUP_ORDER"
          }
        }
      }
    },
    "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": 300,
        "temperature": 0,
        "top_p": 1
      }
    }
  }
}
~';

  L_INPUTS CLOB := TO_CLOB (
    '[{"name":"request","value":"Where is order 7812?"}]'
  );
  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 one possible result is:

{
  "response": "Order 7812 is out for delivery."
}

One possible execution proceeds as follows:

StartNode.request is transferred to AgentNode.request.
The AgentNode resolves order-support-agent and supplies the request.
The Agent invokes the configured model with its instructions, request, and description of lookup_order.
The model requests lookup_order with order_id set to 7812.
The runtime validates the arguments and invokes ORDER_TOOLS.LOOKUP_ORDER.
The returned OUT_FOR_DELIVERY value is added to the Agent's context for a later model invocation.
The Agent produces response, which becomes AgentNode.response.
The outgoing data-flow edge transfers the response to EndNode, and the Flow returns it to the API caller.

The precise number of model invocations is determined by the model's decisions during this execution.