Input and output guardrails
createAgent({ guardrails }) (or ExecuteOptions.guardrails) checks a run at
three points, each list in order:
Parallel input guardrails. A slow input check (one that calls a model,
such as
moderationGuardrail({ model })) adds its whole latency before the
agent starts answering. Mark it runInParallel: true (on your own
IoGuardrail, or as an option of promptInjectionGuardrail and
moderationGuardrail) and it runs while the first model call is already in
flight: the blocking input guardrails (the default) run first, including their
rewrites, then the parallel ones start together on that input and the model
call starts at once. Until every parallel check has passed, nothing the call
produced is released: its text.delta, reasoning.* and provider-run tool
events are held (step.start is not), in order, and its tool calls do not
run; a reply that comes first waits for the checks. When they pass, the held
events go out and the run goes on exactly as with blocking guardrails. When one
trips, the model call is aborted, the held events are dropped, nothing of the
call reaches the transcript, a checkpoint or onLLMResponse, and the run ends
with finishReason: 'guardrail' and guardrail.tripped (or
GuardrailError with onTripped: 'throw') like a blocking trip. A parallel
check cannot rewrite, because the model already has the input: a rewrite
result blocks, with the reason starting runInParallel guardrails cannot rewrite: . The trade-off is cost: a tripped call may already have used tokens.
They count in result.usage when the provider reported them (a call that
finished before the trip); an aborted stream usually reports none, and none is
estimated. Only the first model call of a run is raced, and a run resumed after an
approval does not check its input again. On output and
tools guardrails runInParallel is ignored. A guardrail model string is a
provider/model spec: the vendor/ prefix chooses the provider; with
OpenRouter use openrouter/<vendor>/<model> (e.g.
openrouter/openai/gpt-4o-mini).
{ name, check(ctx) }. ctx has kind ('input', 'output'
or 'tool'), text, the run’s messages, toolName and args for a tool
call, and the run’s signal. check returns (or resolves to) { ok: true }
or { ok: false, reason, action?, replacement?, info? }:
action: 'block'(the default) ends the run withfinishReason: 'guardrail'andresult.guardrail({ name, kind, reason, toolName?, info? }).result.textis''and a blocked reply is not added to the transcript; a blocked tool call does not run (nor do the calls after it in that turn) and gets a “cancelled” result, so the transcript stays valid.stream()emitsguardrail.trippedbeforerun.done.action: 'rewrite'replaces the text withreplacement(a tool call’s arguments:replacementis the new arguments as JSON), the next guardrail sees the new text, andstream()emitsguardrail.rewrote.
onTripped: 'throw' a block rejects with GuardrailError
(LOUSHO_GUARDRAIL_TRIPPED, with the same guardrail) instead. A check
that throws fails the run. Sub-agents run their parent’s guardrails, then their
own. Agent spec files name built-in guardrails in policy.guardrails (see Configuration).
The last four are a starter set for checks most production agents need:
result.guardrail, guardrail.tripped,
guardrail.rewrote, GuardrailError.guardrail) carries info, a
GuardrailTripInfo when the guardrail gives one, which the starter set always
does: { category: 'pii', matches: [{ type, start, end }] },
{ category: 'secret', matches: [{ label, start, end }] },
{ category: 'prompt-injection', source: 'heuristic' | 'model', signals } or
{ category: 'moderation', categories }. Offsets point into the checked text
(ctx.text). info never contains the matched text, and neither does the
reason of the PII and secret checks (types and labels only), so events,
traces and logs do not copy the personal data or the secret. Your own
guardrail can return info: { category: 'custom', ...anything }.
Limits. The PII, secret and prompt-injection checks are heuristic pattern
checks: they catch the common forms listed above and miss others (personal data
in other formats or languages, a secret with an unknown prefix, an injection
that is paraphrased, translated or encoded), and they flag some harmless text
too (an order number that looks like a phone number, a version string that
looks like an IP address, a user asking about “system prompts”). Treat them as
a first filter, not a security boundary; keep tool permissions and approvals in
place for anything that matters. The model-backed checks are only as reliable
as the model, cost one call per checked text, and fail closed: a reply that is
neither form blocks, with a reason saying the reply could not be read. Tool
results (for example a fetched web page carrying an indirect injection) are not
checked by any guardrail yet.
Patch checks
runPatchChecks(patch, checks) runs every check concurrently over a
proposed patch and rolls the results up into one verdict. The
ops-pipeline example uses it to gate a fixer
agent’s patch before a pull request is opened:
Fail-closed. A check that throws, rejects, does not settle within its
timeout (30 s by default), or resolves with anything but
pass: true counts as
failed: runPatchCheckSafely(check, patch) wraps each one. A command
check kills its process when the timeout fires (on Windows, the whole
process tree). Write your own as { name, check(patch) } returning
{ pass, reason? }.
Sandboxed tools
A tool opts in withrequiresSandbox: true and a sandboxExecute(args, sandbox)
function. The executor then calls sandboxExecute with the run’s
SandboxAdapter instead of calling execute. createAgent() does not take
sandbox yet, so this goes through the executor.
Advanced: the executor API
NoopSandbox(the default) runs on the host. It is a stand-in, not isolation.SubprocessSandboxruns each command in a new, network-isolated, auto-removed Docker container, with no host directory mounted except thecwdyou pass. It needs a running Docker daemon and the optional peerdockerode(npm install dockerode@^5.0.1; loaded on first use). When the run is cancelled (itssignalaborts) or the command times out, the container is killed and removed. Each container runs as a non-root user (user, default'1000:1000'; on a Linux host it must be able to write the mountedcwd), with every Linux capability dropped,no-new-privileges, andlimitsof 512 MiB memory, 256 processes and 1 CPU by default.writeFile(path)writes on the host only underroot(default: the working directory); a path outside it, also through a symlink, is refused withLOUSHO_SANDBOX_PATH_DENIED.- Implement
SandboxAdapter(name,run(cmd, args, opts),writeFile(path, content)) for another backend.
SandboxShell puts the workspace shell tool behind the same
adapter; see Workspace tools.