1
# Agent Guardrails
2
3
A safety harness for autonomous/semi-autonomous agent runs: classifies every action as
4
read-only, reversible-write, or destructive; gates destructive actions behind explicit
5
human confirmation (stated blast radius, no pre-approval loopholes); enforces
6
turn/budget limits with a clean halt-and-summarize instead of a hard kill; and appends
7
every action to a structured, append-only JSON Lines audit log.
8
9
## When to use
10
11
- Wrapping any agent run with meaningful autonomy (multi-step, tool-using, especially
12
  unattended/scheduled runs) where destructive mistakes are costly.
13
- Environments with compliance/audit requirements — the JSON Lines log gives a
14
  reviewable record of every action taken.
15
- Long-running agent sessions where an unbounded loop is a real risk (turn/budget caps).
16
17
## Install
18
19
```bash
20
npx openagents-cli add openagents/agent-guardrails
21
```
22
23
| Runtime | Installed to |
24
|---|---|
25
| `claude-code` | `.claude/skills/agent-guardrails/` |
26
| `codex` | `.codex/skills/agent-guardrails/` |
27
| `openai-agents` | `.openai-agents/agent-guardrails/` |
28
| `langgraph` | `.langgraph/agent-guardrails/` |
29
| `generic` | `.openagents/agent-guardrails/` |
30
31
## Inputs
32
33
| name | type | required | default | description |
34
|---|---|---|---|---|
35
| `max_turns` | number | no | `50` | Max tool-call rounds before halting to ask for continuation |
36
| `budget_usd` | number | no | — | Soft cost ceiling before halting (only enforced where the runtime exposes cost tracking) |
37
| `audit_log_path` | path | no | `.openagents/audit.log.jsonl` | Where audit entries are appended (JSON Lines) |
38
39
## Example run
40
41
```
42
> Use the agent-guardrails harness for this cleanup task. Max 30 turns.
43
```
44
45
Read-only exploration proceeds freely; file edits are logged; a proposed
46
`DROP TABLE staging_events` is held at the confirmation gate with the exact row count
47
and no-undo warning stated before the agent waits for explicit approval; at 30 turns
48
the harness halts, summarizes progress, and asks whether to continue.
49
50
## Files
51
52
- `HARNESS.md` — the pre-action check, confirmation gate, turn/budget limits, and
53
  audit logging rules (entry point).
54
- `policies/destructive-actions.md` — concrete classification rules (read-only vs.
55
  reversible-write vs. destructive) with examples.
56
- `audit-log.schema.json` — JSON Schema for each audit log entry.
57
58
## Limitations
59
60
- This is a set of instructions the agent follows, not a sandboxed enforcement
61
  mechanism — it constrains a cooperative agent, it does not replace OS/infra-level
62
  permission boundaries for untrusted code execution.
63
- Budget tracking is only as good as the runtime's own cost-reporting; if unavailable,
64
  the harness says so rather than silently pretending to enforce it.
65
- The confirmation gate requires a reachable human operator; unattended runs that hit a
66
  destructive action will block on it and report rather than proceed.
67