Agent Contracts

Lightweight contracts for agent task delegation.

Agent Contracts is a narrow specification and validation layer for delegated agent work. It helps teams describe what an agent is being asked to do, what inputs and outputs matter, which execution constraints apply, and when approval or handoff rules should shape the work.

This repository is intentionally not a workflow engine, orchestration framework, or full multi-agent platform. The goal of the alpha is smaller and sharper: make delegated work more explicit, more portable, and easier to validate.

Why this project exists

Agent handoffs are often underspecified. A planner asks an executor to do work, but the contract between them is implied rather than declared. That usually means:

• required inputs are missing
• expected outputs are vague
• risk handling is inconsistent
• approval posture is unclear
• delegation rules are implicit
• downstream review is harder than it should be

Agent Contracts gives that handoff a lightweight, portable shape.

Alpha scope

The current alpha includes:

• parsing of contract.yaml
• explicit JSON Schema validation
• minimum structural validation
• heuristic detection of weak delegation signals
• a local CLI with validate, lint, inspect, explain, init, and format
• JSON output mode for local tooling and CI
• an initial JSON Schema
• example contracts
• public-facing docs for vision, architecture, and roadmap

Quick start

npm install
npm run build
node dist/cli.js validate examples/research-contract
node dist/cli.js lint examples/research-contract
node dist/cli.js inspect examples/change-plan-contract
node dist/cli.js explain examples/extraction-contract
node dist/cli.js init ./contracts/new-research --template research
node dist/cli.js format ./contracts/new-research --check
npm test

During development, you can also run:

npm run dev -- validate examples/research-contract

CLI commands

validate

Checks schema compliance plus minimum validation posture. It fails when the schema is invalid or when high-severity issues are present.

agent-contracts validate ./examples/research-contract
agent-contracts validate ./examples/research-contract --json

lint

Reports every contract finding, including lower-severity authoring gaps. This is the stricter quality command and is useful in CI or review workflows.

agent-contracts lint ./examples/research-contract
agent-contracts lint ./examples/research-contract --json

Example output:

Contract: Web Research Contract (research-web-v1)
Valid: yes
Schema valid: yes
Lint clean: yes
Signal strength: strong
Issue counts: 0 high, 0 medium, 0 low

No validation issues detected.

inspect

Prints a structured view of the contract for humans reviewing the file.

agent-contracts inspect ./examples/change-plan-contract
agent-contracts inspect ./examples/change-plan-contract --json

explain

Turns the contract into a short human-oriented explanation, including key gaps if validation found any.

agent-contracts explain ./examples/extraction-contract
agent-contracts explain ./examples/extraction-contract --json

init

Creates a new contract scaffold from a small starter template.

agent-contracts init ./contracts/new-research --template research
agent-contracts init ./contracts/new-generic --template generic --json

format

Normalizes contract.yaml into a stable canonical order. Use --check to fail CI when formatting changes would be required.

agent-contracts format ./contracts/new-research
agent-contracts format ./contracts/new-research --check
agent-contracts format ./contracts/new-research --json

--json emits a versioned envelope with the stable shape:

{
  "format": "agent-contracts-cli",
  "formatVersion": 1,
  "command": "validate",
  "result": {}
}

Contract shape

The alpha contract model focuses on eleven concerns:

• identity
• intent
• inputs
• outputs
• constraints
• risk
• escalation
• approvals
• execution
• handoff
• provenance

Example:

id: research-web-v1
name: Web Research Contract
version: 0.1.0

intent:
  type: research
  description: Gather cited information on a defined topic and return a concise synthesis.

inputs:
  required:
    - research_query

outputs:
  expected:
    - structured_summary
    - citations
    - uncertainty_notes

constraints:
  max_latency_ms: 12000
  max_cost_usd: 0.25
  allow_external_web: true

risk:
  level: medium
  failure_mode: escalate_if_low_confidence

escalation:
  on_blocker: escalate_to_requester
  contact_role: requester

approvals:
  required: false

execution:
  retries: 1
  timeout_ms: 15000

handoff:
  delegation_allowed: true
  allowed_delegate_types:
    - researcher
    - analyst

provenance:
  source: human
  requested_by: requester

The schema lives at schemas/contract.schema.json.

Validation philosophy

The first validator is intentionally simple. It combines:

• explicit JSON Schema validation
• minimum required structure checks
• heuristic issue detection for weak delegation signals
• rule-based validation that is easy to extend without introducing a policy engine yet
• readable CLI output for human review

It does not yet implement advanced policy packs, trace validation, or runtime integration logic.

Repository layout

src/
  cli.ts
  explain.ts
  format.ts
  init.ts
  inspect.ts
  parser.ts
  schema-validator.ts
  types.ts
  validation-rules.ts
  validator.ts
test/
  *.test.ts
examples/
  research-contract/
  extraction-contract/
  change-plan-contract/
schemas/
  contract.schema.json
docs/
  vision.md
  architecture.md
  contract-spec.md
  roadmap.md

Non-goals

Agent Contracts is not trying to be:

• a runtime for coordinating agents
• a database-backed control plane
• a dashboard-heavy product
• a generic multi-agent framework
• a full approval workflow engine

Those may connect to Agent Contracts later. They are not the purpose of this alpha.

Documentation

• docs/vision.md
• docs/architecture.md
• docs/contract-spec.md
• docs/roadmap.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• CHANGELOG.md
• docs/release-checklist.md

License

MIT