ContrAgent
Symbolic temporal supervision of LLM agents using assume-guarantee contracts.
Write rules about what an agent may call, and when. ContrAgent checks every tool call against them before it runs, in microseconds, with no model in the loop.
The rules are assume-guarantee contracts: pairs of ALTLf formulas (linear temporal logic on finite traces with linear arithmetic) over the agent's tool-call trace. Each contract compiles to a deterministic finite automaton that serves two roles. Online, it gates each tool call before execution and blocks, redirects, or escalates a violating call. Offline, it replays a recorded trace and returns a verdict with the first violating event. A library is independent of the agent's model, transfers across agents that share a tool interface, and is checked for conflicts when loaded.
Installation
pip install -e . # runtime and command line; Python 3.10+
pip install -e ".[dev]" # plus pytest, ruff, and z3
Quick start
A contract is a rule over the order, count, and arguments of tool calls.
Two from examples/bank.yaml:
- desc: "identity must be verified before funds move"
G: {ltl: "(!(called('transfer_funds')) U called('verify_identity')) | G(!(called('transfer_funds')))"}
- desc: "no email after a file read"
G: {ltl: "G((called('read_file') -> G(!(called('send_email')))))"}
Both are about the shape of the trace, not its content: the first refuses a transfer until an identity check has happened, the second refuses any email once a file has been read, whatever the email says. Wrap your tools and every call is checked:
from contragent import ContrAgent
guard = ContrAgent(agent_id="bank_agent", config="bank.yaml", verbose=True)
@guard.wrap
def transfer_funds(amount: float, to: str) -> dict:
...
transfer_funds(500, "ACME")
# -> "The action `transfer_funds` was rejected by policy: identity must be
# verified before funds move. Choose a different approach."
A refused call never runs; the wrapper returns the refusal text, which is
what goes back to the model as the tool result (on_block="raise" raises
instead). guard.wrap({...}) wraps a whole tool table, and loops that
execute tools elsewhere call the two hooks, guard_before and
guard_after, themselves. When a call owes the next one (G(a -> X b)),
the result comes back with a prompt to call b next, and before the agent
stops, guard.guard_finish() prompts for what is still owed.
verbose=True prints every decision as it is made, as a timeline of the
session; trace_path= writes the session at finish_session() as a trace
file that contragent replay reads back.
The same library replays a recorded trace:
contragent replay trace.json --config bank.yaml
examples/ has a supervised tool-calling loop and traces to
replay; nothing there needs a model or credentials.
Documentation
- Authoring a contract library: the four rule shapes, weak versus strong until, which side a predicate belongs on, arguments, the checks to run before an agent runs under a library, enforcement actions, and the Python form.
- Interaction predicates: the vocabulary formulas are written over, and how each predicate is fed.
- Conflict check: optional solvers for the load-time library check.
- CHASE export: contract algebra and model checking on an exported library.
Offline evaluation
contragent eval traces/ --config contragent/contracts/benchmark/rjudge.yaml --agent "*"
contragent replay trace.json --config contragent/contracts/sopbench/bank.yaml
contragent conflicts --config contragent/contracts/sopbench/hotel.yaml
eval replays a directory of safe_*.json / unsafe_*.json traces and
reports precision, recall, and false-positive rate per contract;
replay prints the verdict and the first violating event of one trace;
conflicts runs the library conflict check.
Experiments
Both roles are evaluated on four benchmarks with the libraries under
contragent/contracts/. Success and safety are in percent; ASR is the
attack success rate.
| Benchmark | Role | Result |
|---|---|---|
| SOPBench (7 domains, gemini-2.5-flash) | online enforcement | success / safety 91 / 32 unguarded, 64 / 94 with the procedure in the prompt, 24 / 98 with an LLM judge, 90 / 98 with ContrAgent at +0.14 s per task |
AgentDojo (gpt-4o, important_instructions) |
online enforcement | ASR 47.7% → 11.1% with no injection detector and 0.79% with the recorded injection as the untrusted span, utility unchanged at 72.6%, 0.16 ms per call |
| R-Judge (571 records) | offline evaluation | precision 97.0%, recall 87.0%, F₁ 91.8%; the misses are semantic, not procedural |
| tau²-bench (4,464 traces) | offline evaluation | the strongest model passes 25–60% of tasks by outcome but 0% without a procedural violation, decided at 0.83 ms per call |
Each number's record, with the command that produced it and the summary
file behind it, is under experiments/. Third-party
datasets are not redistributed; benchmarks/README.md
says where to place each one and how to rerun.
Citation
@article{xiao2026contragent,
title = {Symbolic Temporal Supervision of {LLM} Agents Using Contracts},
author = {Xiao, Yifeng and Nuzzo, Pierluigi},
journal = {arXiv preprint arXiv:2609.18128},
year = {2026}
}
License
Apache-2.0. Copyright 2026 Yifeng Xiao. See LICENSE and
NOTICE; ContrAgent includes code derived from
Sponsio (Apache-2.0). See
CONTRIBUTING.md for the development workflow.
Metadata
Release files for contragent 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| contragent-1.1.0.tar.gz | 305.2 kB | With provenance | Details for contragent-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| contragent-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for contragent-1.1.0-py3-none-any.whl |
Total release size: 565.7 kB
Release files / contragent-1.1.0.tar.gz
| Download URL | contragent-1.1.0.tar.gz |
|---|---|
| Size | 305.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6930947edb583cc7d4d14d85a7c71ff971d8e8a21542d3790831d6d1fc7ce004
|
|
BLAKE2b-256 checksum How to use checksums |
db5c0aa0b8f5bc17f90ba285c7b8000b20fa16fef13e857b898f15cc93e6fa4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logRelease files / contragent-1.1.0-py3-none-any.whl
| Download URL | contragent-1.1.0-py3-none-any.whl |
|---|---|
| Size | 260.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7e6620599a91bab49330dd5d4efa8b1b6290fa51642a7ba54e9bcdf2f89d35b8
|
|
BLAKE2b-256 checksum How to use checksums |
e0793334a148534b9c15aa0c2e64539c11427e929d927df6926599341f6e8b9e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logSecurity for contragent 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for contragent-1.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.