Common Agent Spec Component Fields

An Agent Spec is composed of typed JSON objects called components. A component can represent a complete executable workflow, a Flow node, an edge, a model configuration, or a tool.

Every component type has its own schema. Several identity and descriptive fields recur across those schemas and give the document a consistent structure.

Common Identity and Descriptive Fields

Field	Description
component_type	Case-sensitive name of the component type.
id	Unique component identity within the applicable scope.
name	Readable name for people and tooling.
description	Optional explanation of the component's purpose.
metadata	Optional application metadata admitted by the component schema.
agentspec_version	Agent Spec version where the component schema admits this field.

The schema for a specific component determines which fields are required and which optional fields are accepted. Not every component type accepts or requires the full set of the above fields.

Component Type

The component_type selects the schema and behavior for an object:

{
  "component_type": "StartNode",
  "id": "receive-request",
  "name": "receive_request"
}

Component type values should be one of the provided values and are case-sensitive. StartNode and startnode are different strings; only the supported value identifies the StartNode component.

The type also determines the component-specific fields. For example:

Component	Examples of type-specific fields
Flow	start_node, nodes, control_flow_connections and data_flow_connections
Agent	system_prompt, llm_config, and tools
ToolNode	tool, inputs, and outputs
ControlFlowEdge	from_node, from_branch, and to_node
DataFlowEdge	source_node, source_output, and destination_node

Those fields are explained on the corresponding component or building-block page.

Component ID

The id uniquely identifies a component within the applicable reference scope. The runtime uses this identifier to resolve component references and graph connections. When a component definition is reused, each $component_ref contains the component’s id.

{
  "component_type": "EndNode",
  "id": "return-order-status",
  "name": "return_order_status"
}

Human-readable ID values such as return-order-status make Agent Spec definitions, errors, and traces easier to understand.

Component Name

The name is a readable component label. It can follow an application's naming convention and does not have to equal the ID.

{
  "component_type": "ToolNode",
  "id": "lookup-order",
  "name": "lookup_order"
}

Two components are not the same component merely because their names match. References contain the target component's ID, not its name.

Component Description

The optional description records the component's purpose:

{
  "component_type": "ToolNode",
  "id": "lookup-order",
  "name": "lookup_order",
  "description": "Returns the current status for one order."
}

A useful description explains the business role or boundary of a component without repeating its name.

Component Metadata

The optional metadata object carries application-defined information when the component schema admits it:

{
  "component_type": "ToolNode",
  "id": "lookup-order",
  "name": "lookup_order",
  "metadata": {
    "domain": "order_support",
    "owner": "customer_service"
  }
}

Metadata does not replace fields that affect execution. Scheduling belongs in control-flow edges, value types belong in endpoint contracts, and executable configuration belongs in the component fields defined for that purpose.

Agent Spec Version

agentspec_version identifies the Agent Spec version used by a definition where the schema admits it:

{
  "component_type": "Flow",
  "agentspec_version": "26.1.0",
  "id": "order-status-flow",
  "name": "order_status_flow"
}

The value must be supported by the target database release. Component availability and accepted fields are evaluated according to the supported schema, rather than inferred from the version string alone.