Machine-readable, domain-independent, and framework-independent operational contracts for AI agents and automated systems.
MCP and A2A standardize how agents communicate with tools and each other. Scyvera defines the layer above: what an intelligent system can do, what resources it can access, what authority it requires, what constraints apply, what side effects it produces, and how it is governed.
Scyvera provides a machine-readable specification and Python tooling layer for defining the operational boundary of intelligent or automated systems.
It is NOT:
- another agent framework
- an LLM wrapper
- an orchestration library
- a coding-agent framework
- a security sandbox or malware scanner
It IS: A framework-independent and domain-independent specification layer describing system identity, capabilities, resources, inputs, outputs, permissions, constraints, side effects, approvals, dependencies, state persistence, failure recovery, replay semantics, observability, artifact trust declarations, and risk.
Scyvera provides two complementary governance layers:
| Layer | Component | Responsibility | Trust Level |
|---|---|---|---|
| Tier 1 & 2: Static Verification | validate_contract(), lint_contract() |
Validates that a contract.yaml is structurally and semantically well-formed against specification schemas. |
Declaration conformance |
| Runtime Enforcement | ContractEnforcer |
Gates real-world Python calls against declared permissions and side effects using Default-Deny rules. Halts execution on approval points. | Execution boundary enforcement |
Install locally or in your project virtualenv:
pip install scyvera
# Or for local development:
pip install -e .scyvera init contract.yaml --name "Research Assistant"Interactive wizard mode:
scyvera init contract.yaml -iThe CLI automatically detects the specification version (1 vs 1.1) and validates against the corresponding JSON Schema:
scyvera validate contract.yamlOutput:
PASS contract.yaml
Override with a custom JSON Schema file:
scyvera validate contract.yaml --schema path/to/custom.schema.jsonThe ContractEnforcer protects your agent's execution boundaries in Python by enforcing Default-Deny: any undeclared permission or side effect raises ContractViolationError, and any action listed in approval_points raises ApprovalPendingError.
from pathlib import Path
from scyvera import ContractEnforcer, ContractViolationError, ApprovalPendingError
# 1. Load, validate, and freeze the contract
enforcer = ContractEnforcer.load("implementations/n8n/duplicate-issue-detector/contract.yaml")
# 2. Gate sensitive tools and operations
@enforcer.gate(action_name="github: issues:write", action_type="permission")
def post_github_comment(issue_id: int, comment: str):
print(f"Posting comment to issue #{issue_id}: {comment}")
return True
@enforcer.gate(action_name="aws_s3:read", action_type="permission")
def read_s3_bucket():
return "s3_data"
# 3. Allowed calls execute cleanly and log to audit trail
post_github_comment(101, "Potential duplicate detected.")
# 4. Undeclared actions are denied immediately (Default-Deny)
try:
read_s3_bucket()
except ContractViolationError as e:
print(f"Blocked by Scyvera: {e}")
# 5. Inspect the immutable audit log
for entry in enforcer.get_audit_log():
print(f"[{entry.timestamp}] {entry.decision} - {entry.action_name} ({entry.reason})")
# 6. Verify file integrity on disk (Threat T5 defense)
enforcer.verify_integrity() # Raises ContractTamperError if contract.yaml was modifiedScyvera provides structural verification and runtime gating, but security is an end-to-end discipline. Integrators must understand the following technical boundaries:
- Gate Bypass (Threat T4): Scyvera enforces boundaries at the
@enforcer.gate(...)decorator. In Python, the runtime cannot physically prevent code from directly calling an un-decorated internal function. Integrators should useContractEnforcer.assert_gated(fn)within their integration test suites to verify that all external-facing tool call sites are wrapped. - Internal Third-Party Behavior / String Spoofing (Threat T6): Scyvera verifies that a declared intent (e.g.
github:issues:write) matches an allowed permission in the contract. It does not perform dynamic bytecode analysis or network-packet inspection to guarantee that a decorated library function does not execute unauthorized background calls. The integrity of third-party dependencies remains the responsibility of dependency scanning and peer review. - Pre-Load File Tampering (Threat T5): The SHA-256 integrity check in
verify_integrity()protects against file replacement AFTER load. It does not protect against a tamperedcontract.yamlbeing present BEFOREContractEnforcer.load()is called. The deployment environment is responsible for protecting the contract file prior to load.
You can programmatically construct, inspect, serialize, and validate Agent Contracts in Python without manually writing YAML:
from scyvera import Contract, validate_contract
# Programmatically construct a v1.1 Contract
contract = (
Contract(name="Literature Research Assistant", purpose="Analyzes scientific papers")
.set_domain("research")
.add_capability("search_documents", description="Queries research repositories")
.add_resource("paper_db", type="pdf_repository", access="read")
.add_input("research_topic", type="string", required=True)
.add_output("summary", type="document")
.add_permission("paper_db", actions=["read", "search"])
.set_state("session")
.set_recovery("retry")
.set_replay("idempotent")
.set_observability("basic")
.set_risk("low", category="misinformation_risk")
)
# Validate directly in code
result = contract.validate()
if result.valid:
print("Contract is valid!")
# Save to file
contract.save("contract.yaml")
else:
for err in result.errors:
print(f"Error at {err.path}: {err.message}")Validate an existing YAML file programmatically:
from scyvera import validate_contract
result = validate_contract("contract.yaml")
print(f"Valid: {result.valid}")Instead of prose documentation alone, systems in this repository specify:
- Identity & Purpose — system identity, operational scope, and system version
- Capabilities — semantic ability claims
- Resources — data stores, APIs, entities, or systems accessed
- Inputs & Outputs — data entering and produced by the system
- Permissions — exact authorized
{resource, actions[]}combinations - Constraints — quantitative limits (e.g. rate limits, transaction caps)
- Side Effects — externally observable mutations
- Approvals — explicit human or expert approval gates
- Dependencies — required external services, models, APIs
- State, Recovery, Replay, Observability — persistence, failure strategy, idempotency, and audit evidence
- Artifact Security & Risk — model/data artifact trust requirements and risk level classification
agent-contracts/
├── README.md
├── WORKFLOW-CONTRACT-SPEC.md
├── CONTRIBUTING.md
├── CONTRIBUTORS.md
├── LICENSE
├── pyproject.toml
├── docs/
│ ├── contract-model-v1.1.md # Normative v1.1 Specification
│ ├── vision.md # Strategic Project Vision
│ ├── design-principles.md # Normative Design Principles
│ └── terminology.md # Specification Terminology
├── schemas/
│ ├── v1/ # Contract v1 JSON Schema
│ │ └── contract.schema.json
│ └── v1.1/ # Contract v1.1 JSON Schema
│ └── contract.schema.json
├── examples/
│ └── v1.1/ # Domain-Neutral Examples (v1.1)
│ ├── education-tutor.yaml
│ ├── research-assistant.yaml
│ ├── financial-operations.yaml
│ └── clinical-information-assistant.yaml
├── src/
│ └── scyvera/ # Python Package
│ ├── __init__.py
│ ├── builder.py # Programmatic Contract Builder API
│ ├── validator.py # Multi-Version Validator Engine
│ ├── cli.py # CLI Application (validate, init)
│ └── schemas/ # Bundled Package Schemas
├── tests/
│ ├── fixtures/ # Test Fixture Files
│ ├── test_validator.py # v1 Validator Unit Tests
│ ├── test_validator_v1_1.py # v1.1 Validator Unit Tests
│ ├── test_builder.py # Programmatic Builder Unit Tests
│ └── test_cli.py # CLI Unit Tests
└── implementations/ # Multi-Framework Reference Implementations
├── n8n/
└── langgraph/
See examples/v1.1/ for runnable, validated v1.1 contracts across different domains:
| Domain | Contract File | Description |
|---|---|---|
| Education | education-tutor.yaml |
Guided study tutor, low risk, session state |
| Research | research-assistant.yaml |
Scientific literature analysis, arXiv API dependency |
| Finance | financial-operations.yaml |
Critical risk, payment caps ($5000 USD limit), controller approval gate |
| Healthcare | clinical-information-assistant.yaml |
High risk, EHR database access, physician approval gate, model integrity requirements |
Important
Contract Declaration ≠ Security Verification ≠ Runtime Enforcement. An Agent Contract describes declared operational boundaries. It is not a sandbox, anti-malware scanner, or runtime enforcement proxy. Contract declarations provide structured input upon which external policy engines, verification scanners, and runtime isolation systems operate.
Contract v1 was designed and proven against coding/developer agents. That's now understood to be a starting substrate, not the ceiling — v1.1 is a deliberate audit-and-redesign effort to make the spec:
- Domain-independent — usable for research, education, finance, business-workflow, and healthcare-workflow agents, not just coding agents
- Framework-independent — already true in principle (n8n + LangGraph prove it), being stress-tested further
- Accessible to non-technical authors — YAML/JSON is a representation format, not meant to be the only way to create a contract
This is genuinely in the design/audit phase — classifying existing Contract v1 fields, testing them against non-coding agent archetypes, and only then extending the schema. Nothing in this section describes a shipped feature. Follow progress in implementations/rfcs/ and open issues tagged v1.1.
Contributions are welcome — new domain profiles, framework reference implementations, specification RFCs, or Python API improvements. See CONTRIBUTING.md for details.
Distributed under the MIT License — see LICENSE for details.
Built and maintained by Shinjan Das and open-source contributors — see CONTRIBUTORS.md.