Skip to content

Spec clarifications #192

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vvenz1n wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Spec clarifications #192

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
35fc641
docs: clarify branching support in nightly spec
vvenz1n May 20, 2026
09dcdbb
docs: note node table horizontal scrolling
vvenz1n May 20, 2026
555eb4f
docs: clarify duplicate inline definitions
vvenz1n May 20, 2026
d709b47
docs: clarify component reference scope
vvenz1n May 20, 2026
5d526b7
docs: exclude null from string conversion rule
vvenz1n May 20, 2026
fb72f3f
docs: clarify default value compatibility
vvenz1n May 20, 2026
eb67ad0
docs: clarify reference validity rules
vvenz1n May 21, 2026
b96ab0f
docs: clarify node parameter constraints
vvenz1n May 21, 2026
78f1d8a
docs: clarify map node IO rules
vvenz1n May 21, 2026
77de98b
docs: refine map node clarifications
vvenz1n May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 64 additions & 23 deletions docs/pyagentspec/source/agentspec/language_spec_nightly.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,28 @@ 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.

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.

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
Expand Down Expand Up @@ -171,13 +193,16 @@ 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.

@cesarebernardis cesarebernardis May 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a new limitation and a breaking change, we kept the conversion of any type to string for simplicity. I don't think we should add this.

@vvenz1n vvenz1n May 21, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

json-schema says that null can have exactly one value, and it’s null

https://json-schema.org/understanding-json-schema/reference/null#null

Given that strictness, I think it’s better to not allow converting it.

E.g. anyOf{string, null}  -> string , should not work IMO.

The target here wants a string, it doesn’t expect (or know) what to do with null

“null”  means explicitly “no value” or “absence of value”, so converting it into a value seems not correct to me.

@oracle-nish oracle-nish May 31, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might have several instances in an executor implementation where we would need anyOf{string, null} -> string.

1st example that comes to mind is:
An AgentSpec has a ToolNode / LLMNode accepts an output property which is an anyOf{string, null} with a default value of "null". Here, we may have an outgoing dataflow connection to an BranchingNode which needs to make a control flow decision based on the null value. Since we currently allow only string representations of mappings, executors might need to allow the anyOf{string, null} -> string conversion to happen to do mapping string compare check.

2nd (rather simpler) example: We may simply have a requirement to display a stringified "null" value to the user for specific cases where either a ToolNode/LLMNode/AgentNode returns null, which would require the data flow connection from anyOf{string, null} to string to be valid.

Hence, I do agree with @cesarebernardis that this rule can be made more lenient.

- 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.
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``;
Expand Down Expand Up @@ -1530,9 +1555,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
Expand Down Expand Up @@ -1594,9 +1620,14 @@ 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.

.. 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
Expand Down Expand Up @@ -1764,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::
Expand Down Expand Up @@ -1798,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.

@oracle-nish oracle-nish May 31, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vvenz1n Specific to MapNode, we agreed that the subflow's input/output types need not be exactly the same as the MapNode's "inner_type" within the input/output types, and that they can be castable. Can we mention this explicitly here?


- 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``, ``average``, ``max``, ``min``

- One, the default next
* - CatchExceptionNode
Expand Down Expand Up @@ -1860,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 <parallelization>`.
- .. list-table::
Expand Down Expand Up @@ -1893,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``, ``average``, ``max``, ``min``

- One, the default next
* - ParallelFlowNode
Expand Down
Loading