From 35fc641ebf2970653f41f388507080872811ce15 Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Wed, 20 May 2026 16:46:52 +0200 Subject: [PATCH 01/10] docs: clarify branching support in nightly spec --- .../pyagentspec/source/agentspec/language_spec_nightly.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index e9a9851d..1e42faa2 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -1530,9 +1530,10 @@ Conditional branching in Agent Spec is supported through a special step called BranchingNode (detailed later), a node that maps input values to different branches through a key-value mapping. -Nodes can have multiple outgoing branches, as previously mentioned in this page. -The ``branches`` attribute of the Node is automatically filled and managed -by the implementation of the Node, but it will appear in the representation. Both +Only node types that explicitly support branching, such as ``BranchingNode`` +and ``FlowNode``, can have multiple outgoing branches. The ``branches`` attribute +of the Node is automatically filled and managed +by the implementation of those nodes, but it will appear in the representation. Both ``Node.branches`` and ``ControlFlowEdge.from_branch`` are set to null by default, and that is the default behavior in case one single branch is going out of a node (this is compatible with the definition of Node and From 09dcdbbfb411657b173bf67a9d9e86039c7baebb Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Wed, 20 May 2026 16:49:38 +0200 Subject: [PATCH 02/10] docs: note node table horizontal scrolling --- docs/pyagentspec/source/agentspec/language_spec_nightly.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index 1e42faa2..e1e03ad6 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -1598,6 +1598,9 @@ Here's the list of nodes supported in Agent Spec: A more detailed description of each node follows. +.. note:: + On narrower screens, the node table is horizontally scrollable. Scroll horizontally to view all columns. + .. list-table:: :widths: 5 20 15 15 15 15 :class: wideoutertable From 555eb4faf5f7fd6b2dff87a5f97cc0757c1b6466 Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Wed, 20 May 2026 16:56:30 +0200 Subject: [PATCH 03/10] docs: clarify duplicate inline definitions --- docs/pyagentspec/source/agentspec/language_spec_nightly.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index e1e03ad6..e1592430 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -82,6 +82,10 @@ Note that a subcomponent reused in multiple parts of a complex nested component a flow) must be defined using a component reference. If two components in an Agent Spec configuration use the same `id`, the configuration will be considered invalid. +Duplicate inline definitions are invalid even when they appear in different +fields. For example, a node with the same ``id`` must not be defined inline in +more than one of ``start_node``, ``nodes``, or ``$referenced_components``; +define it once and use ``$component_ref`` everywhere else. Input/output schemas From d709b474fe3d84da33f86d49ec7144e6aadb66b5 Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Wed, 20 May 2026 17:02:43 +0200 Subject: [PATCH 04/10] docs: clarify component reference scope --- .../pyagentspec/source/agentspec/language_spec_nightly.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index e1592430..ff8e132f 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -87,6 +87,13 @@ fields. For example, a node with the same ``id`` must not be defined inline in more than one of ``start_node``, ``nodes``, or ``$referenced_components``; define it once and use ``$component_ref`` everywhere else. +Component references are resolved from the referencing component outward through +its parent components. A nested component can reference a component defined by a +parent, including a node. A component cannot reference components that are only +defined inside one of its children or inside a sibling component. Component IDs +must be unique within a single Agent Spec configuration, including nested +components. + Input/output schemas -------------------- From 5d526b71498716ef1327bc8356ad3700e114f79a Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Wed, 20 May 2026 17:04:30 +0200 Subject: [PATCH 05/10] docs: exclude null from string conversion rule --- docs/pyagentspec/source/agentspec/language_spec_nightly.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index ff8e132f..d8a141ff 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -182,7 +182,7 @@ but an output of type ``string`` cannot connect to an input of type ``number``. In order to further simplify input-output connections, we define some simple type compatibility rules that are accepted by Agent Spec. -- Every type can be converted to string. +- Every type except ``null`` can be converted to string. - Numeric types (i.e., ``integer`` and ``number``) can be converted to each other. Note that this conversion could cause the loss of decimals. - The Boolean type can be converted to numeric ones and vice-versa. From fb72f3fef9ed1fd3e8f49a9d4ad56e471abc3ed0 Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Wed, 20 May 2026 17:08:29 +0200 Subject: [PATCH 06/10] docs: clarify default value compatibility --- docs/pyagentspec/source/agentspec/language_spec_nightly.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index d8a141ff..a388eaaa 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -189,6 +189,9 @@ In order to further simplify input-output connections, we define some simple typ The convention for the conversion is the one adopted by most programming languages: 0 refers to ``false``, while any other number refers to ``true``. +Default values follow the same compatibility rules. If a property defines ``default``, +that value must be compatible with the property's declared schema. + These rules apply recursively in complex types: - To the types of the elements of an ``array``; From eb67ad0ae9611f471f5ccd744d3fb8f90f8ad5e6 Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Thu, 21 May 2026 11:11:01 +0200 Subject: [PATCH 07/10] docs: clarify reference validity rules --- .../source/agentspec/language_spec_nightly.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index a388eaaa..0a757402 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -94,6 +94,17 @@ defined inside one of its children or inside a sibling component. Component IDs must be unique within a single Agent Spec configuration, including nested components. +Reference validity rules: + +- A ``$component_ref`` may appear multiple times; all occurrences resolve to the + same definition. +- A reference ID must be defined at most once in ``$referenced_components`` within + a serialized configuration. +- A reference is valid if it resolves to an in-scope ``$referenced_components`` entry + or to an externally supplied disaggregated component. +- If a reference is unresolved after external disaggregated components are supplied, + deserialization must fail. + Input/output schemas -------------------- From b96ab0f80dd0043a2879247dae5e22b8653ab8cd Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Thu, 21 May 2026 11:15:38 +0200 Subject: [PATCH 08/10] docs: clarify node parameter constraints --- docs/pyagentspec/source/agentspec/language_spec_nightly.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index 0a757402..ae8b532d 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -1620,6 +1620,8 @@ Here's the list of nodes supported in Agent Spec: - ParallelMapNode: performs a parallel map-reduce operation on a given input collection - ParallelFlowNode: execute a list of subflows in parallel +Node configurations must not include parameters outside the node type definition. + A more detailed description of each node follows. From 78f1d8ac0a844c93ec38555bfe5ec33c74a81820 Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Thu, 21 May 2026 11:41:08 +0200 Subject: [PATCH 09/10] docs: clarify map node IO rules --- .../agentspec/language_spec_nightly.rst | 38 ++++++++++++------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index ae8b532d..5067529d 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -1829,25 +1829,30 @@ A more detailed description of each node follows. - null, each output is aggregated through value concatenation (append) - Inferred from the inner structure (as defined in FlowNode). - The names of the inputs will be the ones of the inner flow, - complemented with the ``iterated_`` prefix. Their type is + The inputs must exactly match the inputs of the inner flow, + with each name complemented with the ``iterated_`` prefix. + Extra or missing inputs are invalid. Their type is ``Union[inner_type, List[inner_type]]``, where ``inner_type`` is the type of the respective input in the inner flow. - - If an input of type ``inner_type`` is connected, the same value will used in + - If an input of type ``inner_type`` is connected, the same value is used in all the executions of the inner flow - If an input of type ``List[inner_type]`` is connected, the input values will be iterated over + - If all inputs are scalar, the inner flow is executed once + - If multiple inputs are lists, they must have the same length and are consumed together for each execution Note that all the input lists must have the same length, otherwise a runtime error will be thrown. - Inferred from the inner structure (as defined in FlowNode), combined with the reducer method of each output. - The names of the outputs will be the ones of the inner flow, - complemented with the ``collected_`` prefix. Their type depends - on the ``reduce`` method specified for that output: + The outputs must exactly match the outputs of the inner flow, + with each name complemented with the ``collected_`` prefix. + Extra or missing outputs are invalid. Reducer keys must be inner output names; + missing reducers default to ``append``. + The output type depends on the reducer method specified for that output: - ``List`` of the respective output type in case of ``append`` - - same type of the respective output type in case of ``sum``, ``avg`` + - same type of the respective output type in case of ``sum``, ``avg``, ``max``, ``min`` - One, the default next * - CatchExceptionNode @@ -1924,25 +1929,30 @@ A more detailed description of each node follows. - null, each output is aggregated through value concatenation (append) - Inferred from the inner structure (as defined in FlowNode). - The names of the inputs will be the ones of the inner flow, - complemented with the ``iterated_`` prefix. Their type is + The inputs must exactly match the inputs of the inner flow, + with each name complemented with the ``iterated_`` prefix. + Extra or missing inputs are invalid. Their type is ``Union[inner_type, List[inner_type]]``, where ``inner_type`` is the type of the respective input in the inner flow. - - If an input of type ``inner_type`` is connected, the same value will used in + - If an input of type ``inner_type`` is connected, the same value is used in all the executions of the inner flow - If an input of type ``List[inner_type]`` is connected, the input values will be iterated over + - If all inputs are scalar, the inner flow is executed once + - If multiple inputs are lists, they must have the same length and are consumed together for each execution Note that all the input lists must have the same length, otherwise a runtime error will be thrown. - Inferred from the inner structure (as defined in FlowNode), combined with the reducer method of each output. - The names of the outputs will be the ones of the inner flow, - complemented with the ``collected_`` prefix. Their type depends - on the ``reduce`` method specified for that output: + The outputs must exactly match the outputs of the inner flow, + with each name complemented with the ``collected_`` prefix. + Extra or missing outputs are invalid. Reducer keys must be inner output names; + missing reducers default to ``append``. + The output type depends on the reducer method specified for that output: - ``List`` of the respective output type in case of ``append`` - - same type of the respective output type in case of ``sum``, ``avg`` + - same type of the respective output type in case of ``sum``, ``avg``, ``max``, ``min`` - One, the default next * - ParallelFlowNode From 77de98beba9c08d4aebb18ceaf3c3fef7747d9f1 Mon Sep 17 00:00:00 2001 From: Valentin Venzin Date: Thu, 21 May 2026 11:59:08 +0200 Subject: [PATCH 10/10] docs: refine map node clarifications --- .../source/agentspec/language_spec_nightly.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst index 5067529d..1c0a3c5c 100644 --- a/docs/pyagentspec/source/agentspec/language_spec_nightly.rst +++ b/docs/pyagentspec/source/agentspec/language_spec_nightly.rst @@ -1795,9 +1795,9 @@ A more detailed description of each node follows. It's the set of outputs defined in the ``subflow``'s specification - Inferred from the inner flow: one per unique ``branch_name`` of the ``subflow``'s EndNodes * - MapNode - - The MapNode is used when we need to map a sequence of nodes to each of the values - defined in a list (from output of a previous node). This node is responsible to - asynchronically map each value of a collection (defined in input_schema) to the first node + - The MapNode is used when we need to map a sequence of nodes to inputs + defined by a previous node. This node is responsible to + asynchronically map input values to the first node of the 'subflow' and reduce the outputs of the last node of the 'subflow' to defined variables (defined in output_schema) - .. list-table:: @@ -1852,7 +1852,7 @@ A more detailed description of each node follows. The output type depends on the reducer method specified for that output: - ``List`` of the respective output type in case of ``append`` - - same type of the respective output type in case of ``sum``, ``avg``, ``max``, ``min`` + - same type of the respective output type in case of ``sum``, ``average``, ``max``, ``min`` - One, the default next * - CatchExceptionNode @@ -1896,8 +1896,8 @@ A more detailed description of each node follows. * The branches of the ``sub_flow``; * A branch ``caught_exception_branch`` for when an exception is caught. * - ParallelMapNode - - The ParallelMapNode is used when we need to map a sequence of nodes to each of the values - defined in a list (from output of a previous node). Its functionality is equivalent to the MapNode, + - The ParallelMapNode is used when we need to map a sequence of nodes to inputs + defined by a previous node. Its functionality is equivalent to the MapNode, the only difference is that in this node the map operation is supposed to be performed in parallel. Please check the concerns regarding parallel execution depicted in the :ref:`parallelization section `. - .. list-table:: @@ -1952,7 +1952,7 @@ A more detailed description of each node follows. The output type depends on the reducer method specified for that output: - ``List`` of the respective output type in case of ``append`` - - same type of the respective output type in case of ``sum``, ``avg``, ``max``, ``min`` + - same type of the respective output type in case of ``sum``, ``average``, ``max``, ``min`` - One, the default next * - ParallelFlowNode