A pattern for getting work done by agents
A blueprint records the shape of the work: which agents exist, what each one is handed, what each one is kept away from, and where a person acts. It is a folder of plain text files, neither a prompt nor a model, and you run it with your own tools.
open the folder
A blueprint is the folder
One graph, one folder, three kinds of file. Every file shown on these pages is the real one from the archive, so what you copy from here is a file that loads.
- topology.dot
- The graph, as a person wrote it: which node hands what to which, and which edges were deliberately left out. This is the file the rest of the folder is pinned to.
- cards/*.yaml
- One versioned card per node, pinned by the topology at an exact version. What runs there, which model it uses, what it may reach and what must never reach it.
- README.md
- This blueprint, explained for a person: the shape in a sentence, a checksum (the digest) you can verify the files against, and how to run it with your own harness.
A blueprint, a card for every node, one vocabulary
Each part is a plain text file, and each is checked against the others.
The topology
A directed graph in a subset of Graphviz’s DOT language, saying which node hands what to which. An edge nobody drew is a connection somebody decided against. The dashed one above is an edge the validator refuses, because the card on the receiving node forbids what it would carry.
topology.dot
The cards
Each card names the node’s job, the brief it is handed, the model it runs on, the tools it may reach, and the data types that must never reach it. A card is pinned by version, so the same card can serve in more than one blueprint.
cards/id@version.yaml · ontology/extensions.yaml
- phase
- 5
- node-type
- 13
- data-type
- 16
- risk-marker
- 13
The vocabulary
A controlled list of terms the topology and the cards are both written against, so that two authors naming the same thing write the same word and the validator can tell when they have not.
ontology/extensions.yaml
What a blueprint needs before it runs
A blueprint is a specification, and a specification does not run by itself. Three other things surround every run, and DarkPrint supplies only the first of the four.
Blueprint
specificationHarness
runtimeRuns the loop and owns the live state.
Rubric
criteriaEval
aggregateblueprint
the specificationThe graph and the cards it pins define which agents exist, what each agent is handed, and what each agent is kept away from. It is text, versioned and checkable, and the only one of the four you download from here.
harness
the agent's runtimeThis runs the loop. It dispatches the tools, manages the context, keeps the session state and holds the safety rules. An agent is a model with tools, memory and state acting in that loop. You bring your own harness.
rubric
the scoring schemaThese are the criteria a result is graded against. Several apply at once, each with a scale, so “good” has a gradable answer: deterministic checks, a model acting as judge, or both. The criteria are written down before the run, so two runs can be compared. They are kept away from the agents doing the work: a system that can read its own grading criteria learns to satisfy the criteria instead of doing the work.
eval
the measurementRunning the blueprint through the harness and grading what comes back. An eval asks whether the behaviour is acceptable over many inputs rather than checking one exact output, and reports the result across all of them. It happens offline, before anything ships.
Where to go from here
Two reference pages follow: the topology file first, then the node card, which also covers the vocabulary.