NAME
Sim::Agent - Deterministic Orchestration Framework for Structured LLM Agent Experiments
SYNOPSIS
use Sim::Agent;
my $sim = Sim::Agent->new(plan => 'plan.sexpr');
$sim->run;ABSTRACT
Sim::Agent is a deterministic, single-threaded orchestration framework for Large Language Model (LLM) agents defined through a strict S-expression DSL. It is designed for controlled experimentation, auditability, and explicit coordination semantics rather than autonomous or emergent behavior.
The system enforces explicit topology, bounded self-reflection, critic gating, and reproducible journaling. It is particularly suited for research scenarios where repeatability, traceability, and architectural clarity are required.
MOTIVATION
Contemporary LLM agent frameworks often prioritize flexibility and autonomy over determinism and inspectability. This introduces:
Implicit control flow
Non-reproducible behavior
Unbounded reflection loops
Opaque state transitions
Hidden concurrency
Sim::Agent is intentionally designed in opposition to these tendencies. It treats agent orchestration as a formally structured computational graph with explicit routing, bounded cycles, and file-backed journaling.
The framework is not intended to simulate cognition; it is intended to simulate coordination.
DESIGN PRINCIPLES
1. Determinism
Scheduling is FIFO and single-threaded. There is no concurrency, no asynchronous dispatch, and no hidden background processes.
2. Explicit Topology
All control flow is declared in a strict S-expression DSL. There are no implicit retries, no emergent routing rules, and no hidden dependencies.
3. Bounded Self-Reflection
Workers may self-criticize and revise their outputs, but cycles are explicitly bounded via max_self_cycles.
4. Critic Gating
Critics determine whether outputs propagate forward in the graph. Critics return structured status:
{ status => 'ok' }
{ status => 'fail', critique => '...' }5. Ping-Pong Protection
Repeated critic-worker failure loops are bounded by max_pingpong. Upon exhaustion, flow proceeds with taint annotation.
6. Auditability
Every run produces a time-stamped journal directory containing:
Archived plan
Prompts and outputs per agent
Execution log
The journal provides full replay-level transparency.
7. No Hidden State
State is owned by the Runner and passed explicitly between agents. There is no shared mutable global context.
ARCHITECTURE
The system is composed of:
- Parser
-
Tokenizes and parses the S-expression DSL into an AST.
- Compiler
-
Validates references, resolves routing, injects default limits, and constructs the executable graph.
- Runner
-
Owns execution state, performs scheduling, invokes hooks, handles LLM calls, and manages routing.
- Engine
-
Pure helper logic for guard checks and dependency resolution.
- Hook System
-
Loads dynamic hook files returning coderefs for prompts, self-critique, revision, and critic parsing.
- Journal
-
Creates and manages run directories and structured logging.
- LLM Adapter
-
Current implementation uses shell-based Ollama invocation. Adapters are intentionally isolated from orchestration logic.
DSL OVERVIEW
Plans are defined as S-expressions:
(system
(limits ...)
(entry Worker1)
(agent Worker1 ...)
(agent Critic1 ...)
)The DSL is declarative. The graph is compiled before execution. Invalid references are rejected at compile time.
RESEARCH APPLICATIONS
Sim::Agent is appropriate for:
Structured evaluation of agent topologies
Controlled experiments in critic-based validation
Deterministic comparison of orchestration strategies
Exploration of bounded self-improvement cycles
Reproducible LLM workflow research
It is not intended as a production automation system. It is a research instrument.
LIMITATIONS
No concurrency
No distributed execution
No web browsing or tool autonomy
LLM-dependent variability in content (though structure is enforced)
These constraints are deliberate.
PHILOSOPHY
Sim::Agent rejects "vibe coding" and emergent orchestration. Every transition is declared. Every loop is bounded. Every output is journaled.
The framework assumes that coordination, not creativity, is the primary engineering challenge in multi-agent systems.
FUTURE DIRECTIONS
Potential research extensions include:
Deterministic replay mode
Formal schema declaration in DSL
Structured journal export (e.g., JSON traces)
Model-agnostic adapter abstraction
Patch-based self-improvement experiments under controlled conditions
AUTHOR
Gian Luca Brunetti (2026), gianluca.brunetti@gmail.com
AI tools were used to accelerate drafting and refactoring. No changes were merged without human review; the maintainer remains the sole accountable party for correctness, security, and licensing compliance.
LICENSE
GNU General Public License, Version 3.