Agents, Frameworks, and Sandboxes

An agent is not a model with a more ambitious system prompt. It is a software system that repeatedly asks a model what to do, interprets the proposal, decides whether the proposal is allowed, performs any approved effect, records the result, and decides whether to continue. The model is one component inside that system. It is not the scheduler, authorization service, durable store, or security boundary.

The ReAct work introduced a widely used pattern for interleaving model reasoning with actions in an external environment (Yao et al. 2023). That pattern explains how a trajectory can be generated. A production runtime must add the controls that the prompting method does not provide: typed actions, complete mediation, bounded execution, durable state, recovery, approval, isolation, and evidence.

The practical unit is therefore an agent release: an agent execution contract, a versioned controller, a governed set of tools, an isolation policy, an evaluation report, and a reversible deployment. Chapter 38 develops the behavioral patterns; Chapter 41 develops the durable runtime. This chapter connects them to tool protocols and sandbox enforcement.

Freeze the agent execution contract

Framework selection comes after the agent execution contract. The contract states what one run may accomplish, which external effects are permitted, what evidence proves success, and how the system stops safely. Without it, a demo that reaches a plausible answer can be mistaken for a dependable application.

“Resolve customer issues” is not a task boundary. A usable contract identifies the system of record, the set of customers, the allowed read and write actions, the fields that may be disclosed, the evidence that a case is closed, and the conditions that require escalation. It also distinguishes a draft from an effect. Composing a refund request and issuing the refund are different capabilities.

The contract is versioned with the complete served system: model revision, prompt and context builder, tool schemas, policy, controller, memory rules, sandbox image, and decoder settings. A change to any of them can change the trajectory even when the framework package stays fixed.

Make the control loop explicit

The trusted controller turns a stochastic model proposal into a governed state transition. One compact formulation is

$$\begin{aligned} u_t &\sim \pi_{\theta}(\mathord{\cdot}\mid C(s_t)), \\ a_t &= V(u_t), \\ d_t &= A(p_t,a_t,r_t), \\ o_t &= \begin{cases} X(a_t), & d_t=\mathrm{allow}, \\ \bot, & d_t\in\{\mathrm{deny},\mathrm{approve}\}, \end{cases} \\ s_{t+1} &= \delta(s_t,a_t,d_t,o_t). \end{aligned}$$

where:

• $t$ is the step index, and $s_t$ is the current durable run state;
• $C$ is the context projection that selects and serializes the bounded view of state sent to the model;
• $\pi_{\theta}$ is the model distribution with parameters $\theta$, and $u_t$ is one sampled model proposal;
• $V$ is schema validation and normalization, and $a_t$ is the validated proposed action or final answer;
• $A$ is the external authorization function, $p_t$ is the verified principal and policy context, $r_t$ is the current resource snapshot, and $d_t$ is the authorization decision allow, deny, or approve;
• $X$ is the credentialed tool executor, $o_t$ is the tool observation, and $\bot$ means that no tool was executed; and
• $\delta$ is the deterministic transition function that appends the recorded event and produces the next durable state $s_{t+1}$.

The stochastic part ends at the proposal. Schema validation can reject malformed arguments, but it cannot decide whether a syntactically valid transfer is authorized. The policy decision uses verified identity and current resource state outside the model. Human approval is a separate decision when policy requires it. Tool execution occurs only after authorization, and the observation is recorded as untrusted data rather than silently promoted to an instruction.

Keep distinct kinds of state distinct

“Memory” is too vague for recovery design. An agent run usually contains at least five kinds of state:

A message session is not a workflow checkpoint. A checkpoint is not proof that an external side effect did or did not happen. A trace is not automatically a replay log. Treating these objects as one “memory” produces duplicate writes, stale approvals, and recovery that begins from the wrong world state.

Stop for declared reasons

Every run has a step budget, token budget, cost budget, and wall-clock deadline. It also stops after a declared consecutive failure limit or a no-progress detector, such as repeated identical actions or no change in the task state. Tool calls have their own deadline and output limit.

Terminal reasons are part of the API: succeeded, failed, refused, cancelled, timed_out, budget_exhausted, and needs_human. A run that timed out, was cancelled, or ended with its budget exhausted is not reported as a model failure. A run in a terminal state cannot resume execution under the same identity; a retry creates a linked attempt with a new lease and an explicit recovery decision.

Choose control semantics before a framework

Framework names overlap in capability and change faster than the underlying control patterns. Choose the pattern that makes required transitions visible, then test whether a candidate library implements those semantics.

A handoff transfers responsibility for the next interaction. A bounded subagent call does not: the parent remains responsible and receives a result. Fan-out and join require a rule for partial failure, cancellation, ordering, and conflicting answers. “Multi-agent” does not supply those semantics by itself.

Use a capability matrix rather than a product leaderboard:

Current libraries expose different combinations of these features. LangGraph documents checkpointed graph state and interrupts; Pydantic AI delegates durable execution to workflow integrations; the OpenAI Agents SDK documents both manager-style orchestration and handoffs (LangChain 2026; Pydantic Services 2026; OpenAI 2026). Those facts are inputs to a local test, not universal product recommendations.

Run the same proof workflow against each candidate: two reads, one approval-gated write, a fan-out and join, and a final state check. Crash the worker after the external write succeeds but before its response is stored. Deliver the same callback twice. Cancel an in-flight tool, upgrade the controller while approval is pending, then resume. Measure duplicate effects, lost work, state divergence, latency, cost, and operational effort. That evidence is more durable than a feature table.

Make recovery safe for effects

Durable execution preserves control state. It does not create exactly-once effects across an external system. A worker can complete a write and fail before recording the reply, so the controller may see an ambiguous outcome. Many task queues also provide at-least-once delivery, which means a handler may receive the same logical request more than once.

Every logical side effect therefore has:

• a stable idempotency key derived from the run and logical action, not the network attempt;
• an intent record written before dispatch;
• an effect receipt containing the external operation identity, observed resource version, outcome, and time;
• a reconciliation operation that can query an ambiguous result; and
• compensation or escalation when the external API cannot deduplicate safely.

Retries preserve the idempotency key. A retry policy distinguishes transport failure, retryable tool failure, business rejection, policy denial, and unknown outcome. An at-most-once attempt avoids automatic repetition but may lose work; an at-least-once attempt needs duplicate handling. Neither label proves exactly one real-world effect. Durable workflow documentation makes the same distinction between replayable control and external activities (Temporal Technologies 2026; Amazon Web Services 2026).

Resume, replay, and reevaluation answer different questions:

• Resume continues a pending run from a durable boundary.
• Workflow replay rebuilds control state from recorded events without repeating recorded effects.
• Recorded-output test replay feeds saved model and tool outputs through new deterministic controller code.
• Live reevaluation calls the model and tools again and may produce a different trajectory.

Version pending runs explicitly. If a controller or tool contract changes, the runtime either migrates the saved state, continues with the pinned old version, or terminates safely. It must not reinterpret an old approval or effect receipt under new semantics.

Delegate with a typed envelope

A child agent receives less than the parent, not a copy of all parent authority. The delegation envelope records:

delegation:
  parent_run_id: run_85a
  child_run_id: run_85a_research_2
  objective: "Compare the two named incident records"
  input_refs: [incident_104, incident_119]
  permitted_tools: [read_incident, search_runbook]
  authority_scope: {tenant: acme, access: read_only}
  budget: {steps: 12, tokens: 18000, wall_clock: 5m}
  deadline: 2026-08-07T18:30:00Z
  result_schema: incident_comparison_v2
  completion: "return evidence for every difference"
  return_owner: run_85a

The parent validates the result and remains accountable for any later effect. The child cannot widen its tool set, extend its deadline, or delegate broader authority than it received. Cancellation propagates down the ownership tree; results arriving after cancellation are recorded but cannot trigger a new effect.

Treat every tool as an effect contract

A tool name and JSON Schema are not enough. The controller needs to know what the tool reads or changes, what authority it needs, how it fails, and whether it is safe to repeat.

A versioned tool contract includes:

The executor validates arguments again at the execution boundary. It checks the principal, tenant, resource, current version, and policy even if the controller already checked them. This is complete mediation and least privilege in the sense described by Saltzer and Schroeder (Saltzer and Schroeder 1975). A tool server must not trust a model-provided resource handle as proof of ownership.

Tool results are also untrusted. A web page, email, document, issue, or database field can contain an indirect prompt injection. InjecAgent and AgentDojo show that poisoned external content can induce harmful calls or data disclosure in tool-using agents (Zhan et al. 2024; Debenedetti et al. 2024). Returned prose cannot grant authority, alter policy, approve a pending action, or widen the tool catalog. Treat it as tainted data with source provenance.

Bind approval to what will execute

A human approves the exact effect, not the model's summary. The approval view shows the tool, normalized arguments, target resource, current resource version, principal, tenant, data leaving the boundary, expected postcondition, and rollback or irreversibility. The approval record includes a digest of that payload, the approver, the policy version, and an expiry.

Immediately before execution, trusted code rechecks authority and resource state. If the arguments, resource, principal, policy version, or relevant state has changed, the approval expires and the runtime must re-authorize or ask again. Approval is not a reusable bearer capability and never enters model context as a secret token.

Use MCP as a wire protocol, not a trust mark

The Model Context Protocol (MCP) standardizes tool discovery and invocation, schemas, transports, protocol metadata, and optional HTTP authorization. The final 2026-07-28 revision uses a stateless protocol core: request metadata carries the protocol revision and capabilities, while stateful tools expose explicit application handles (Parra and Delimarsky 2026; Model Context Protocol 2026).

That interoperability has limits. A client and server still need compatible revisions, transports, content types, authorization flows, and extensions. Test version negotiation and capability negotiation for the exact pair being deployed. Conformance to the wire format does not grant trust, business authorization, safe retry semantics, data rights, or permission to expose a newly discovered tool.

In particular:

• inputSchema and outputSchema validate data shape; they do not establish a precondition, postcondition, side-effect class, or authority.
• A JSON-RPC request ID correlates protocol messages; it is not a business idempotency key.
• A state handle is a name, not a capability. Recheck its owner and tenant on every call.
• Tool discovery is inventory, not endorsement. Pin server identity, package digest, schema digest, and reviewed catalog. Quarantine unexpected catalog changes.
• A gateway can centralize routing, metering, and policy, but it does not replace authorization at the MCP server and external resource.

HTTP authorization is optional in MCP. Where it is used, the client and server must validate issuer, signature, expiry, token audience, and intended resource. The authorization specification prohibits token passthrough: a server cannot accept a token meant for another service and relay it downstream (Model Context Protocol 2026). Separate the client-to-MCP credential from any server-to-downstream credential. A proxy with ambient authority can otherwise become a confused deputy; per-client consent, audience binding, minimal scopes, and independent resource authorization are required (Model Context Protocol Contributors 2026).

Local stdio servers are subprocesses with the host authority they inherit. Run only pinned and reviewed binaries, under an unprivileged identity, with explicit filesystem, environment, process, and network restrictions. Calling the subprocess through MCP does not sandbox it.

Specify the sandbox from a threat model

A sandbox is an execution boundary for code and processes whose behavior cannot be trusted. It reduces the consequences of a compromised model, poisoned tool output, malicious dependency, or ordinary bug. It does not decide whether an action is authorized, and it does not make data safe to disclose.

Start with a threat model. Name the attacker and the protected assets:

• host escape or access to another tenant;
• cross-tenant or cross-run data disclosure;
• data exfiltration through network, logs, artifacts, or allowed services;
• denial of service through CPU, memory, process, disk, output, or network use;
• supply chain execution from packages, images, extensions, and build scripts;
• unwanted persistence in overlays, snapshots, caches, logs, or external APIs;
• theft or replay of credentials; and
• abuse by a trusted operator or compromised control plane.

Isolation is a conjunction of guarantees rather than a product label:

$$G = K \land P \land F \land N \land I \land R \land T \land C,$$

where $G$ is the claimed sandbox guarantee; $K$ is the kernel or system-call boundary; $P$ is process, user, IPC, and tenant isolation; $F$ is filesystem, mount, device, and artifact isolation; $N$ is ingress and network egress policy; $I$ is workload identity and credential authority; $R$ is resource control; $T$ is workspace lifetime, persistence, cleanup, and data-remanence control; and $C$ is control-plane integrity, patching, audit, and configuration. If any term needed by the threat model is absent, the overall claim does not hold.

Compare mechanisms by call path

Firecracker demonstrates how a small virtual machine monitor can combine a separate guest kernel with a reduced device model for serverless workloads (Agache et al. 2020). gVisor inserts a userspace application kernel rather than passing application syscalls directly to the host, but its Sentry and host interfaces are still part of the trusted surface (gVisor Project 2026). NIST's container guidance likewise treats images, registries, orchestrators, runtimes, hosts, and data as separate risk areas (Souppaya et al. 2017).

There is no universal winner. A microVM, userspace kernel, hardened container, language isolate, or browser executor may be appropriate under a particular threat model. Use defense in depth and test the configured system. Startup time, density, compatibility, accelerators, snapshot support, and cost are workload measurements, not isolation proofs.

Define the complete sandbox envelope

An isolation label leaves most operational authority unspecified. A deployable envelope pins the enforcement points:

sandbox:
  image_digest: sha256:<immutable-image>
  runtime_revision: <runtime-and-host-policy-version>
  identity: {tenant: acme, run_id: run_85a, uid: 10000}
  filesystem:
    root: read_only
    inputs: [{digest: sha256:<input>, mode: read_only}]
    workspace: {mode: fresh_overlay, max_bytes: 2147483648}
    devices: []
  network_egress:
    default: deny
    allowed_destinations: [artifact-mirror.internal]
    methods: [GET]
    max_bytes: 104857600
  resources:
    cpu: 2
    memory_bytes: 4294967296
    process_count: 128
    disk_bytes: 2147483648
    open_files: 512
    output_bytes: 16777216
    wall_clock: 10m
  workspace_lifetime: one_run
  artifacts: {allow: [result.json], scan: true, hash: true}
  cleanup: {lease: 15m, revoke_credentials: true, verify_process_tree: true}

The runtime enforces the filesystem mounts, read-only inputs, network egress, CPU, memory, process count, disk, file descriptor, output, and wall-clock limits outside the workload. Limits cover descendants, not only the first process. Allowed network destinations are resolved and revalidated through trusted DNS; IPv4, IPv6, redirects, alternate protocols, and metadata endpoints receive the same policy.

Keep credentials outside the workload

The invariant is not that no trusted component ever holds a credential. It is that untrusted execution receives no reusable ambient authority. Prefer a semantic action broker outside the sandbox. If direct access is necessary, use a virtual key issued by a gateway for model access, a short-lived scoped substitute for a provider key. No raw provider key enters the sandbox.

For other services, mint a short-lived token bound to workload identity, tenant, audience, resource, action, and expiry. Where a service cannot issue one, egress substitution may exchange a placeholder at a trusted proxy, but the proxy must bind the request to the exact allowed destination, method, path, quota, and operation. Otherwise the proxy becomes a credentialed confused deputy. Credentials stay out of images, workspace snapshots, exported artifacts, crash dumps, model context, and logs, and are revoked when the lease ends.

Default-deny network policy is necessary but incomplete. Test DNS rebinding, redirects, raw IP addresses, IPv6, WebSockets, uploads to an allowed host, and cloud metadata endpoints. An allowed hostname is not an allowed action.

Treat workspace state as a governed artifact

Create every ephemeral run from a clean baseline with an immutable image digest and explicit read-only inputs. Record the input digest, dependency locks, tool versions, runtime and kernel revisions, locale, clock and randomness policy, resource limits, and network fixtures. A workspace snapshot is mutable state, not a clean baseline; it can retain processes, credentials, randomness state, caches, and malicious files.

Export only declared paths. Scan outputs for malware, secrets, unexpected repositories, links, device files, archives, and executable content. Record each output digest and artifact provenance before the controller consumes or publishes it. Failed or suspicious outputs enter quarantine. A reset proves that a fresh run cannot read a canary written by the prior run, including through snapshots, caches, backing volumes, logs, or exported images.

Persistent workspaces are a separate feature with a separate retention and authorization policy. Suspending a process does not make its state safe or reproducible. Deleting an overlay also does not erase external API effects, backups, or retained logs.

Give browser agents two boundaries

A browser agent needs both web-content isolation and tenant isolation. A fresh browser profile separates cookies and storage for the run. The renderer sandbox and site isolation constrain hostile pages. An outer microVM, userspace kernel, or hardened container protects the broker and other tenants. A separate action policy governs navigation, downloads, uploads, clipboard, file URLs, local and metadata addresses, authenticated writes, and payments.

WebDriver is a privileged remote-control interface, not an untrusted tool endpoint (World Wide Web Consortium 2026). Do not expose it to the sandbox network or reuse a personal browser profile. A browser sandbox can contain renderer code while the automated browser still misuses a legitimate account.

Wire the runtime through governed seams

The controller consumes services; it does not become the trust hub. Model, tool, state, and compute access cross separate enforcement points.

The model gateway in Chapter 82 and Chapter 88 controls model identity, routing, budget, and usage. The tool broker authenticates the caller, authorizes the exact effect, and obtains narrowly scoped credentials. The sandbox supervisor allocates the boundary, applies resource and egress policy, and reconciles cleanup. Durable state records decisions and receipts. No single gateway log is sufficient evidence for all four paths.

Record evidence that supports recovery and audit

An observability trace helps diagnose a run; an audit record supports an accountability claim; an event log supports recovery. They may share identifiers without becoming the same object.

At minimum, record:

• run ID, attempt ID, trace ID, parent span, timestamps, and controller revision;
• user or workload principal, tenant, delegated actor, and authority expiry;
• model revision, prompt and context-builder versions, token use, and latency;
• tool version and schema digest, normalized argument digest, resource identity, policy decision, policy version, and denial reason;
• approval identity, exact approved payload digest, expiry, and revalidation;
• idempotency key, retry number, effect receipt, external state version, and compensation;
• sandbox image digest, runtime policy, resource usage, network destinations, artifact digests, and cleanup evidence; and
• terminal reason, success evidence, unresolved ambiguity, and last-known-good release.

W3C Trace Context standardizes how a trace ID and parent span propagate across services; it does not define agent semantics or guarantee that every relevant event was sampled and retained (World Wide Web Consortium 2021). Keep tokens, reusable credentials, and sensitive payloads out of logs by default. Protect the event sink outside the sandbox, apply retention and access policy, and test that crashes and denied actions still leave a complete record.

Verify failure behavior before granting authority

Evaluation covers the final answer, external end state, policy compliance, trajectory, latency, cost, and repeated-run reliability. Chapter 87 provides the statistical harness. Agent-specific acceptance tests also exercise the control plane:

Run these tests through the deployed model gateway, tool server, policy engine, sandbox image, and controller rather than mocking away the boundary under test. For a high-impact write, use shadow execution or a simulator first, then a canary tenant with a narrow failure budget. Preserve the last-known-good route until the canary satisfies both task and containment gates.

Operate the agent lifecycle

A practical sequence is:

1. Freeze the contract. Define task boundary, success evidence, permitted effects, authority, data, budgets, terminal reasons, recovery, and rollback.
2. Build the smallest explicit loop. Keep deterministic work in code and use the model only where the contract requires uncertain interpretation or choice.
3. Specify every tool. Pin schemas and implementation digests; add policy, idempotency, errors, data, credentials, and postconditions.
4. Choose control semantics. Select linear loop, state graph, durable workflow, filesystem harness, or supervisor and worker from the transitions the task needs.
5. Choose and test isolation. Start from the threat model, define the full sandbox envelope, and run escape, exfiltration, resource, remanence, and cleanup tests.
6. Rehearse recovery. Use failure injection for worker crashes, duplicate callbacks, timeouts, cancellation, stale approval, and ambiguous external outcomes.
7. Seal the release. Bind model, prompt, controller, tool catalog, policy, sandbox image, state schema, and evaluation plan to digests.
8. Evaluate and shadow. Measure success, external state, policy compliance, repeated-run reliability, cost, latency, and failure containment.
9. Canary with narrow authority. Use limited tenants, tools, credentials, egress, concurrency, and spend while the last-known-good route remains live.
10. Monitor and requalify. Review failures, reconcile leases and ambiguous effects, rotate credentials, patch boundaries, and rerun affected gates.

A requalification trigger includes a model revision, prompt or context change, controller or state migration, tool schema or implementation change, policy change, authorization flow, sandbox image or runtime change, new host or device, browser revision, network policy, artifact pipeline, tenant boundary, or material traffic shift. Each trigger creates a new release identity and reruns the tests for the affected enforcement boundaries.

The output is an agent release record linking the agent execution contract, controller and state schema, model revision, tool and policy digests, sandbox envelope, approval and effect evidence, evaluation report, canary result, and rollback outcome. That record, not the framework name, is what makes an agent an operable part of the infrastructure.

Lower-layer constraint

The controller cannot recover an effect that the external API cannot identify, contain code outside the boundary enforced by the host, or reconstruct evidence that the gateways and event store never recorded. Model serving limits shape latency and cost; tool and identity systems shape authority; storage shapes recovery; compute and network policy shape containment. The agent contract must fit those lower-layer guarantees.

Conversely, a microVM or durable workflow cannot rescue an overbroad business permission. Isolation limits where code runs. Authorization limits what the verified principal may do. Both must hold at the execution boundary described in Chapter 56.

Further reading

The primary papers establish the action pattern and observed attack surface; the standards and systems sources define tool, authorization, tracing, durable execution, and isolation boundaries.