Skip to main content

ContrAgent

Symbolic temporal supervision of LLM agents using assume-guarantee contracts.

License: Apache-2.0 Python 3.10+ arXiv

ContrAgent: contracts are compiled once into DFA monitors, which gate tool calls online and replay recorded traces offline

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)

Source distribution for contragent 1.1.0
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)

Table of built distributions (wheels) for contragent 1.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page