agentcontract

Executable spec for AI agent behavior contracts — define expected behavior in YAML and verify compliance.

Why

AI agents need more than just accuracy benchmarks. They need behavioral contracts — clear declarations of what they should and shouldn't do. agentcontract lets you write those contracts as YAML files and continuously verify that your agent's behavior stays within bounds.

This is not an eval tool. It's an executable specification for agent authorization models.

Quick Start

npm install -g agentcontract

1. Create a contract

agentcontract init --name my-agent

2. Edit the generated YAML

contract: my-agent
version: "0.1"

model:
  provider: anthropic
  id: claude-sonnet-4-20250514
  system: "You are a helpful assistant."
  temperature: 0
  max_tokens: 1024

scenarios:
  - name: "responds with citations"
    input: "List 3 recent AI papers"
    assert:
      - type: contains_pattern
        pattern: "https?://"

3. Run the contract

export ANTHROPIC_API_KEY=sk-ant-...
agentcontract run my-agent.contract.yaml

Design Principles

1. Contract-first — The YAML contract file serves as spec, test, and documentation
2. Independence — Works standalone without agentbond or trustbundle
3. Single responsibility — Define contracts, verify them, show results. Nothing else
4. Adapter pattern — LLM providers abstracted behind adapters (MVP: Anthropic only)
5. Library-friendly — CLI-first, but importable as a TypeScript library for vitest integration

Assertion Types

| Type | Description | |---|---| | contains_pattern | Output matches a regex pattern | | not_contains_pattern | Output does NOT match a regex pattern | | scope_compliant | Output stays within declared action scope (LLM-as-judge) | | json_schema | Output is valid JSON matching a JSON Schema |

Programmatic Usage

import type { Contract, RunResult } from "agentcontract";

Status

0.1.0 — MVP in development. API may change without notice.

Related Projects

| Project | Role | |---|---| | agentbond | Authorization layer — defines contract.scope | | trustbundle | Audit layer — consumes RunResult via adapters | | agent-trust-telemetry | Runtime detection — complements pre-execution verification |

Contributing

See CONTRIBUTING.md.

License

MIT