Zero to gated agent in five minutes.
No API keys. No external accounts. No telemetry daemons. One clean install, one recorded golden trace, and an automated regression gate protecting every PR.
From local execution to automated CI gate.
Install the Engine
Install AgentDiff into your project via pip or uv. Air-gapped, zero cloud accounts, and zero background services.
# Install via pip
pip install agent-trajectory-diff
# Or add to uv project
uv add agent-trajectory-diffRecord Golden Baseline Trace
Execute your known good agent once to capture its canonical execution DAG. Commit the resulting JSON file directly into git.
agentdiff record my_agent_module:run \
--input '{"query": "Generate Q3 sales analysis"}' \
--output baselines/golden_run.jsonDiff Candidate Trajectories
When upgrading prompts, tools, or model weights, run the comparator to verify graph invariance and catch loops in < 5ms.
agentdiff baselines/golden_run.json candidate_run.json \
--explain \
--treeGate Pull Requests in CI
Enforce strict trajectory thresholds in your CI pipeline. Automatically exits with code 1 if thresholds fail and posts a rich PR comment.
agentdiff baselines/golden_run.json candidate_run.json \
--fail-on-regression \
--max-divergence 0.25 \
--max-cost-delta 10.0 \
--format markdown \
--output-file pr_verdict.mdTwo ways to integrate in your workflow.
Whether you prefer unit test assertions in pytest or repository-wide threshold governance in agentdiff.toml:
Programmatic Pytest Assertions
Run your golden test baselines directly through standard pytest runners. Automatically flag regressions with expressive assert_no_regressions() assertions.
def test_agent_checkout():
baseline = load_trace("golden.json")
candidate = run_agent(input_data)
assert_no_regressions(
compare(baseline, candidate),
max_divergence=0.25,
allow_loops=False
)Declarative Governance Policy
Commit your regression thresholds once in agentdiff.toml. Audit threshold alterations directly on PRs to prevent silent test weakening.
[assertions]
max_divergence = 0.25
max_cost_increase_pct = 5.0
allow_loops = false
max_wasted_effort = 0.10
max_recovery_step_ratio = 1.5Ready to automate on GitHub?
Add the official AgentDiff GitHub Action to your repository and receive instant diagnostic PR comments on every commit.