Run tool-using LLM agents inside limits you can test.

Architecture

flowchart TD
    U["User input"] --> GI{"Input guardrails<br/>PII redaction"}
    GI -- block --> X["RunResult: blocked"]
    GI --> L["Agent loop"]
    L --> B{"Budget check<br/>steps, tokens, cost, time"}
    B -- exceeded --> Y["RunResult: max_steps / budget_exceeded / timeout"]
    B --> P["Provider.complete<br/>retry + backoff on transient errors"]
    P --> M{"Tool calls?"}
    M -- yes --> TC{"Tool-call guardrails<br/>allowlist"}
    TC --> V["Validate args<br/>pydantic schema from type hints"]
    V --> A{"Write tool?"}
    A -- yes --> H["Approver hook"]
    A -- no --> T["Run tool with timeout"]
    H -- approved --> T
    H -- denied --> R["Tool error to model"]
    T --> GO{"Tool-output guardrails<br/>PII redaction, injection"}
    GO --> L
    R --> L
    M -- no --> GF{"Output guardrails<br/>policy, citation grounding"}
    GF --> S["Structured output<br/>validate, one repair attempt"]
    S --> Z["RunResult + spans"]
    Z --> E1["JSONL exporter"]
    Z --> E2["OpenTelemetry exporter"]
    Z --> EV["Scenario eval checks"]

Design decisions

• The runtime owns retries. The SDK clients are created with max_retries=0. Every attempt then becomes its own llm_call span, and backoff counts against the wall-clock budget. Hidden SDK retries would make both traces and budgets inaccurate.
• Fail closed on writes. The default approver denies. A write tool runs only when a caller-supplied approver says yes. A non-idempotent call is recorded before it runs, so a write that crashes mid-flight is never retried or repeated in the same run. Only idempotent tools are retried after a timeout.
• Guardrails are data, not exceptions. Every check returns a Decision, and every decision is recorded as a span. Allow decisions are kept too, hidden by default in the renderer. This makes guardrail behaviour measurable: trigger counts in evals, precision and recall in the bench.
• Withhold, don't abort, on suspicious tool output. A blocked tool output is replaced with a notice and the run continues. One poisoned document should cost the agent a source, not end the task.
• Allowlist on two layers. Tools outside allowed_tools are left out of the request, and calls to them are also blocked at execution. The second layer catches hallucinated or injected tool names.
• Schemas come from type hints. Annotated[float, Field(gt=0)] produces both the JSON schema the model sees and the validator that enforces it. Validation errors go back to the model as tool errors it can recover from.
• The mock provider is a first-class provider. Scripted turns drive the unit tests. Rule policies drive the demos and the eval suite. Fault injection exercises the retry path. The example mock policies deliberately follow embedded instructions, so the evals measure what the guardrails prevent rather than what a well-behaved model would avoid anyway.

Where it fails

With guardrails on, every bundled scenario passes, so the failures worth knowing about come from the ablation and the guardrail bench. Model and data limits are the ones a better model or more data would move; design and scaffolding limits are choices in this code.

Model and data limits

Design and scaffolding limits

Considered and rejected. Raising exceptions on guardrail violations instead of returning typed decisions (docs/PRODUCT.md, trade-offs). It is simpler, but it loses redact-and-continue and makes trigger counts unmeasurable, which is what the ablation and bench above depend on. For the same reason, a blocked tool output is withheld and the run continues rather than aborting.

Known limitations

• The injection detector is a weighted regex heuristic. It catches explicit override and exfiltration phrasing and misses paraphrased or semantic attacks (recall 0.733 in-sample above). It is one layer next to the allowlist, approvals, and output policy, not a substitute for them.
• PII redaction is regex-based. It covers emails, phone numbers, and Luhn-valid card numbers, but not names, addresses, or government IDs.
• A timed-out tool runs on in its worker thread because CPython cannot kill threads. Tools with external side effects should enforce their own I/O timeouts.
• Runs are synchronous, with tool calls in a turn executed sequentially. There is no streaming and no async API yet.
• Mock token counts are estimates. Real-provider costs use a static list-price table in providers/pricing.py, which needs updating as vendor prices change. Unknown models are priced at zero unless you pass pricing=.
• The real-provider adapters are tested against fake clients for request and response translation. The bundled scenarios have not been run against live models in CI.
• The eval results describe the bundled synthetic scenarios and a rule-based mock policy. They show what the guardrails prevent for these cases, not how often a given real model would misbehave.

Data

All bundled data is synthetic and was written for this repository. No public or proprietary dataset is used, and nothing needs to be downloaded.

• src/agent_harness/examples/data/synthetic_orders.json: 40 orders from scripts/generate_synthetic_orders.py (seed 20260930). The first seven are hand-specified fixtures used by the scenarios, including the injection note on ORD-1006 and the card and phone numbers on ORD-1007. Customer emails use the reserved example.com domain, and card numbers are standard test numbers.
• src/agent_harness/examples/data/synthetic_kb/: eight short articles about a fictional product, "Lumen". kb-005 contains a deliberate injection payload.
• src/agent_harness/examples/data/synthetic_guardrail_cases.jsonl: 48 hand-labelled texts (15 injections, 33 benign including hard negatives, 11 with PII). Labels describe intent, not what the heuristics catch.

The synthetic data is released under the same MIT license as the code.

Roadmap, success metrics, and trade-offs are in the product brief.