A tax preparer gives an assistant twelve documents and asks for a review packet. The assistant has to copy the files, identify the document types, ask a model about uncertain pages, calculate totals, remember which file produced which result, and show a human what happened before anything is filed. The final paragraph is the smallest part of the job.
An AI agent runtime environment is the software and machine around a model that makes this multi-step work possible. It supplies tools and state, enforces permissions, manages resources, routes model requests, records actions, and decides what survives after the run. The model proposes decisions. The runtime determines which decisions can become side effects.
The tax example is illustrative and is not tax advice or a filing service. Coding, browser automation, paid APIs, and model evaluation each need scoped tools, state, permissions, and retained evidence.
The runtime starts where the prompt ends
A model can answer “What does this error mean?” from text in a request. It cannot read twelve files, run a deterministic calculation, retry a failed parser, and prove which input produced the result unless another system gives it those capabilities.
The workflow needs at least these steps:
- Accept the request and establish the allowed authority.
- Copy only the supplied documents into a bounded workspace.
- Classify documents and keep uncertainty attached to each classification.
- Convert accepted fields into structured data.
- Run calculations outside the model’s prose generation.
- Save intermediate artifacts and failures under one run identity.
- Return a review packet with a human approval point.
For this workflow, the runtime needs to make those steps observable. It should give each task an identifier, record the actor and action, pass approved outputs forward, and preserve failed attempts instead of replacing them with an empty result.
A small dictionary for the system
Agent infrastructure uses ordinary words for different control layers. Define them before combining them.
| Term | Meaning in this workflow | Boundary to preserve |
|---|---|---|
| Runtime | Software and compute that execute model-directed actions | It owns lifecycle, tools, state, permissions, and records |
| Agent profile | A versioned bundle of model, tools, instructions, permissions, resource limits, and budget | Changing it changes what the run can do and how its result should be compared |
| Router | A service that accepts a stable model-request format and chooses an available provider or model route | A route record identifies which model path answered; it does not certify answer quality |
| Sandbox | An isolated workspace for files, processes, packages, and artifacts | Isolation narrows side effects; it does not decide whether a patch is correct |
| Trace | An ordered record of inputs, model calls, tool actions, outputs, errors, and artifacts | A trace makes a run inspectable without pretending every conclusion is true |
| Evaluation | A repeatable set of cases with explicit checks and a comparison rule | An eval measures a defined behavior; it does not turn all model output into ground truth |
An agent profile might allow a document classifier to read copied PDFs, call one model route, write a packet, and spend at most a fixed amount. It should not inherit the user’s home directory, filing credentials, or email permissions merely because the model could describe those actions.
Per-document runtime record
The record should point to the artifact and its result, alongside the conversation.
| Stage | Input | Action | Output to retain |
|---|---|---|---|
| Intake | User-supplied file IDs | Copy into a scoped workspace | Input manifest and file hashes |
| Classification | One copied document | Ask the model for a typed label and confidence explanation | Raw response, normalized fields, and model route |
| Validation | Structured fields | Check required fields and allowed values | Validation errors and accepted fields |
| Calculation | Accepted numeric fields | Run deterministic code | Formula version, inputs, output, and exit status |
| Packet | Classifications and totals | Render a review document | Packet path, artifact hash, and unresolved questions |
| Cleanup | Workspace and session IDs | Save required artifacts and delete temporary resources | Cleanup status and retained record |
The calculation row is deliberately separate from the model row. A model can extract a number from a document, but a normal program should add, compare, and round it when the rule is deterministic. The reviewer then sees which values came from interpretation and which came from a calculation.
A vendor-neutral runtime sketch
The following TypeScript is a teaching example, not a Tangle API.
It makes the important boundaries visible without hiding them behind a generic runAgent function.
type ReviewTask = {
id: string
inputFiles: string[]
outputDirectory: string
allowedActions: Array<
'read-inputs' | 'classify' | 'validate' | 'calculate' | 'write-packet'
>
}
type RunEvent = {
at: string
action: string
status: 'started' | 'completed' | 'failed' | 'blocked'
detail?: string
}
type ReviewRun = {
task: ReviewTask
events: RunEvent[]
artifacts: string[]
}
async function prepareReviewPacket(task: ReviewTask): Promise<ReviewRun> {
const run: ReviewRun = { task, events: [], artifacts: [] }
requireAction(task, 'read-inputs')
record(run, 'read-inputs', 'started')
const documents = await readOnlyInputCopies(task.inputFiles)
record(run, 'read-inputs', 'completed', `${documents.length} files copied`)
requireAction(task, 'classify')
record(run, 'classify', 'started')
const classifications = await classifyDocuments(documents)
record(run, 'classify', 'completed')
requireAction(task, 'validate')
const fields = validateFields(classifications)
record(run, 'validate', 'completed')
requireAction(task, 'calculate')
const totals = calculateFromStructuredFields(fields)
record(run, 'calculate', 'completed')
requireAction(task, 'write-packet')
const packet = await writeReviewPacket(task.outputDirectory, fields, totals)
run.artifacts.push(packet)
record(run, 'write-packet', 'completed', packet)
return run
}
function requireAction(task: ReviewTask, action: ReviewTask['allowedActions'][number]) {
if (!task.allowedActions.includes(action)) {
throw new Error(`blocked action: ${action}`)
}
}
function record(run: ReviewRun, action: string, status: RunEvent['status'], detail?: string) {
run.events.push({ at: new Date().toISOString(), action, status, detail })
}The application functions in the example are placeholders for parser, model, validation, calculation, and rendering code. The action list omits submission in this example, but the TypeScript type is only a compile-time check. The process that owns the filesystem and network still has to enforce the same rule outside the model context.
Treat the profile as a contract
An agent profile is easy to mistake for a long system prompt. It is more useful when it is a versioned input to the runtime and the evaluator. The runtime reads it to decide which tools and resources exist. The evaluator records it to explain why two runs are comparable or why they are not.
| Profile field | Example for the document task | Failure when it is missing |
|---|---|---|
| Model route | router/document-review | A later run may use a different model without showing the change |
| Tool set | Read files, classify, validate, calculate, write packet | The model may appear to have permission that the job never intended |
| Workspace scope | One temporary directory containing copied inputs | A trace cannot show which files were reachable |
| Network policy | Package registry and model endpoint only | A parser or model call can silently use an unreviewed destination |
| Budget | Sample budget: 12 model turns and 10 minutes | A stuck recovery loop can become an unbounded cost |
| Stop rule | Write a packet and wait for human review | The agent may treat a plausible draft as a filed result |
Suppose the classifier labels invoice-17.pdf as an invoice with 0.61 confidence.
The trace should retain the input ID, copied-file hash, profile ID, model route, raw response, normalized label, and the rule that sent the item to review.
The calculation stage should then record the fields it accepted and the formula version that produced the total.
That chain lets a reviewer ask whether the error came from the document, the model, the parser, the calculation, or the policy.
If the same document is retried with a different model route or a larger budget, give the retry a new profile ID. The retry may be a good recovery, but it is not the same experiment as the first run. Keeping that distinction prevents a later score from hiding a change in authority or cost.
How Tangle surfaces fit the runtime
Tangle’s products map to different responsibilities. Each surface should be added because the task needs it, not because “agent stack” sounds incomplete without it.
| Runtime need | Tangle surface | Concrete contribution | What it does not prove |
|---|---|---|---|
| Model access | Tangle Router and @tangle-network/tcloud | An OpenAI-compatible request surface, model discovery, route and usage information | That the selected model answered correctly |
| Files and processes | Tangle Sandbox and @tangle-network/sandbox | Isolated workspaces, commands, files, sessions, snapshots, and resource limits | That a command was the right command or that its output is safe |
| User-visible web work | Tangle Browser Agent | Chromium control with DOM and screenshot evidence | That the external site accepted the intended business change |
| Repeatable service | Blueprint SDK | A reusable service template with typed jobs, inputs, outputs, artifacts, and trigger choices | That each live instance is healthy or that every result is correct |
| Service execution | Operator-run Blueprint Service | A live instance of the template that listens for jobs and returns results | That the operator followed the claimed implementation without an execution check |
| Pay-per-request access | x402 payment ingress | Payment requirements over HTTP and a path from verified payment to a paid job request record | That payment settlement means the job finished or produced a good result |
| Confidential execution | TEE runtime and attestation | Signed evidence about code or hardware-backed execution state | That a model answer or generated patch is correct |
| Result improvement | @tangle-network/agent-eval | Cases, traces, judges, comparisons, and promotion records | That a score is meaningful without a calibrated case set and real backend |
A Blueprint is a reusable template for software that can run as a service. A Service is a live instance created from that template. A Job is one callable unit of work inside the Service. An operator is the person or team that runs the Service’s software and returns Job results. The Blueprint documentation describes those relationships and the distinction between off-chain application execution and protocol coordination.
The Blueprint Runner is the process that dispatches Blueprint Jobs to their handlers.
An x402 request uses HTTP 402 Payment Required to tell a caller which payment is required, then accepts a signed payment payload on a retry.
Tangle’s x402 gateway verifies and settles the payment through a facilitator before injecting a paid request into the Blueprint Runner.
The runner records that request as a JobCall, the identifier for one queued call, but that identifier does not mean the Job completed.
The official x402 flow and Tangle’s gateway documentation both separate payment acceptance from resource delivery.
A TEE attestation is signed evidence about a Trusted Execution Environment, such as a code measurement or hardware-backed execution state. It can answer “what execution boundary and measurement did the verification service accept?” It cannot answer “was the document classification right?” Use the Tangle attestation explanation when the trust claim depends on confidential execution.
Smoke-test the boundaries before composing them
These public discovery calls check service availability without creating a workspace or running a Job:
curl -fsS https://router.tangle.tools/api/health
curl -fsS https://router.tangle.tools/v1/models
curl -fsS https://sandbox.tangle.tools/health
npm install @tangle-network/sandbox
npm install @tangle-network/agent-evalA Router health response says that the service can answer a health request. The model list says which model records are currently published and routeable according to that service. The Sandbox health response says that the public API answers. The install commands make package provenance explicit.
None of these calls runs the tax workflow. The next test should create one authenticated workspace, copy one non-sensitive sample file, run one deterministic parser, save the output, and delete the workspace. Only after that boundary works should the application add a model request, browser session, payment path, or confidential runtime.
From a run to an evaluation
An evaluation, or eval, is a repeatable test over named scenarios with a defined check. For this document workflow, scenarios could cover a complete document set, a missing form, an unreadable scan, a malformed number, and a model timeout.
A judge is the code or model that applies the scoring rule to an output. Use deterministic checks for file presence, schema validity, arithmetic, and required review questions. Use a model judge only for qualities that cannot be checked exactly, and record the judge version and input it saw.
The evaluation record should include:
| Field | Why it matters |
|---|---|
| Scenario ID and input hash | Shows which case ran |
| Agent profile ID | Shows model, tools, permissions, and budget |
| Runtime and environment | Shows where the actions executed |
| Trace and artifact IDs | Connects the score to observable work |
| Baseline and candidate labels | Supports a fair comparison when something changed |
| Check or judge version | Makes the scoring rule attributable |
| Cost and duration | Prevents quality claims from hiding resource growth |
| Failure category | Separates model, tool, policy, infrastructure, and evaluator failures |
The agent-eval repository describes a trace-first approach that compares changes on the same cases and preserves run data for analysis. Preserve traces, artifacts, profiles, and check versions so evaluation results remain comparable and inspectable. For the concrete workspace lifecycle behind these records, read AI agent sandbox.
Failures need to stay in their own columns
Assign each failure to the model, provisioning, workload, payment, or measurement boundary.
| Observed failure | Likely boundary | Record that should exist |
|---|---|---|
| Model returns an uncertain classification | Model or task contract | Prompt, model route, raw response, and uncertainty field |
Workspace never reaches running | Provisioning or quota | Create request, lifecycle states, timeout, and service error |
| Command exits non-zero | Workload or dependency | Command, working directory, exit code, stdout, and stderr |
| Browser shows a confirmation but backend rejects it | External service | Screenshot, request log, and service-side confirmation status |
| Payment settles but job does not complete | Payment and execution are separate | Payment receipt, job ID, queue state, and failure policy |
| Attestation validates but output is wrong | Execution identity versus task quality | Attestation fields plus independent result check |
| Eval score rises while traces are incomplete | Measurement failure | Missing-span or missing-artifact record and a failed comparison |
Replacing any of those failures with a generic “agent failed” loses the information needed for the next fix. The runtime should preserve the failure even when the product later shows a shorter user-facing message.
Choose the smallest complete environment
A text-only answer may need model access and a request record. Add a sandbox when the task needs files, packages, processes, or retries. Add a browser when the task must operate a website. Add a Blueprint when another team or operator must run the service repeatedly. Add x402 when a caller needs a programmatic payment challenge before a paid job. Add a TEE and attestation when the execution boundary itself changes the trust decision. Add an evaluation when a change needs to be compared against a defined set of cases.
The design question is concrete: what action must happen, what authority does it need, what state must survive, and which record lets another person check the result? If the answer fits in one local process and one deterministic test, a larger runtime is unnecessary. If the answer involves external side effects, multiple attempts, or a paid service, the boundaries should be explicit before the model receives more authority. For a continuing agent session that needs isolated state and recovery, compare Tangle Sandbox and E2B.
What is an AI agent runtime environment?
It is the software and compute around a model that supplies tools and state, enforces permissions, manages task lifecycle, routes model requests, and records what happened during a multi-step job.
Is the runtime the same as the model?
No. The model generates decisions or text, while the runtime determines which actions are available, where they execute, and which results are retained.
What is an agent profile?
An agent profile is a versioned configuration for one run class. It usually names the model, tools, instructions, permissions, resource limits, budget, and output record.
What does a Router do?
A Router accepts a stable model-request format and selects a provider or model route according to its configuration and available capacity. It can simplify model switching and usage attribution, but it does not verify the correctness of the model’s answer.
What does an x402 payment prove?
x402 payment verification proves that a caller supplied a payment payload accepted by the configured payment rules. The service still needs an execution record and a task-specific result check.
Does attestation prove an AI result is correct?
No. Attestation can prove selected properties about code identity or a hardware-backed execution boundary. Correctness still needs an evaluation, deterministic check, replay, or human review appropriate to the task.
What should I build first?
Name one task, remove every capability it does not need, run one successful and one rejected case, and save the trace and artifacts. Expand the runtime only when a reviewer can explain both outcomes from the retained record.