Transparency Over Magic

Developers evaluating an agent framework usually say they want control. Frameworks hear this and respond by adding configuration.

That is the wrong reading. Nobody wants more knobs. What people mean by control is narrower and more specific:

When this system does something surprising, can I find out why, and can I change it?

Those are two different properties — inspectability and replaceability — and neither is delivered by removing opinions.

"Unopinionated" is not the goal

A framework with no opinions is a library with extra steps. Its value is its opinions: the decisions you no longer have to make, the mistakes you can no longer make by accident. A framework that decides nothing has given you nothing.

So SwarmPlane does not claim to be unopinionated, and Why SwarmPlane states its three opinions without hedging. The claim is different:

Every decision the system makes is visible, inspectable, and replaceable.

Visible: you can see that a decision was made. Inspectable: you can see what it was and what caused it. Replaceable: you can substitute your own without forking.

Magic fails the first test. Not because it is complicated — real systems are complicated — but because it does not leave a trace of having happened. An agent that silently retried three times, or quietly truncated your context, or picked a different model because the first was slow, has made decisions you cannot see. When behaviour surprises you, there is nothing to read.

Structure you can look at

There is a reason Airflow displaced cron for pipelines, and it was not scheduling — cron schedules fine. Airflow won because it made the dependency graph a first-class object. You could render it, click a failed task, and see what was downstream. The graph stopped being a property of the code and became a thing on a screen.

That changed how people operated pipelines, independent of what the pipelines did.

The same move applies here, with one difference: Airflow's graph is declared and static, so it shows you the plan. SwarmPlane's graph is accreted from outcomes, so it shows you the run — including the branch that failed, what that failure taught, and which attempt produced the answer.

Records, not side effects

A graph that exists as a data structure is a different kind of object from one that is a side effect of decorated Python.

If the graph is a persisted record, you can print it, diff two runs of the same task, commit an interesting one to a repository as a regression fixture, hand it to someone who does not have your codebase, or query "which runs called this tool after a failure." None of that requires the framework to provide a feature, because the graph is just data.

If the graph exists only as control flow implied by your code, every one of those needs tooling somebody has to build, and each tool sees a slightly different view.

This is why the graph is persisted from the first node rather than reconstructed for display, and why the visualizer is a reader of the same structure the scheduler writes rather than a parallel representation. Two representations means one of them is wrong and you find out during an incident.

Where transparency has to be earned

An honest limit: none of this makes a language model transparent. Why the expansion policy proposed one step rather than another is a question about the model, and the graph does not answer it. What the graph gives you is the complete record of what was proposed, what ran, what it returned, and what followed — the decisions and their consequences, not their interior reasoning.

That is a real boundary and worth naming, because the failure mode for a project with "transparency" in its philosophy is to imply more than it delivers.

The claim is: nothing the framework does is hidden from you. Not: the model is explainable.

The falsification

The condition under which this page is wrong is stated in Prior Art: if frontier policy cannot be made comprehensible — if nobody can predict or control what the graph will do next — then "transparent" is marketing and this is a ReAct loop that draws pictures.

Producing a record of decisions is not the same as making them intelligible. The first is solved by the data structure. The second has to be earned in Execution Semantics, and it is not solved yet.