A formal framework for governing autonomous AI agents through explicit resource constraints and temporal boundaries.
Agent Contracts turn autonomous agents from unbounded explorers into bounded optimizers: declare a budget, and the framework tracks consumption as the agent runs, enforces the limit, and leaves an audit trail. It wraps six agent frameworks without changing how you write agents.
pip install ai-agent-contracts- Why
- Quick start
- Integrations
- Key concepts
- Feature guide
- Research: the causal-chamber pillar
- Documentation
- Installation
- Development
- Project structure
- Status
- Contributing
Agentic systems fail in ways ordinary software does not:
| Problem | What a contract adds |
|---|---|
| Unbounded consumption — an agent can burn unpredictable tokens, calls and time | An explicit budget, enforced during execution rather than reported after |
| Unclear lifecycles — no explicit termination criterion | Machine-verifiable states from activation to fulfilment |
| Hard governance — difficult to audit, attribute cost, or prove compliance | An event stream and audit trail per contract |
| Multi-agent coordination — no formal allocation between agents | Hierarchical delegation and DAG flow conservation, with a provable global bound |
A contract is C = (I, O, S, R, T, Φ, Ψ) — inputs, outputs, state, resources,
time, preconditions, postconditions. The whitepaper has
the formal treatment.
from agent_contracts import Contract, ContractedLLM, ContractMode, ResourceConstraints
contract = Contract(
id="research-task",
name="Research Assistant",
mode=ContractMode.BALANCED, # quality-cost-time balance
resources=ResourceConstraints(
tokens=10_000,
api_calls=50,
cost_usd=1.0,
),
)
with ContractedLLM(contract) as llm:
response = llm.completion(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Summarize recent AI papers"}],
)
usage = llm.get_usage_summary()["usage"]
print(f"{usage['tokens']} tokens · ${usage['cost_usd']:.4f}")Token budgets, call counts and cost are tracked as the agent runs; crossing a limit raises or warns depending on whether you run strict or lenient.
Six integrations share one contract object. The value scales with how many calls a framework can make on your behalf.
| Integration | Calls per run | Budget risk | What the contract buys |
|---|---|---|---|
| LiteLLM | 1 per call | Low | Universal baseline — 100+ providers, token counting, cost |
| LangChain | 3–10 | Low–moderate | Multi-call protection, audit trail, policy compliance |
| LangGraph ⭐ | 30+ (cycles, retries, parallel agents) | Very high | Loop protection, multi-agent budget sharing, cumulative tracking across every node |
| Claude Agent SDK | 10–100+ tool calls | High | Per-tool limits and temporal enforcement via PreToolUse hooks; audit via PostToolUse |
| Google ADK | 10–50+ | High | Multi-turn protection, hierarchical governance, prompt/response/thinking/cached token split |
| Causal Chambers | research harness | — | Budget-matched agent experiments on a physical testbed |
LangGraph is where the framework earns its keep. A graph with a validation cycle can spiral past $10 unbounded; the contract enforces one budget across every node and every iteration.
LangGraph — one budget across a whole graph, cycles included
from langgraph.graph import END, StateGraph
from agent_contracts import Contract, ResourceConstraints
from agent_contracts.integrations import ContractedGraph
graph = StateGraph(AgentState)
graph.add_node("researcher", research_node)
graph.add_node("validator", validate_node)
graph.add_conditional_edges(
"validator", should_retry, {"retry": "researcher", "done": END}
)
contract = Contract(
id="research-workflow",
name="Research Workflow",
resources=ResourceConstraints(tokens=50_000, api_calls=20),
)
contracted = ContractedGraph(contract, graph.compile())
result = contracted.invoke({"query": "..."})
print(contracted.get_remaining_budget())The budget is cumulative across all nodes and cycles, so a retry loop that never terminates hits the contract instead of your bill.
Google ADK — one budget for a multi-agent hierarchy
from google.adk.agents import Agent
from agent_contracts import Contract, ResourceConstraints
from agent_contracts.integrations import ContractedAdkAgent
coordinator = Agent(
name="coordinator",
model="gemini-2.0-flash",
sub_agents=[researcher, analyst],
)
contract = Contract(
id="multi-agent-research",
name="Multi-Agent Research",
resources=ResourceConstraints(tokens=30_000, api_calls=15),
)
contracted = ContractedAdkAgent(contract, coordinator)
result = contracted.run(
user_id="u1", session_id="s1", message="Analyze the EV market"
)Token tracking is broken out by prompt, response, thinking and cached.
An Agent Contract C = (I, O, S, R, T, Φ, Ψ):
| Symbol | Field | Meaning |
|---|---|---|
| I | inputs |
Input specification |
| O | outputs |
Output specification |
| S | state |
Current lifecycle state |
| R | resources |
Resource constraints — tokens, calls, cost, tools, memory |
| T | temporal |
Deadlines and duration limits |
| Φ | success_criteria |
Preconditions and success conditions |
| Ψ | termination_conditions |
Postconditions and termination rules |
DRAFT → ACTIVE → {FULFILLED, VIOLATED, EXPIRED, TERMINATED}
Contract modes let you trade quality, cost and time explicitly rather than implicitly. Validated on an N=20 benchmark — no mode dominates another, so the three sit on a Pareto frontier:
| Mode | Quality | Effect |
|---|---|---|
URGENT |
87% | ~50% faster, ~20% more tokens |
BALANCED |
85% | Balanced resources |
ECONOMICAL |
81% | ~32% fewer tokens, longer runtime |
from agent_contracts import Contract, ContractMode, ResourceConstraints
contract = Contract(
id="urgent-task",
name="Urgent Task",
mode=ContractMode.URGENT,
resources=ResourceConstraints(tokens=10_000),
)Per-tool resource limits
Per-tool limits are checked before the aggregate limit. An omitted key means
unconstrained, not zero — grant an explicit 0 when you mean zero.
from agent_contracts import Contract, ResourceConstraints
contract = Contract(
id="research-agent",
name="Research Agent",
resources=ResourceConstraints(
tokens=10_000,
tool_invocations=20, # aggregate limit across all tools
per_tool_limits={
"web_search": 5,
"code_exec": 3,
# tools not listed are bounded only by the aggregate
},
),
)Delegation graphs (multi-parent budgets)
When one agent is funded by several others — an aggregator merging two workers,
a shared reviewer — a strict hierarchy cannot express it without
double-counting. DelegationGraph models delegation as a DAG where budget
flows along edges:
from agent_contracts import Contract, ResourceConstraints
from agent_contracts.core import DelegationGraph
root = Contract(
id="research",
name="Research",
resources=ResourceConstraints(tokens=100_000, per_tool_limits={"web_search": 20}),
)
graph = DelegationGraph(root)
for name in ("scout_a", "scout_b", "aggregator"):
graph.add_node(name)
graph.allocate("root", "scout_a", tokens=40_000, per_tool={"web_search": 10})
graph.allocate("root", "scout_b", tokens=40_000, per_tool={"web_search": 10})
graph.allocate("scout_a", "aggregator", tokens=15_000, per_tool={"web_search": 0})
graph.allocate("scout_b", "aggregator", tokens=15_000, per_tool={"web_search": 0})
graph.seal() # validate the whole graph, then freeze its topology
graph.contract_for("aggregator").resources.tokens # 30_000 — the sum of its in-edges
graph.verify() # raises if any node breaks the invariantThe invariant at every node is in-flow ≥ own consumption + out-flow. Because
that is a purely local check, and internal allocations cancel when summed
across the graph, satisfying it everywhere guarantees total consumption never
exceeds the root budget — with no global lock and no central accountant.
See whitepaper §4.6 for the proof and its scope.
Two semantics worth knowing: control flow may cycle but budget flow must not (a cycle would let a node refund its own ancestor), and refunds are computed against original allocations rather than live ones, which is what makes releasing sibling edges order-independent.
Pre-execution hooks (custom policy)
Custom governance logic that runs before every constraint check, on all integrations:
from agent_contracts import (
CheckContext,
Contract,
ContractedLLM,
EnforcementAction,
HookResult,
ResourceConstraints,
)
def topic_guard(ctx: CheckContext) -> HookResult:
messages = ctx.metadata.get("messages", [])
if any("off-topic" in str(m) for m in messages):
return HookResult(
allow=False,
reason="Request outside allowed domain",
action=EnforcementAction.HARD_STOP,
)
return HookResult() # allow by default
contract = Contract(
id="guarded-agent",
name="Guarded Agent",
resources=ResourceConstraints(tokens=10_000, cost_usd=1.0),
)
with ContractedLLM(contract) as llm:
llm.enforcer.add_pre_check_hook(topic_guard)WARN and THROTTLE are informational; SOFT_STOP and HARD_STOP block.
Post-check hooks are observational and cannot block. See
docs/pre-execution-hooks.md.
Agent skills (agentskills.io standard)
from agent_contracts import Capabilities, Contract, SkillSpec
code_review = SkillSpec(
name="code-reviewer",
description="Review code for best practices, security issues, and test coverage.",
instructions="""
## Instructions
1. Read the target files
2. Check error handling, security, and test coverage
3. Provide detailed feedback
""",
allowed_tools=["Read", "Grep", "Glob"],
version="1.0.0",
)
contract = Contract(
id="review-task",
name="Code Review",
capabilities=Capabilities(
skills=[code_review, "simple-skill"], # SkillSpec and plain strings both work
tools=["web_search"],
),
)
skill = contract.capabilities.get_skill("code-reviewer")SKILL.md import/export via to_skill_md() / from_skill_md(), progressive
disclosure (metadata ≈ 100 tokens, instructions loaded on activation), and
backward compatibility with plain string skills.
Beyond the library, this repository hosts an empirical research pillar that uses contracts as a measurement instrument. Because budgets can be split across agents and verified, agent topologies can be compared at exactly matched spend — which is what makes the comparison meaningful.
The M6 experiment runs a five-rung coordination ladder (single loop, ensemble, parallel roles, relay, negotiating team) on two Causal Chambers — physical devices whose true causal graph is known by construction, so a recovered graph can be graded objectively rather than by an LLM judge.
2,221 cells, $94.05, zero errored cells, two chambers, two models. Of 24 topology-vs-loop contrasts, 10 resolve and 9 favour a single sequential loop.
docs/chamber-results.md— every experiment and what it showeddocs/chamber-harness-validity-register.md— 19 harness defects that each changed, or could have changed, a number. Read this before trusting any figure; six of them looked like findings first.docs/causal_chamber_validation_plan.md— the full experiment plan
The harness lives in evaluation/chamber_pipeline/
and needs the chambers extra.
📚 Complete documentation index
| Document | What it covers |
|---|---|
| Whitepaper | Formal framework, the conservation proof, use cases |
| Pre-execution hooks | Custom governance hooks and monitor design |
| Testing strategy | Test plan and validation approach |
| Chamber results | Empirical results of record |
| Validity register | Every harness defect found, and its effect |
| Quality measurement | LLM-as-judge under rating indeterminacy |
By role: researchers start with the formal framework; engineers with implementation architecture; product managers with the introduction.
pip install ai-agent-contracts # or: uv add ai-agent-contractsThe package imports as agent_contracts:
from agent_contracts import Contract, ResourceConstraintsRequirements: Python ≥ 3.12.
Optional extras — install only what you use:
| Extra | Install | For |
|---|---|---|
litellm |
uv sync --extra litellm |
100+ LLM providers |
langchain |
uv sync --extra langchain |
LangChain chains |
langgraph ⭐ |
uv sync --extra langgraph |
LangGraph graphs |
google-adk |
uv sync --extra google-adk |
Google ADK agents |
claude-agent-sdk |
uv sync --extra claude-agent-sdk |
Claude Agent SDK |
chambers |
uv sync --extra chambers |
Causal-chamber research harness |
eval |
uv sync --extra eval |
Benchmark datasets and plots |
# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/flyersworder/agent-contracts.git
cd agent-contracts
uv sync --dev # or --all-extras for every integration
uv run pre-commit installuv run pytest # run the suite
uv run pytest --cov=agent_contracts --cov-report=html # with coverage
uv run pre-commit run --all-files # all checks
uv run ruff check . # lint
uv run ruff format . # format
uv run mypy . # type checkQuality gates: Ruff (lint + format), mypy in strict mode, and pre-commit hooks that run on every commit. CI must be green on Python 3.12 and 3.13 before merge.
agent-contracts/
├── src/agent_contracts/
│ ├── core/
│ │ ├── contract.py # Contract, ResourceConstraints, Capabilities
│ │ ├── monitor.py # Real-time resource tracking
│ │ ├── enforcement.py # Constraint enforcement and hooks
│ │ ├── delegation.py # Hierarchical delegation (tree)
│ │ ├── delegation_graph.py # DAG delegation with flow conservation
│ │ ├── resource_vector.py # Resource algebra
│ │ ├── skillspec.py # agentskills.io SkillSpec
│ │ ├── tokens.py # Token counting and cost
│ │ ├── planning.py # Strategic planning
│ │ ├── executor.py # Contract execution
│ │ └── prompts.py # Budget-aware prompts
│ └── integrations/
│ ├── litellm_wrapper.py # LiteLLM
│ ├── langchain.py # LangChain
│ ├── langgraph.py # LangGraph ⭐
│ ├── google_adk.py # Google ADK
│ ├── claude_agent_sdk.py # Claude Agent SDK
│ └── causalchamber.py # Causal Chambers (research)
├── tests/ # 1,507 tests
├── benchmarks/ # Live demos: governance, strategic, per-framework
├── evaluation/ # Experiments
│ ├── chamber_pipeline/ # Causal-chamber coordination ladder
│ ├── research_pipeline/ # Multi-agent research
│ └── code_review_pipeline/ # Coder ↔ Reviewer loop
└── docs/ # Whitepaper, results, validity register
v0.5.0 — production ready. 1,507 tests, 1 skipped, 91% coverage,
mypy --strict clean, CI green on Python 3.12 and 3.13.
| Area | State |
|---|---|
| Core framework — contracts, monitoring, enforcement, tokens | ✅ |
| Integrations — LiteLLM, LangChain, LangGraph, Google ADK, Claude Agent SDK | ✅ |
| Contract modes and strategic planning | ✅ Validated at N=20 |
| Per-tool limits and SkillSpec (agentskills.io) | ✅ |
| Pre-execution hooks (custom policy) | ✅ All integrations |
| Delegation: hierarchical tree and DAG flow conservation | ✅ v0.4.0 |
| Evaluation pipelines — research, code review | ✅ |
| Causal-chamber research pillar | ✅ M6 complete, M7 planned |
| AutoGen / CrewAI integrations | 🔜 Planned |
| Audit dashboards and cost-attribution reporting | 🔜 Planned |
Known limitation: ResourceConstraints.iterations is honoured only by
Google ADK (max_llm_calls) and the Claude Agent SDK (max_turns). LiteLLM,
LangChain and LangGraph neither track nor enforce it.
Contributions welcome — reference implementations, new framework integrations, practical examples, and empirical studies. Please open an issue to discuss substantial changes first.
Apache License 2.0 — see LICENSE.
Qing Ye (with assistance from Claude, Anthropic).
@techreport{ye2025agentcontracts,
title={Agent Contracts: A Resource-Bounded Optimization Framework
for Autonomous AI Systems},
author={Ye, Qing},
year={2025},
month={October}
}v0.5.0 · Last updated 30 August 2026