Ask an AI coding assistant to “have three specialists work in parallel, compare their patches, and stop the losing attempts.” The assistant may still make one model call, describe three imaginary specialists, and return the first patch it wrote. That mismatch comes from the runtime topology: the prompt states an intention, while the runtime decides which workers start, what state they can see, how their outputs are checked, and whether losing branches can stop.
An agent runtime is the software that starts model and tool work, manages the loop, records events, and decides when a run ends. A worker is one bounded execution of an agent inside that runtime. The runtime’s topology is the shape of the work: serial steps, parallel branches, retries, handoffs, review stages, or a supervisor loop. A trace is the record of the run, including each worker, tool call, artifact, decision, cost, and failure. An agent profile is the versioned bundle of model, prompt, tools, permissions, skills, and runtime settings used for a run. An evaluation is a repeatable test of an agent on a defined case. A baseline is the version already trusted for comparison, and a candidate is a proposed replacement. A validator is a check that turns an artifact into pass or fail evidence. A judge is a scorer for qualities that a deterministic validator cannot fully capture. A winner rule is the rule that chooses among valid branch results. A promotion gate is a fixed rule that decides whether a candidate may replace the baseline. A sandbox is an isolated execution boundary that limits access to files, networks, credentials, or processes. A Blueprint is Tangle’s reusable template for software that runs as a service. A Blueprint Runner is Tangle’s runtime for dispatching a Blueprint job to the handler registered for that job. A trusted execution environment, or TEE, is a hardware-backed area intended to isolate code and secrets from the host.
The rule is simple: a prompt can request a behavior, but the runtime must own any behavior that needs to be enforced, measured, cancelled, or repeated.
A request is not an action
For a person, “work in parallel” implies several details:
- Independent attempts.
- Separate state or files.
- A limit on concurrent work.
- A way to collect results.
- A rule for comparing them.
- A cancellation path.
- A record of what each attempt did.
For software, each detail is a capability.
| Desired behavior | Runtime capability |
|---|---|
| Start several attempts | Worker creation and bounded concurrency |
| Prevent conflicts | Isolated state, files, or namespaces |
| Limit spending | A shared token, call, time, and dollar budget |
| Compare results | A validator or judge with a visible contract |
| Choose a winner | A winner rule the runtime enforces |
| Stop losing work | Cancellation that reaches child work |
| Learn from the run | A trace that keeps branches and outcomes |
If the runtime has none of these controls, a prompt can only ask the model to imitate them. The result may read like a team report while one worker did all the work. That is a control-flow failure, not a wording failure.
Topology is an execution shape
The word topology is useful here only as shorthand for the shape of execution. It answers four questions:
- Which worker or tool runs?
- In what order or at the same time?
- What state does each branch see?
- Which condition ends or escalates the run?
A serial refinement run looks like:
task → worker → validator → retry or finishA parallel run looks like:
task → worker A ┐
worker B ├→ validator → winner or retry
worker C ┘A handoff looks different:
triage worker → specialist worker → final reviewerThe model can be identical in all three cases. The execution shape still changes the available evidence, cost, latency, and failure behavior.
What belongs in the runtime
Keep policy text and execution authority separate. The model can suggest a next step, but the runtime should enforce the boundaries that matter:
| Runtime responsibility | Why it cannot be left to prose |
|---|---|
| Worker count | The model cannot create an operating-system process through a sentence |
| Concurrency limit | A model cannot reserve shared capacity across branches |
| State isolation | A role label does not create separate files or memory |
| Budget accounting | “Be efficient” does not stop a runaway loop |
| Validation | A model can claim it passed a check without running it |
| Cancellation | A model can say “stop” while child calls continue |
| Replay | A summary cannot recover an omitted tool call |
| Promotion | The candidate should not decide whether it replaces itself |
The boundary also improves experiments. When the driver, worker profile, validator, and budget are explicit, a team can compare serial refinement with fanout while holding the model and task set fixed.
A public runtime example
Tangle’s public agent-runtime repository exposes a TypeScript kernel for bounded agent rounds. Its public quickstart shows a driver that reads the previous worker output, composes the next prompt, stops when a validator passes or a shot limit is reached, and returns a recorded decision.
The shape is:
import { runAgentRounds } from '@tangle-network/agent-runtime/kernel'
const result = await runAgentRounds({
task: { prompt: 'Write a release note that mentions rollback.' },
driver: {
name: 'refine',
plan: async (task, history) => {
const last = history[history.length - 1]
if (!last) return [task]
if (last.verdict?.valid || history.length >= 3) return []
return [{ prompt: 'Rewrite the note to mention the rollback path.' }]
},
decide: (history) =>
history.some((shot) => shot.verdict?.valid)
? 'pick-winner'
: history.length < 3
? 'refine'
: 'fail',
},
agentRun: { profile: { name: 'note-writer' }, taskToPrompt: (task) => task.prompt },
output,
validator,
ctx: { sandboxClient: worker },
maxIterations: 3,
})The example is adapted from the repository’s public offline quickstart. The output parser, validator, and worker are adapters supplied by the application. The important property is that refinement is represented as executable driver state rather than as a promise in the prompt.
The public repository also documents supervision and improvement calls. Use those interfaces as the source of truth for current names and options because runtime APIs change faster than an article.
Do not confuse agent routing with Blueprint routing
Tangle uses the word Router in more than one nearby context. A Router in the Blueprint Runner is a traffic director that maps a job identifier to the handler for that job and validates its inputs. It is not automatically the planner that decides which AI worker should act next.
A Blueprint is a reusable template for software that can run as a service. A Service is a live instance of that template. An operator is the party that runs the Service and handles its jobs. If the agent is wrapped inside a Blueprint, the Blueprint Runner Router can deliver a paid or on-chain job to the agent service, while the agent runtime can still have its own internal worker topology.
That distinction matters for debugging. An accepted job at the outer Router does not prove that an internal worker started. An internal worker finishing does not prove that the outer job result was returned. The trace should connect those boundaries with a shared execution identifier.
If the service accepts x402, x402 is an optional off-chain HTTP payment path. The gateway verifies and settles payment, then injects a job call into the runner. A paid and enqueued request is not a completed job and is not proof of answer quality.
If the service runs inside a trusted execution environment, an attestation is a signed report about the code and hardware state loaded by that environment. Attestation can support the claim that the expected code ran in the expected boundary. It does not prove that the agent chose the right tool or that the output passed an evaluation.
Trace fields that prove the execution shape
A final answer cannot show whether the runtime executed the requested shape. For a claimed three-worker run, the trace should include:
| Trace field | Question it answers |
|---|---|
| Parent and child IDs | Which work belonged to the run? |
| Agent profile | Which model, prompt, tools, and permissions did each worker use? |
| Input context | Did branches see independent or shared state? |
| Start and finish times | Did the timestamps show concurrency? |
| Tool calls and outputs | What evidence did each branch collect? |
| Validator result | Which checks passed or failed? |
| Winner rule decision | Why did one branch win? |
| Cancellation state | Did losing work stop or continue? |
| Cost and tokens | What did the topology purchase? |
Without these fields, a successful output does not prove that parallelism helped. It may prove only that one branch happened to solve the task.
Artifact lineage is the chain linking a final artifact to the branches and evidence that produced it. The trace systems article explains why raw provider activity, tool spans, and artifact lineage matter. The harness evolution article covers what to do when the current runtime cannot capture or enforce the required boundary.
Equal-budget topology comparisons
An eight-worker topology can beat a one-worker topology because it spent eight times as much. That can be a rational product decision. It is not evidence that coordination itself improved the result.
For each comparison, record:
- Worker count and maximum concurrency.
- Model calls and tool calls.
- Input and output tokens.
- Wall-clock time.
- Failed, timed-out, and cancelled branches.
- Human approvals.
- Total dollars and sandbox time.
- Final quality and protected failure classes.
Then compare the right question:
| Question | Required evidence |
|---|---|
| Is the topology better at the same budget? | Paired tasks with equal limits |
| Is it cheaper at the same quality? | Cost and quality together |
| Is it faster at the same quality? | Latency distribution and quality together |
| Is it safer? | Permission, failure, approval, and trace records |
The evaluation gates article gives the release rule. The multi-agent coordination article explains why independent-looking workers can still share one blind spot.
Failure behavior must be explicit
Every topology needs policies for the unhappy path.
If a branch times out, the runtime can retry, ignore it, stop the run, or ask for review. If a validator fails, the runtime can refine the same branch, open a new branch, or return a failure with evidence. If the winner rule receives no valid candidate, the result should be “no candidate passed,” not the first malformed output. If cancellation races with a tool call, the trace should record whether the side effect completed.
Do not let the model choose among those policies in an unstructured paragraph. The model can propose a retry reason. The runtime owns the retry count, budget, side-effect policy, and final decision.
Cancellation also has a cost boundary. Stopping a parent call does not necessarily stop a provider request, remote job, browser action, or child process. The runtime needs a cancellation contract for every adapter and must report adapters that cannot stop immediately.
Add a branch only when it adds a capability
The simplest topology is one worker with one validator. Use refinement when a failed result contains enough information to improve the next attempt. Use fanout when independent attempts can explore useful alternatives and a reliable winner rule or validator can choose among them. Use a handoff when a new specialist should own the next step and the state transfer is explicit. Use a supervisor when work can be decomposed and the coordinator has authority over assignments, budgets, and merge rules.
Do not add a branch because the prompt sounds more sophisticated with five roles. Add one when it creates a measurable capability:
- Different evidence.
- Different tools.
- Different model or skill.
- A real isolated workspace.
- An independent check.
- A faster path through independent work.
If five workers share the same context, model, evaluator, and missing source, five outputs may be five versions of the same error.
Separate the service job from the agent workflow
The public agent-runtime repository places execution, supervision, and improvement in code that can be measured. The public agent-eval repository provides the comparison layer for candidate behavior. The Blueprint Runner documentation describes the outer service lifecycle, job producers, Router, handlers, and consumers.
These are related but not interchangeable. The Blueprint Runner routes a service job. The agent runtime executes the internal workflow. The evaluation system decides whether a new profile or topology earned promotion. The operator runs the service and records operational evidence; application checks still determine whether the agent’s answer meets the product contract.
The profile must identify the full execution condition. If a candidate changes the Router, worker model, prompt, tool list, or sandbox mode, the evaluation should say so. Otherwise a topology claim can hide a profile change.
The practical decision
Keep coordination in the prompt when it is advice the model may follow. Move it into the runtime when it must be enforced, measured, cancelled, or repeated.
Use one worker when the task is small, the cost of extra attempts is not justified, or the evaluator is too weak to select among branches. Use refinement when the failure signal points to a repair. Use fanout when independent attempts create useful diversity and the winner rule is testable. Use a supervisor when the decomposition, state transfer, and merge contract are explicit.
The minimum proof is not a polished final answer. It is a trace that shows the requested workers existed, saw the intended state, ran the intended tools, received the intended checks, and consumed the reported budget.
If a prompt says “parallel” and the trace contains one worker, the system did not parallelize. If the system cannot show why a branch won, it did not yet select a winner. If the service accepted payment but the job has not completed, it did not yet deliver a result.
Can a better prompt create true parallelism?
No. It can request parallel work or imitate a team report, but true parallelism requires the runtime to create, track, isolate, and join multiple executions.
What is agent runtime topology?
It is the executable shape of an agent workflow, including which workers and tools run, their order or concurrency, their state visibility, their budgets, and their stop rules.
Does more workers always improve quality?
No. More workers can increase cost, latency, correlated errors, winner-rule mistakes, and cleanup work. Compare against equal-budget baselines and inspect branch-level traces.
What should a runtime record?
Record the agent profile, parent and child execution IDs, context boundaries, tool calls, outputs, validators, winner-rule decisions, timing, cost, failures, and cancellation state.
Where does a Blueprint fit?
A Blueprint defines a deployable service and its jobs. Its Router delivers a job to the service handler. The internal agent runtime can then choose a separate topology for the work.