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.

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.

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.

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.

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.

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