Skip to main content
MirrorNeuron keeps its built-in agent set intentionally small. Rather than shipping domain-specific personas, the runtime gives you four composable primitives — router, executor, aggregator, and sensor — that you combine through manifest-defined graphs. Each primitive covers a distinct role in a workflow: fanning work out, running isolated code, collecting results, or waiting for external signals. On top of these primitives, a set of behavioral templates lets you tune how each agent processes messages without writing custom runtime code.

​
The four built-in agent types

You select an agent’s primitive by setting agent_type on the node in your manifest.json. Every node must declare exactly one agent_type.

​
router

A router receives an incoming message and re-emits it to downstream nodes. It does not execute external code and does not hold multi-message state. By default it forwards the message using the incoming type, but you can override the outgoing message type with config.emit_type. Use a router when you need to:
  • Fan a single input out to multiple parallel workers
  • Rename or retype a message as it moves through the graph
  • Act as the entry point (root_coordinator) that seeds work across other agents
{
  "node_id": "ingress",
  "agent_type": "router",
  "type": "map",
  "role": "root_coordinator",
  "config": {
    "emit_type": "research_request"
  }
}

​
executor

An executor requests an execution lease, runs a command in an OpenShell sandbox, and then emits the result. It is the only built-in primitive that leaves the BEAM process boundary — every other primitive stays in the control plane. Before running, an executor node acquires a slot from its assigned executor pool. If no slot is available, the request queues until capacity is freed. This keeps sandbox concurrency bounded regardless of how many logical workers are waiting. Use an executor when you need to:
  • Run a Python script or shell command inside an isolated sandbox
  • Perform CPU- or I/O-heavy work that should not block BEAM
  • Process uploaded payloads from the payloads/ directory
{
  "node_id": "summarizer_worker",
  "agent_type": "executor",
  "type": "map",
  "config": {
    "pool": "default",
    "pool_slots": 1,
    "uploads": [
      {
        "source": "summarize.py",
        "target": "/app/summarize.py"
      }
    ],
    "command": ["python3", "/app/summarize.py"]
  }
}
The source path inside uploads is resolved relative to the payloads/ directory in your job bundle. See Job bundles for the full directory structure.

​
aggregator

An aggregator accumulates messages from upstream agents and combines them into a single result. It tracks which agent IDs it has already seen to deduplicate deliveries, and it signals job completion once a configurable threshold is met. You control completion with two config keys:
  • complete_on_message — complete the job as soon as the first message arrives
  • complete_after — complete the job after a specific number of messages have been collected
Use an aggregator when you need to:
  • Collect results from a fan-out of parallel executor workers
  • Wait for all branches of a graph to report back before completing
  • Deduplicate result messages from retried agents
{
  "node_id": "result_collector",
  "agent_type": "aggregator",
  "type": "reduce",
  "config": {
    "complete_on_message": true
  }
}
Set output_message_type on an aggregator to forward the combined result to another node instead of completing the job immediately.

​
sensor

A sensor observes incoming messages and re-emits them downstream, tracking an observation count. It is designed for deferred or trigger-style patterns — for example, waiting for an external signal before allowing the rest of the graph to proceed. By default, a sensor emits a sensor_ready message for each observation. You can override this with config.output_message_type. Set complete_after to complete the job once a target number of observations has been recorded. Use a sensor when you need to:
  • Gate downstream work on an external event or signal
  • Forward streaming telemetry data through the graph
  • Observe and relay messages without modifying them
{
  "node_id": "signal_gate",
  "agent_type": "sensor",
  "config": {
    "output_message_type": "pipeline_ready",
    "complete_after": 1
  }
}

​
Agent templates

Every node also carries a type field that selects a behavioral template. Templates provide reusable message-handling patterns that work on top of the primitive. If you omit type, it defaults to "generic".
The default template. It provides no additional state or behavior beyond what the underlying primitive defines. Use generic when none of the specialized templates fit or when you are building custom agent behavior.
Tracks a processed counter and emits a map_transformed event for each message handled. Use map on router or executor nodes that fan out one input per message — for example, dispatching one work item per incoming record.
Accumulates messages into a list and tracks complete_on_message and complete_after thresholds. When the completion condition is met, it triggers a complete_job action with the collected results. Use reduce on aggregator nodes that gather results from parallel branches.
Tracks chunks_received and items_seen across a stream of messages. Emits a stream_chunk_processed event per chunk. Use stream when an agent is processing a continuous or chunked data feed.
Buffers incoming items until a batch_size threshold is reached, then flushes the batch and resets the buffer. Emits a batch_buffered event on each push. Use batch when you want to group messages before forwarding them to an executor or downstream node.
Shares the same collect-and-complete behavior as reduce. Use accumulator as a semantic alias when you want to make it explicit that an agent is accumulating state across messages rather than reducing a fan-out.

​
Combining agent_type and type

The agent_type field picks the primitive, and the type field picks the template. The two work together: not every template is valid for every primitive — the manifest validator will reject incompatible combinations at load time. 
{
  "node_id": "dispatcher",
  "agent_type": "router",
  "type": "map"
}

{
  "node_id": "worker",
  "agent_type": "executor",
  "type": "generic"
}

{
  "node_id": "collector",
  "agent_type": "aggregator",
  "type": "reduce"
}
If you specify an agent_type and type combination that the runtime does not support, ./mirror_neuron validate will return an error before the job runs. Always validate your bundle before deploying.