Getting Started Core Concepts

Core Concepts

AgentMesh separates workflow execution into two planes: the Python Data Plane (where LLM calls and domain logic reside) and the C++ Control Plane (where graph topology, wave scheduling, barrier synchronization, and state snapshots are processed).

 +------------------------------------------------------------------------+
 |                         PYTHON DATA PLANE                              |
 |   LangGraph StateGraph / Agent Functions / LLM Calls (Groq, Gemini)   |
 +-----------------------------------+------------------------------------+
                                     | (Zero-Copy Pybind11 FFI)
 +-----------------------------------v------------------------------------+
 |                     AGENTMESH C++ CONTROL PLANE                        |
 |                                                                        |
 |  +------------------------+         +-------------------------------+  |
 |  |   WorkflowGraph        |         |     PriorityReadyQueue        |  |
 |  |  - Spec Graph (DAG)    |<------->|  - Priority DESC / FIFO Tie   |  |
 |  |  - Dynamic Trace Nodes |         |  - Lock-Free Synchronized     |  |
 |  +-----------+------------+         +---------------+---------------+  |
 |              |                                      |                  |
 |              v                                      v                  |
 |  +------------------------+         +-------------------------------+  |
 |  |  Scheduler (O(1) Engine|<------->|     AsyncEventDispatcher      |  |
 |  |  - Atomic In-Degrees   |         |  - LocalWorkerPool            |  |
 |  |  - Dynamic Unrolling   |         |  - Non-Blocking Timers        |  |
 |  +-----------+------------+         +-------------------------------+  |
 |              |                                                         |
 |              v                                                         |
 |  +------------------------------------------------------------------+  |
 |  |        State Repository (PostgresStateRepository / RAM)          |  |
 |  |        - Transactional Snapshots & Crash Recovery in <5ms        |  |
 |  +------------------------------------------------------------------+  |
 +------------------------------------------------------------------------+

---

1. The Wave Execution Model

Instead of sequentially walking edges in Python, AgentMesh calculates independent topological frontiers called Waves:

• Wave 0: Entry nodes (__start__).
• Wave 1: Parallel branch nodes (e.g. 8 specialist agents).
• Wave 2: Barrier join aggregator.

When a wave contains multiple nodes, AgentMesh releases the CPython Global Interpreter Lock (GIL) and dispatches them across a C++ thread pool.

---

2. O(1) Atomic Barrier Joins

In typical DAG schedulers, joining $N$ parallel branches requires scanning predecessor statuses with $O(N)$ or $O(E)$ complexity. AgentMesh tracks predecessor in-degrees with atomic counters:

$$ ext{in_degree}(u) = \sum_{v \in ext{Pred}(u)} 1$$

When node $v$ finishes, it atomically decrements the in-degree counter of $u$. When $ ext{in_degree}(u) == 0$, node $u$ is pushed to PriorityReadyQueue in $O(1)$ time with zero mutex contention.

---

3. Channel Reduction Semantics

Channels in AgentMesh represent managed state keys. When multiple nodes in a wave emit updates to the same channel, AgentMesh merges them deterministically using registered binary operator reducers:

$$S_{k}^{(t+1)} = ext{Reducer}_k(S_{k}^{(t)}, \Delta_k)$$

Supported reducers include:

• operator.add for lists and integers.
• Custom binary lambdas lambda old, new: ....
• Default dictionary overwrite semantics for non-reduced fields.

---

4. Spec Graph vs. Dynamic Trace Graph

AgentMesh maintains a dual-tier graph model:

1. Static Spec Graph: The immutable definition containing node callables, static edges, and branch predicates.
2. Dynamic Trace Graph: An append-only execution history unrolled at runtime, supporting cycles, reflection loops, and dynamically spawned tasks (Send()) without mutating the base template.\n