BranchingNode

A BranchingNode selects one of its declared branches based on an input value, such as a request category, approval result, or order status. Its mapping associates each supported input value with a branch name. When the BranchingNode executes, the runtime reads its decision input, finds the corresponding branch name in the mapping, and selects that branch. Outgoing control-flow edges whose from_branch value matches the selected branch identify the nodes that can execute next. Edges associated with the other branches are not followed for that execution.

The branch selection controls execution but does not transfer the decision value or any other data. Separate data-flow edges provide values required by the selected destination nodes.

Description of the illustration BranchingNode Multi-Route Support Flow

BranchingNode Fields

Field	Requirement	Purpose
`component_type`	Required	Identifies the component as a `BranchingNode`.
`id`	Required	Uniquely identifies the node for references and graph connections.
`name`	Required	Provides a human-readable component name.
`inputs`	Required	Declares exactly one typed input whose value determines the selected branch.
`mapping`	Conditionally required	Associates accepted input values with branch names. It is required when the node has multiple outgoing control-flow edges and can be omitted when there is only one.
`branches`	Required	Declares the branch names available from the node. These names correspond to its outgoing control-flow edges.

Each value in mapping must exactly match a name in branches. Every entry in branches must have a corresponding outgoing ControlFlowEdge whose from_node references the BranchingNode and whose from_branch has the same name.

BranchingNode Example

An online store classifies each support request before sending it to a specialized handler. The BranchingNode receives the classification in request_type and maps it to one of three declared branches:

`request_type` value	Selected branch	Node that can execute next
`where_is_order`	`order_status`	`order-status-handler`
`start_return`	`return_request`	`return-handler`
`other`	`general_question`	`general-question-handler`

The surrounding control-flow structure is:

Description of the illustration BranchingNode Control-Flow Fan-Out

The following fragment defines the branching decision:

{
  "component_type": "BranchingNode",
  "id": "route-support-request",
  "name": "route_support_request",
  "inputs": [
    {
      "title": "request_type",
      "type": "string"
    }
  ],
  "outputs": [],
  "branches": [
    "order_status",
    "return_request",
    "general_question"
  ],
  "mapping": {
    "where_is_order": "order_status",
    "start_return": "return_request",
    "other": "general_question"
  }
}

The keys in mapping are accepted request_type values. Each mapping value names the branch selected for that input. The names must exactly match the entries in branches.

The outgoing control-flow edges associate the declared branches with possible next nodes:

[
  {
    "component_type": "ControlFlowEdge",
    "id": "route-to-order-status",
    "name": "route_to_order_status",
    "from_node": {
      "$component_ref": "route-support-request"
    },
    "from_branch": "order_status",
    "to_node": {
      "$component_ref": "order-status-handler"
    }
  },
  {
    "component_type": "ControlFlowEdge",
    "id": "route-to-return-handler",
    "name": "route_to_return_handler",
    "from_node": {
      "$component_ref": "route-support-request"
    },
    "from_branch": "return_request",
    "to_node": {
      "$component_ref": "return-handler"
    }
  },
  {
    "component_type": "ControlFlowEdge",
    "id": "route-to-general-question",
    "name": "route_to_general_question",
    "from_node": {
      "$component_ref": "route-support-request"
    },
    "from_branch": "general_question",
    "to_node": {
      "$component_ref": "general-question-handler"
    }
  }
]

For example, suppose request_type has the value start_return:

A data-flow edge transfers StartNode.request_type to BranchingNode.request_type.
The runtime finds start_return in mapping and selects the return_request branch.
The outgoing control-flow edge whose from_branch is return_request identifies return-handler as a node that can execute next.
The control-flow edges for order_status and general_question are not followed for this execution.

Branch selection does not transfer the complete customer request. Separate data-flow edges provide the request to the handlers that may consume it:

Description of the illustration BranchingNode Data-Flow Mappings

These data-flow edges make the request values available but do not determine which handler executes. The selected branch determines the applicable control-flow continuation.

Complete Runnable Agent Spec

The complete example routes one request to one of three PL/SQL handlers. Each handler returns a different response, making the selected branch visible in the Flow output.

This example does not require an LLM configuration, credential, or network ACL. The application schema must be able to create the example package and execute DBMS_AI_AGENT.

Create the Example Handlers

Connect as the application schema and create the following package:

CREATE OR REPLACE PACKAGE SUPPORT_HANDLERS AS
  PROCEDURE HANDLE_ORDER_STATUS (
    REQUEST  IN  VARCHAR2,
    RESPONSE OUT VARCHAR2
  );

  PROCEDURE HANDLE_RETURN_REQUEST (
    REQUEST  IN  VARCHAR2,
    RESPONSE OUT VARCHAR2
  );

  PROCEDURE HANDLE_GENERAL_QUESTION (
    REQUEST  IN  VARCHAR2,
    RESPONSE OUT VARCHAR2
  );
END SUPPORT_HANDLERS;
/

CREATE OR REPLACE PACKAGE BODY SUPPORT_HANDLERS AS
  PROCEDURE HANDLE_ORDER_STATUS (
    REQUEST  IN  VARCHAR2,
    RESPONSE OUT VARCHAR2
  ) IS
  BEGIN
    RESPONSE := 'Order-status request received: ' || REQUEST;
  END HANDLE_ORDER_STATUS;

  PROCEDURE HANDLE_RETURN_REQUEST (
    REQUEST  IN  VARCHAR2,
    RESPONSE OUT VARCHAR2
  ) IS
  BEGIN
    RESPONSE := 'Return request received: ' || REQUEST;
  END HANDLE_RETURN_REQUEST;

  PROCEDURE HANDLE_GENERAL_QUESTION (
    REQUEST  IN  VARCHAR2,
    RESPONSE OUT VARCHAR2
  ) IS
  BEGIN
    RESPONSE := 'General question received: ' || REQUEST;
  END HANDLE_GENERAL_QUESTION;
END SUPPORT_HANDLERS;
/

Execute the Complete Agent Spec

The example supplies start_return as request_type, so the return_request branch reaches return-handler.

SET SERVEROUTPUT ON SIZE UNLIMITED
SET DEFINE OFF

DECLARE
  L_AGENT_SPEC CLOB := q'~
{
  "component_type": "Flow",
  "agentspec_version": "25.4.1",
  "id": "branching-node-example-flow",
  "name": "branching_node_example_flow",
  "inputs": [
    {
      "title": "request_type",
      "type": "string"
    },
    {
      "title": "request",
      "type": "string"
    }
  ],
  "outputs": [
    {
      "title": "response",
      "type": "string"
    }
  ],
  "start_node": {
    "$component_ref": "start"
  },
  "nodes": [
    {
      "$component_ref": "start"
    },
    {
      "$component_ref": "route-support-request"
    },
    {
      "$component_ref": "order-status-handler"
    },
    {
      "$component_ref": "return-handler"
    },
    {
      "$component_ref": "general-question-handler"
    },
    {
      "$component_ref": "order-status-end"
    },
    {
      "$component_ref": "return-end"
    },
    {
      "$component_ref": "general-question-end"
    }
  ],
  "control_flow_connections": [
    {
      "component_type": "ControlFlowEdge",
      "id": "start-to-router",
      "name": "start_to_router",
      "from_node": {
        "$component_ref": "start"
      },
      "to_node": {
        "$component_ref": "route-support-request"
      }
    },
    {
      "component_type": "ControlFlowEdge",
      "id": "route-to-order-status",
      "name": "route_to_order_status",
      "from_node": {
        "$component_ref": "route-support-request"
      },
      "from_branch": "order_status",
      "to_node": {
        "$component_ref": "order-status-handler"
      }
    },
    {
      "component_type": "ControlFlowEdge",
      "id": "route-to-return-handler",
      "name": "route_to_return_handler",
      "from_node": {
        "$component_ref": "route-support-request"
      },
      "from_branch": "return_request",
      "to_node": {
        "$component_ref": "return-handler"
      }
    },
    {
      "component_type": "ControlFlowEdge",
      "id": "route-to-general-question",
      "name": "route_to_general_question",
      "from_node": {
        "$component_ref": "route-support-request"
      },
      "from_branch": "general_question",
      "to_node": {
        "$component_ref": "general-question-handler"
      }
    },
    {
      "component_type": "ControlFlowEdge",
      "id": "default-to-general-question",
      "name": "default_to_general_question",
      "from_node": {
        "$component_ref": "route-support-request"
      },
      "from_branch": "default",
      "to_node": {
        "$component_ref": "general-question-handler"
      }
    },
    {
      "component_type": "ControlFlowEdge",
      "id": "order-status-to-end",
      "name": "order_status_to_end",
      "from_node": {
        "$component_ref": "order-status-handler"
      },
      "to_node": {
        "$component_ref": "order-status-end"
      }
    },
    {
      "component_type": "ControlFlowEdge",
      "id": "return-to-end",
      "name": "return_to_end",
      "from_node": {
        "$component_ref": "return-handler"
      },
      "to_node": {
        "$component_ref": "return-end"
      }
    },
    {
      "component_type": "ControlFlowEdge",
      "id": "general-question-to-end",
      "name": "general_question_to_end",
      "from_node": {
        "$component_ref": "general-question-handler"
      },
      "to_node": {
        "$component_ref": "general-question-end"
      }
    }
  ],
  "data_flow_connections": [
    {
      "component_type": "DataFlowEdge",
      "id": "request-type-to-router",
      "name": "request_type_to_router",
      "source_node": {
        "$component_ref": "start"
      },
      "source_output": "request_type",
      "destination_node": {
        "$component_ref": "route-support-request"
      },
      "destination_input": "request_type"
    },
    {
      "component_type": "DataFlowEdge",
      "id": "request-to-order-status",
      "name": "request_to_order_status",
      "source_node": {
        "$component_ref": "start"
      },
      "source_output": "request",
      "destination_node": {
        "$component_ref": "order-status-handler"
      },
      "destination_input": "request"
    },
    {
      "component_type": "DataFlowEdge",
      "id": "request-to-return",
      "name": "request_to_return",
      "source_node": {
        "$component_ref": "start"
      },
      "source_output": "request",
      "destination_node": {
        "$component_ref": "return-handler"
      },
      "destination_input": "request"
    },
    {
      "component_type": "DataFlowEdge",
      "id": "request-to-general-question",
      "name": "request_to_general_question",
      "source_node": {
        "$component_ref": "start"
      },
      "source_output": "request",
      "destination_node": {
        "$component_ref": "general-question-handler"
      },
      "destination_input": "request"
    },
    {
      "component_type": "DataFlowEdge",
      "id": "order-status-response-to-end",
      "name": "order_status_response_to_end",
      "source_node": {
        "$component_ref": "order-status-handler"
      },
      "source_output": "response",
      "destination_node": {
        "$component_ref": "order-status-end"
      },
      "destination_input": "response"
    },
    {
      "component_type": "DataFlowEdge",
      "id": "return-response-to-end",
      "name": "return_response_to_end",
      "source_node": {
        "$component_ref": "return-handler"
      },
      "source_output": "response",
      "destination_node": {
        "$component_ref": "return-end"
      },
      "destination_input": "response"
    },
    {
      "component_type": "DataFlowEdge",
      "id": "general-response-to-end",
      "name": "general_response_to_end",
      "source_node": {
        "$component_ref": "general-question-handler"
      },
      "source_output": "response",
      "destination_node": {
        "$component_ref": "general-question-end"
      },
      "destination_input": "response"
    }
  ],
  "$referenced_components": {
    "start": {
      "component_type": "StartNode",
      "id": "start",
      "name": "start",
      "inputs": [
        {
          "title": "request_type",
          "type": "string"
        },
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "request_type",
          "type": "string"
        },
        {
          "title": "request",
          "type": "string"
        }
      ],
      "branches": [
        "next"
      ]
    },
    "route-support-request": {
      "component_type": "BranchingNode",
      "id": "route-support-request",
      "name": "route_support_request",
      "inputs": [
        {
          "title": "request_type",
          "type": "string"
        }
      ],
      "outputs": [],
      "branches": [
        "order_status",
        "return_request",
        "general_question",
        "default"
      ],
      "mapping": {
        "where_is_order": "order_status",
        "start_return": "return_request",
        "other": "general_question"
      }
    },
    "order-status-handler": {
      "component_type": "ToolNode",
      "id": "order-status-handler",
      "name": "order_status_handler",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "branches": [
        "next"
      ],
      "tool": {
        "$component_ref": "order-status-tool"
      }
    },
    "return-handler": {
      "component_type": "ToolNode",
      "id": "return-handler",
      "name": "return_handler",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "branches": [
        "next"
      ],
      "tool": {
        "$component_ref": "return-request-tool"
      }
    },
    "general-question-handler": {
      "component_type": "ToolNode",
      "id": "general-question-handler",
      "name": "general_question_handler",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "branches": [
        "next"
      ],
      "tool": {
        "$component_ref": "general-question-tool"
      }
    },
    "order-status-end": {
      "component_type": "EndNode",
      "id": "order-status-end",
      "name": "order_status_end",
      "inputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "branches": [],
      "branch_name": "next"
    },
    "return-end": {
      "component_type": "EndNode",
      "id": "return-end",
      "name": "return_end",
      "inputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "branches": [],
      "branch_name": "next"
    },
    "general-question-end": {
      "component_type": "EndNode",
      "id": "general-question-end",
      "name": "general_question_end",
      "inputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "branches": [],
      "branch_name": "next"
    },
    "order-status-tool": {
      "component_type": "BuiltinTool",
      "id": "order-status-tool",
      "name": "handle_order_status",
      "description": "Handle an order-status request.",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "requires_confirmation": false,
      "executor_name": "Oracle In-DB Agent Executor",
      "tool_version": "1.0",
      "tool_type": "plsql_exec",
      "configuration": {
        "package_name": "SUPPORT_HANDLERS",
        "procedure_name": "HANDLE_ORDER_STATUS"
      }
    },
    "return-request-tool": {
      "component_type": "BuiltinTool",
      "id": "return-request-tool",
      "name": "handle_return_request",
      "description": "Handle a return request.",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "requires_confirmation": false,
      "executor_name": "Oracle In-DB Agent Executor",
      "tool_version": "1.0",
      "tool_type": "plsql_exec",
      "configuration": {
        "package_name": "SUPPORT_HANDLERS",
        "procedure_name": "HANDLE_RETURN_REQUEST"
      }
    },
    "general-question-tool": {
      "component_type": "BuiltinTool",
      "id": "general-question-tool",
      "name": "handle_general_question",
      "description": "Handle a general support question.",
      "inputs": [
        {
          "title": "request",
          "type": "string"
        }
      ],
      "outputs": [
        {
          "title": "response",
          "type": "string"
        }
      ],
      "requires_confirmation": false,
      "executor_name": "Oracle In-DB Agent Executor",
      "tool_version": "1.0",
      "tool_type": "plsql_exec",
      "configuration": {
        "package_name": "SUPPORT_HANDLERS",
        "procedure_name": "HANDLE_GENERAL_QUESTION"
      }
    }
  }
}
~';

  L_INPUTS CLOB := TO_CLOB (
    '[{"name":"request_type","value":"start_return"},'
    || '{"name":"request","value":"I want to return 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 returned JSON has the following form:

{
  "response": "Return request received: I want to return order 7812."
}

In this execution:

StartNode publishes request_type and request.
A data-flow edge supplies start_return to BranchingNode.request_type.
The BranchingNode maps start_return to return_request.
The control-flow edge for return_request identifies return-handler as a node that can execute next. The other handler edges are not followed.
The data-flow edge from StartNode.request makes the request available to return-handler.
return-handler invokes SUPPORT_HANDLERS.HANDLE_RETURN_REQUEST.
The Tool result is transferred to return-end, which returns it through the Flow output contract.

Changing request_type to where_is_order or other selects the corresponding handler and produces a response from that branch.