Agent Model
Declarative Agent graphs, explicit data-flow operations, and execution boundaries.
An Agent defines a computation as a graph of Templates. This document specifies how that graph is structured, how DataContainer values flow through it, and which responsibilities belong to the execution runtime.
For an introduction, see Agents. The Template Model defines the behaviour of individual Templates, including DataSplit and DataMerge.
1. Architectural role
The Agent Model describes the topology of computation: which Templates participate, how they connect, and which outputs are required by downstream operations.
It is separate from the other parts of the architecture:
| Concern | Responsibility |
|---|---|
| Agent Model | Graph structure and data-flow dependencies. |
| Template Model | Transformations and the semantics of split and merge operations. |
| Universal Data Transport (UDT) | Representation and exchange of DataContainer values. |
| Execution runtime | Scheduling and executing the declared graph. |
This separation allows the graph to describe a computation without prescribing the mechanism used to run it.
2. Graph contract
A Sinapsis Agent has a single external input and a single external output, each represented by a DataContainer.
Within the graph:
A normal Template consumes one
DataContainerand produces oneDataContainer.Connections between normal Templates carry
DataContainervalues, regardless of their payload types.Fan-out must be expressed through
DataSplit.Fan-in must be expressed through
DataMerge.
DataSplit and DataMerge are special graph operations whose input/output cardinality differs from that of a normal Template. Their copy, ownership, and merge semantics are defined in the Template Model.
The common Agent structure is a directed acyclic graph (DAG), but an arbitrary DAG is not necessarily a valid Sinapsis Agent. In particular, direct fan-out from a normal Template or direct fan-in to one is not permitted by this model. Branches must be represented explicitly, and the Agent must retain its single external input/output boundary.
3. Why Agents are declarative
An imperative pipeline directly controls execution by calling one operation after another. A declarative Agent instead defines the operations and their data-flow relationships, leaving execution to a runtime that must preserve those relationships.
This distinction is deliberate:
Composition: Templates can be connected through a common
DataContainercontract rather than custom interfaces for each pair of operations.Explicit dependencies: The graph makes the prerequisites of each operation visible, so a runtime can determine which work is eligible to execute and tools can inspect the structure before execution.
Controlled branching:
DataSplitandDataMergemake fan-out, fan-in, and their data-handling semantics part of the declared graph rather than implicit consequences of object references or control flow.Execution independence: A graph does not need to change merely because the runtime runs it sequentially, concurrently, locally, or across supported remote boundaries.
Memory management: Explicit data-flow boundaries make it easier for the runtime to track the lifecycle of intermediate
DataContainerobjects, identify when they are no longer needed, and release references. This reduces the risk of unintended memory retention and helps diagnose memory leaks.Data integrity and execution safety: Explicit dependencies and controlled branching reduce the risk of unintended modifications to shared
DataContainerobjects or individual packets. By making execution dependencies and ownership semantics explicit, the graph helps prevent side effects caused by execution order, shared mutable references, or concurrent operations.Debuggability and observability: The declarative graph provides a clear representation of the computation, making it easier to trace data through individual Templates, inspect intermediate
DataContainerstates, identify where unexpected modifications occur, and isolate failures to specific nodes or connections.
The graph is therefore the definition of the computation, not a transcript of how it happens to execute. Its single-input/single-output boundary and explicit split/merge operations constrain valid graph structures; they are not, by themselves, what makes the model declarative.
4. Graph structure and branching
An Agent may be linear, or it may contain branches that later converge. The following graph has one external input and output and two internal paths:
flowchart TD
IN([Agent input<br/>DataContainer]) --> A[Template A]
A --> S[DataSplit]
S --> B[Template B]
S --> C[Template C]
B --> M[DataMerge]
C --> M
M --> D[Template D]
D --> OUT([Agent output<br/>DataContainer])
Green-bordered nodes reference Sinapsis templates. Hover or focus them to fetch documentation.
View Mermaid source
flowchart TD
IN([Agent input<br/>DataContainer]) --> A[Template A]
A --> S[DataSplit]
S --> B[Template B]
S --> C[Template C]
B --> M[DataMerge]
C --> M
M --> D[Template D]
D --> OUT([Agent output<br/>DataContainer])
DataSplit establishes two downstream data paths, with the configured ownership and copying behaviour. DataMerge combines their outputs into a single downstream flow.
The Agent Model defines where these operations appear and how the paths connect. The Template Model defines how containers are copied and how packets or metadata are combined.
5. DataContainer flow
The same data boundary is used throughout an Agent:
DataContainer → Template → DataContainer
A DataContainer may include heterogeneous packets, such as images, text, audio, files, tensors, or structured metadata. A Template may transform or enrich its contents; another Template may then consume the resulting data without requiring a different graph-level interface.
For example, an object-detection Template may add annotations to an image packet. A downstream Template can use those annotations to produce crops or embeddings while continuing to exchange a DataContainer.
This common boundary does not imply that every Template can process every packet type. Each Template remains responsible for interpreting the data it uses.
An empty DataContainer is also valid as an Agent input or output. It does not require a separate graph interface.
6. Execution and transport boundaries
The runtime executes the graph while preserving its dependencies and data-flow semantics. In the branching example, both branch Templates depend on DataSplit, and the downstream path depends on DataMerge.
A runtime may support sequential or concurrent execution, remote workers, queues, or persisted intermediate data. These choices affect how the declared graph is executed, not what the Agent declares.
Similarly, the Agent Model does not prescribe serialization. Templates executing within one process may exchange Python DataContainer objects directly. When data crosses a process or service boundary, UDT provides its representation and exchange mechanisms; see UDT Architecture.
The Agent Model thus remains concerned with computation topology and dependencies, while runtime and transport mechanisms can evolve independently.
Published from Git revision 7b7ba25d627b