System on an Agent

Instead of system on a chip, system on an agent.

A system on a chip,
but on an agent.

A system on a chip puts a CPU, memory, I/O, and a bus on one piece of silicon. A system on an agent puts the same parts into one agent: a planner as the processor, memory and skills as storage, connectors as input and output, and a bus that ties them together.

View the repository Read the core PR

The same blocks, retitled

The floorplan stays the same. Each SoC block has a counterpart on the agent.

Mapping from a system on a chip to a system on an agent: CPU to planner, memory to memory and skills, I/O to connectors, and bus to bus or router.
System on a Chip SoC
Processor CPU
Storage Memory
Input / output I/O
Interconnect Bus
System on an Agent SoA
Processor Planner
Storage Memory + Skills
Input / output Connectors
Interconnect Bus / Router
  • CPUPlanner
  • MemoryMemory + Skills
  • I/OConnectors
  • BusBus / Router

The core

Four parts, and only these four. Optional add-ons plug in later, beside the core, never into it.

Processor

Planner

Takes a goal, builds a plan, and runs it step by step. The default planner is deterministic and rule-based; no language model is required. An optional language-model provider can be attached later. If the model fails to return a valid plan, the rule-based planner is the fallback.

Storage

Memory and skills

Working memory holds short-lived values for the current run. Long-term memory stores facts, optionally persisted as JSON. The skill library is a set of reusable named procedures the planner can run.

Input / output

Connectors

A pluggable I/O surface. The core ships a local file connector and an echo (mock) connector, and new connectors can be registered on the same interface.

Interconnect

Bus / Router

Routes messages between the planner, memory, skills, and connectors, and fires add-on hooks around each step without those add-ons living in the core.

Quickstart

Python 3.10 or newer. The demo below is a real run of the mock connector, from the core on this repository.

soa run
$ python -m pip install -e ".[dev]"
$ soa run "echo hello from system on an agent"
goal: echo hello from system on an agent
plan: 1 step (rules)
  1. Send "hello from system on an agent" through the echo connector
ok: true
output: hello from system on an agent

Also available: soa skills list and soa connectors list.

Optional add-ons

Add-ons sit beside the core. They never live inside it, and loading or omitting them does not require a core change. Load one from a Python file or a directory with soa_addon.py or addon.py. It declares a manifest and the hooks it implements.

soa --addon path/to/addon.py run "echo hello"

before_plan(plan, context)
after_plan(plan, report, context)
before_step(step, context)
after_step(step, result, context)
on_error(step, error, context)

Two names are reserved for later work. They are documented as placeholders only: there is no implementation and no dependency for either one in the core.

Future add-on

heatgate

Power throttling from measured temperature and grid readings. A future heatgate add-on would hook before_step to pause, delay, or skip work when those readings are high. It would be optional power management, not part of the processor, storage, or I/O of the agent itself.

Future add-on

lex-loop

An 8-step robot loop (READ → RESTART) used as a clock. A future lex-loop add-on would hook plan execution so each tick advances one phase of that loop. It would be an optional clock, not part of the core planner.

Get started

Clone the repository, install the package, and run a goal through the mock connector.

Get started View on GitHub

pip install -e ".[dev]"
soa run "echo hello from system on an agent"

Planner

The processor. It turns a goal into a plan and runs it step by step, with no language model required.

Memory and skills

Storage for the run, long-term facts, and a library of reusable named procedures.

Connectors

Pluggable input and output, including a local file connector and an echo (mock) connector.

Bus / Router

The interconnect that routes messages between the other parts and fires add-on hooks.