BlogAgent Runtime Infrastructurepart 1 of 2
AI Agent Runtime Architecture: When to Remove a Path
Delete a second execution path only after the shared route preserves its settings, controls, errors, and trace records.
Two programs can start the same coding agent and still give its caller different behavior. One path may stream progress, preserve tool calls, and accept an interrupt. The other may return only a final response.
Deleting the larger path can remove duplicate code while also removing the only place a user could see what happened. Line count is therefore a useful result of cleanup, but a poor reason to begin it.
The question for this change was stricter: could the shared path deliver the settings, controls, errors, and records that made the special path necessary? It could for the promised profile behavior and not for several backend-specific controls, and those losses were named.
A second execution path is safe to delete only after the shared path can express the user-visible behavior that matters.
Run the shared route on a Tangle sandbox
The route here is the agent-runtime front door on a Tangle sandbox.
providerAsSandboxClient wraps a provider, and the harness is a profile field, so claude-code, codex, opencode and pi all go through the same client.create and box.streamPrompt calls.
The stream carries two signals: a result event with the final text, and a done event with totalCostUsd.
import { createTangleProvider } from "@tangle-network/agent-provider-tangle";
import { providerAsSandboxClient } from "@tangle-network/agent-runtime/kernel";
import { Sandbox } from "@tangle-network/sandbox";
// Any AgentEnvironmentProvider fits here; this one runs on Tangle.
const provider = createTangleProvider({
client: new Sandbox({
apiKey: process.env.TANGLE_API_KEY!,
baseUrl: "https://sandbox.tangle.tools",
}),
});
// The harness is a profile field: "claude-code", "codex", "opencode", "pi".
const client = providerAsSandboxClient(provider, {
defaults: { profile: { name: "repo-reader", harness: "claude-code" } },
});
const box = await client.create({
git: { url: "https://github.com/tangle-network/sandbox-demo" },
});
try {
const task = "Read this repository. In two sentences, say what it does.";
for await (const event of box.streamPrompt(task)) {
if (event.type === "result") console.log(event.data.finalText);
if (event.type === "done") console.log(`$${Number(event.data.totalCostUsd).toFixed(4)}`);
}
} finally {
await box.delete();
}The output shows the profile reaching the coding program through the shared route, and the route reporting what the run cost. It does not show that the answer is correct.
Start with what the caller can observe
An agent is a program that uses a language model and tools to complete a task. An agent runtime is the software that starts, controls, and records that program. A worker is one running copy of the agent. An execution path is the route that starts and supervises that worker.
An agent profile is a saved set of instructions, model choices, tools, permissions, and resources. A trace is the record of a run’s inputs, actions, tool events, outputs, and failures.
The special path in this change started Pi directly. Pi is a coding-agent program, not a model. The shared path used a bridge. A bridge is an adapter that translates the runtime’s worker requests into a remote service request and translates the service’s events back.
A parent is the program that starts a worker and decides whether to wait, steer, stop, or restart it. Before removing a path, compare the boundary that a caller can see. For a coding task, that boundary includes more than the final text.
| Capability | Shared path before the change | Why a caller needed it |
|---|---|---|
| Live progress | No current activity was available | A parent program could not tell whether to wait or stop |
| Tool-call records | Tool requests were discarded before the settled trace | A reviewer could not see what the worker asked to run |
| Mid-run steering | A non-interactive request accepted no new input | A person had to stop and restart to change direction |
| Provider errors | One failure could look like an empty successful response | A caller could mistake missing work for a valid result |
Without these signals, the parent has to infer state from silence. That is where an apparently harmless simplification becomes a behavior change.
Compare the edges, not the internals
Two execution paths rarely have identical implementations, so parity belongs at the boundary visible to the caller, not in a line-by-line comparison of internal functions.
For a coding task, write the comparison as a small contract before changing the route:
| Boundary | Old path must show | Shared path must show |
|---|---|---|
| Inputs | The same effective profile and task | The same effective profile and task |
| Activity | Whether a turn or tool request is in progress | Whether a turn or tool request is in progress |
| Control | What steering and interruption mean | What steering and interruption mean |
| Failure | The provider or process error | The provider or process error, without converting it to success |
| Artifacts | The requested tool, files, and final record | The requested tool, files, and final record |
| Completion | The terminal state and its reason | The terminal state and its reason |
The comparison should include a task that deliberately visits each boundary. For example, start with a profile containing a system prompt, a resource file, and one tool. Ask the worker to read the resource, request the tool, and stop after the first response. Then repeat with a provider failure and a cancellation. The useful output is not two identical transcripts. It is a result showing which caller-visible facts survived the route change.
This method catches a common false positive. Both paths may return the same final sentence for a task that never uses a tool. That says little about tool delivery. Both paths may return a failure, but one may preserve the provider error while the other returns an empty result. The final status matches while the recovery experience differs.
The parity record should also name intentional differences. If the old path supported immediate mid-turn input and the shared path supports only queued steering, mark that as a changed control contract. The product can then decide whether queued steering is acceptable. It cannot make that decision if the comparison reports only “both completed.”
Add the shared behavior before deleting code
The public bridge implementation now carries the shared observability behavior. It reads live progress from a local event mirror and records the OpenAI-shaped tool-call events arriving from the remote stream. It does not manufacture tool completion when the stream carries only the model’s request.
The resulting shape is easier to reason about:
profile
-> delivery contract
-> shared bridge
-> coding worker
-> progress mirror
-> requested-tool trace
-> remote terminal status
The diagram describes the public source change, not a promise that every provider sends the same events. The source can preserve a request when the remote service exposes a request. It cannot infer a tool result that never crossed the bridge.
The shared path also received the profile behavior that the special path had carried separately. The public runtime changelog names four important settings:
| Profile setting | What the shared path does for the coding worker |
|---|---|
| Reasoning effort | Translates the saved level into the coding program’s thinking option |
| Tools | Applies the saved tool exclusions |
| Resources | Places saved files and instructions in the run directory |
| System prompt | Passes the saved instructions to the coding program |
The same saved profile no longer takes one interpretation on a special route and another on the shared route.
The deletion changed the capability boundary
The cleanup removed a special executor, its tool-connection code, and the tests that only exercised that path.
The capability comparison and the named losses answer the useful question: which caller-visible behaviors survived, and which no longer have a channel?
After the change, a Pi worker uses the shared bridge like the other supported workers. Pi becomes a model or backend choice inside one execution route rather than a separate runtime family that needs a second implementation of every new feature.
It also concentrates risk. If the bridge later loses a capability, every worker using that bridge sees the loss. Shared code reduces divergence only when its contract is explicit and its missing signals are visible.
Publish the behavior that did not survive
The deletion did not preserve every Pi-specific control. A reliable architecture description includes the losses beside the gains. A cloud adapter shows the same contract from the other side. The E2B adapter runs the same profile as Tangle, with the model on the Tangle Router:
import { createE2BProvider } from "@tangle-network/agent-provider-e2b";
import { providerAsSandboxClient } from "@tangle-network/agent-runtime/kernel";
// E2B hosts the sandbox; the model still goes through the Tangle Router on your key.
const provider = createE2BProvider({ router: { key: process.env.TANGLE_API_KEY! } });
// The same profile as on Tangle: "claude-code", "codex", "opencode" or "pi".
const client = providerAsSandboxClient(provider, {
defaults: { profile: { name: "repo-reader", harness: "claude-code" } },
});
const box = await client.create({
git: { url: "https://github.com/tangle-network/sandbox-demo" },
});
try {
const task = "Read this repository. In two sentences, say what it does.";
for await (const event of box.streamPrompt(task)) {
if (event.type === "result") console.log(event.data.finalText);
}
} finally {
await box.delete();
}What E2B cannot give is refused by name before any E2B call: a custom image, resource sizes, egress modes, snapshots and checkpoints. The Pi-specific losses in this change follow the same pattern:
| Removed capability | Behavior after the deletion |
|---|---|
| Immediate mid-turn steering | New input arrives after the current non-interactive request, and an interrupt stops the process tree |
| Per-worker arguments and environment | The shared connection has no per-worker channel, so configure these on the bridge service |
| Per-worker program override | The shared connection has no field for it |
| Worker trace propagation through an environment variable | The old row is removed because the shared connection exposes no worker environment channel |
| Pi-specific tool-connection file | Tool registration belongs to the bridge service, so the runtime no longer writes a Pi-specific file |
They are the conditions under which a team might still need a specialized route. If a product depends on per-worker environment variables, deleting the special path is not a neutral cleanup until the product has another way to supply them.
The right architecture decision can therefore be conditional:
Keep a special path when it expresses a required capability.
Remove it when the shared path expresses that capability and records its limits.
A small parity check is better than a large assumption
The public runtime package is installable with:
pnpm add @tangle-network/agent-runtime
The current public README shows the runtime passing a profile, task, budget, model route, and backend into one supervision call. The important design choice is that the execution location is data supplied to one shared flow rather than a hidden branch that silently changes the profile.
A parity test for a cleanup like this can be concrete:
type ObservableRun = {
profile: string[]
progressKinds: string[]
toolRequests: string[]
providerError?: string
finalStatus: 'completed' | 'failed' | 'cancelled'
}
function comparePaths(before: ObservableRun, after: ObservableRun) {
return {
profile: before.profile.every((setting) => after.profile.includes(setting)),
progress: before.progressKinds.every((kind) => after.progressKinds.includes(kind)),
tools: before.toolRequests.every((tool) => after.toolRequests.includes(tool)),
error: before.providerError === after.providerError,
finalStatus: before.finalStatus === after.finalStatus,
}
}
This is illustrative test code, not an exported API. It makes the acceptance question visible. The real test should use a fixed task, a known tool request, a deliberate provider failure, an interrupt, and the same profile on both paths.
Do not compare only successful final answers. A successful answer can hide a missing tool. A failed answer can reveal whether the path preserves the error that explains the failure.
What the cleanup proves, and what it does not
The deletion proves that the special source path is no longer needed for the selected set of profile and run behaviors at the pinned source revision. It also proves that several Pi-specific controls no longer have a channel through the shared bridge.
It does not prove that every model provider behaves the same. It does not prove that a remote service will remain healthy. It does not prove that a tool request completed. It does not prove that a worker’s final code is correct.
| Evidence | Narrow claim |
|---|---|
| Public deletion diff | Which source path and tests were removed |
| Capability table | Which caller-visible behaviors were compared |
| Shared observability change | Which live and trace signals the bridge now exposes |
| Profile materialization source | Which settings the selected path declares it can carry |
| Task-specific evaluation | Whether a particular coding task passed its acceptance checks |
An evaluation is a structured check of a result against a stated criterion. For a coding worker, that might be a test command, a type check, a review rule, or a human decision. It is separate from architecture parity because two routes can produce the same trace shape and still produce different code.
The package boundary still matters
Source and release are different evidence. The public repository records what the source contains. The package version is what an application can install without building from source.
Check the published package and its release notes before assuming that the current source behavior is in the version your application runs.
A team can read the deletion, install an older package, and conclude that the shared path still drops a setting. That conclusion may be correct for the installed package and wrong for the current source. Record the package version with the run.
Migration is part of the deletion
Removing a path changes more than new runs. Existing sessions may still point at the old worker kind. Stored traces may contain event names that the shared path does not emit. Operational dashboards may count the old executor separately. Support tooling may offer a retry button that assumes the old path can accept per-worker environment values.
Treat those consumers as part of the migration surface. Before release, find the records and controls that mention the old path and decide what each one should do.
| Existing item | Safe migration question |
|---|---|
| In-flight session | Can it finish on the old route, or must the product stop and explain the change? |
| Stored trace | Can readers display both old and shared event shapes? |
| Retry action | Will retrying preserve the same profile and choose the shared route explicitly? |
| Dashboard label | Does it describe a worker capability rather than a deleted implementation name? |
| Rollback package | Can a release be reverted without starting a second worker for the same run? |
The last question is about duplicate side effects. Rolling back code is not the same as replaying a task. If the worker already changed a repository or called an external service, a new path must inspect the existing run before trying again. Use a stable run identifier and preserve the old record even when the new runtime cannot resume it.
This is also where the named capability losses become operationally useful. If per-worker environment overrides disappeared, the migration should reject requests that still depend on them. If steering moved from immediate input to queued input, the user interface should not promise an instant turn change. An honest incompatibility at release time is safer than a retry that appears to work while dropping the control.
A safer rule for deleting execution paths
First, list the user-visible capabilities of the old and new routes. Second, add missing shared behavior before touching the old route. Third, run the same task through both paths with a profile that exercises tools, resources, progress, cancellation, and failure. Fourth, publish the differences that remain. Finally, remove the old path and keep a regression test for the shared contract.
Why remove a backend-specific execution path?
Remove it when a shared route can carry the profile settings and run signals that made the special path necessary. The source becomes easier to change because a new feature no longer needs two implementations.
Did the deletion remove behavior?
Yes. Immediate mid-turn steering, per-worker environment overrides, a per-worker program override, and a Pi-specific tool-connection file no longer travel through the shared route.
Does deleting source code prove the architecture improved?
No. Source removal measures cleanup. The capability comparison, shared observability change, and named losses provide the evidence for the architecture decision.
Is the shared path the same as a model router?
No. A router chooses or forwards model requests. The shared path is the runtime route that starts the worker and translates its events.
Does a passing evaluation prove the two paths are equivalent?
No. An evaluation covers the checks it defines. Use a task that exercises the capabilities your product depends on, including failures and cancellation.
Next in Agent Runtime Infrastructure: Why AI Agent Token Budgets Need a Measured Runtime Floor