Status: Draft Specification: Agent Contracts v1.1
These principles define the architectural and specification-level rules that guide the evolution of Agent Contracts.
They provide a consistent basis for deciding:
- what belongs in the core specification,
- what should be represented as an extension,
- what belongs in tooling rather than the specification,
- what should remain outside the scope of Agent Contracts,
- and how the specification should evolve over time.
A proposed feature SHOULD be evaluated against these principles before being incorporated into the core specification.
These principles govern the design of the specification itself. They do not prescribe how an individual autonomous system must be implemented or operated.
Agent Contracts MUST describe the operational characteristics of an autonomous system independently of its implementation.
A contract MUST NOT require a particular:
- programming language,
- AI model,
- orchestration framework,
- workflow engine,
- runtime,
- cloud provider,
- deployment platform,
- or vendor.
The same operational concept SHOULD be representable regardless of how the underlying autonomous system is implemented.
Implementation-specific information MAY be represented through extensions when necessary, but such information MUST NOT become a requirement of the core specification.
The core specification MUST NOT assume that autonomous systems belong to a particular industry, profession, or use case.
Agent Contracts MUST be capable of representing autonomous systems used in domains including, but not limited to:
- software engineering,
- education,
- scientific research,
- finance,
- healthcare,
- enterprise operations,
- customer support,
- data analysis,
- automation,
- robotics,
- and future domains that may emerge as autonomous systems evolve.
Domain-specific requirements SHOULD be represented through extensions rather than by continuously expanding the core specification.
The core model SHOULD describe concepts at a level of abstraction that remains meaningful across domains.
The core specification SHOULD contain only concepts that are broadly applicable across autonomous systems.
A concept SHOULD be considered for inclusion in the core when its meaning remains useful across multiple domains and implementations.
Domain-specific, vendor-specific, framework-specific, or highly specialized concepts SHOULD NOT be added to the core merely because they are useful in a single environment.
When a requirement can be addressed through an existing concept, an extension, a policy layer, tooling, or an external integration without reducing interoperability or expressiveness, that approach SHOULD be preferred over expanding the core.
The core specification SHOULD evolve deliberately and remain sufficiently stable that implementations and contracts can depend on it over time.
Breaking changes SHOULD be minimized and accompanied by explicit migration guidance.
An Agent Contract SHOULD make the important operational boundaries of an autonomous system explicit.
Where applicable, a contract SHOULD be able to represent concepts such as:
- capabilities,
- resources,
- permitted actions,
- constraints,
- permissions,
- external side effects,
- approval requirements,
- dependencies,
- persistent state,
- recovery behavior,
- replay or idempotency characteristics,
- and observability requirements.
The specification SHOULD prioritize information that helps a stakeholder understand what an autonomous system is declared to be able, required, or permitted to do.
Operational descriptions SHOULD distinguish between capabilities, constraints, and observations where those distinctions are relevant.
Agent Contracts are declarative specifications.
A contract describes the declared operational characteristics and boundaries of an autonomous system. It does not itself become the implementation of that system.
A contract MUST NOT require the embedding of executable agent logic, reasoning procedures, or implementation code as part of the core specification.
The core specification MUST NOT depend on exposing private reasoning processes or chain-of-thought.
Prompts, model configurations, implementation details, and execution logic MAY exist alongside a contract, but they are not inherently part of the core contract model.
Execution remains the responsibility of the underlying system.
Agent Contracts SHOULD be understandable by both humans and software.
A contract SHOULD provide sufficient structure for automated processing while remaining understandable to people who need to review, operate, audit, or govern the system.
The ecosystem SHOULD support multiple levels of interaction, including:
- direct authoring for technical users,
- graphical or guided authoring for non-technical users,
- automated generation,
- validation,
- documentation generation,
- and programmatic consumption.
Higher-level interfaces MAY abstract away the underlying representation, but they MUST preserve the semantics of the underlying contract model.
The underlying specification remains machine-readable even when users interact with it through higher-level tools.
An Agent Contract represents declared operational properties. A valid contract does not, by itself, prove that the underlying implementation behaves according to those declarations.
Structural validation determines whether a contract conforms to the applicable specification.
Policy validation may determine whether declared properties satisfy defined governance or organizational rules.
Neither necessarily proves that the implementation behaves exactly as declared.
Where practical, governance-relevant claims SHOULD be capable of being associated with supporting evidence.
Evidence MAY include:
- validation results,
- test results,
- provenance information,
- attestations,
- audit records,
- runtime observations,
- or other verification artifacts.
The ecosystem SHOULD preserve a distinction between:
- declared behavior,
- verified behavior,
- and observed behavior.
This distinction enables future systems to identify differences between what an autonomous system declares it can or will do and what it has been verified or observed to do.
The existence of a declaration alone MUST NOT be treated as evidence that the declaration is true.
Agent Contracts itself MUST NOT be represented as a guarantee that an autonomous system is safe, secure, trustworthy, or compliant.
Security-relevant operational properties SHOULD be representable explicitly where they are applicable to the autonomous system.
The specification SHOULD make it possible for governance and security tooling to reason about concepts such as:
- capabilities,
- permissions,
- resources,
- trust boundaries,
- external dependencies,
- sensitive operations,
- human approvals,
- side effects,
- and operational constraints.
The Agent Contracts specification does not attempt to solve every security problem.
Instead, it provides structured operational information that other security, governance, and policy systems can consume.
A contract declaration SHOULD NOT be interpreted as evidence that the underlying implementation is secure.
Security enforcement MAY be performed by external systems that consume the contract.
The specification, its tooling, and its enforcement mechanisms are distinct layers.
The specification defines the language and semantics of a contract.
Tooling provides mechanisms for:
- authoring,
- validation,
- analysis,
- visualization,
- conversion,
- and integration.
Enforcement systems may consume contracts to control, restrict, monitor, or audit autonomous systems.
A capability implemented by a tool or runtime MUST NOT automatically become part of the core specification.
Similarly, a feature of the reference implementation MUST NOT be interpreted as a requirement of the specification unless explicitly defined by the specification.
This separation allows multiple independent implementations and tools to consume the same contract model.
Agent Contracts MUST provide a mechanism through which specialized requirements can be represented without modifying the core specification for every new domain or organizational requirement.
Extensions MAY represent:
- industry-specific requirements,
- organizational policies,
- framework-specific metadata,
- vendor integrations,
- domain-specific capabilities,
- regulatory mappings,
- or experimental concepts.
Governance policies SHOULD remain separate from the underlying operational description.
Different organizations MAY apply different policies to the same contract without changing the semantic meaning of the contract itself.
Extensions SHOULD identify their:
- scope,
- ownership,
- version,
- and compatibility requirements.
Extensions MUST NOT redefine the meaning of existing core concepts in ways that create ambiguity or incompatibility.
A domain-specific extension SHOULD add semantics rather than silently changing the meaning of the core specification.
A contract SHOULD be portable across implementations whenever the underlying systems support the concepts represented by that contract.
The specification SHOULD avoid unnecessary coupling between contracts and the tools that create or consume them.
Different implementations MAY provide different levels of feature support.
Unsupported optional capabilities SHOULD be distinguishable from invalid contracts.
An implementation that does not support an optional extension SHOULD NOT be required to reject an otherwise valid core contract solely because the extension is unfamiliar, unless the applicable specification explicitly requires such behavior.
Interoperability SHOULD be treated as a primary design objective rather than an afterthought.
Core fields SHOULD have precise and stable meanings.
A field SHOULD NOT depend primarily on ambiguous natural-language interpretation when its meaning can be represented structurally.
Where free-form descriptions are necessary, they SHOULD complement structured semantics rather than replace them.
This principle is particularly important for properties related to:
- permissions,
- capabilities,
- side effects,
- approvals,
- dependencies,
- state,
- recovery,
- and governance.
Where a field affects automated policy decisions, its semantics SHOULD be sufficiently precise that independent implementations can reach consistent conclusions.
Human-readable descriptions MAY provide additional context but SHOULD NOT silently override structured semantics.
Where a contract omits information that may be significant to governance or risk analysis, consumers SHOULD be able to distinguish between:
- explicitly declared behavior,
- explicitly restricted behavior,
- unspecified behavior,
- and unsupported behavior.
The specification SHOULD avoid silently interpreting missing information as permission, safety, trust, or compliance.
Absence of a declaration MUST NOT automatically be interpreted as authorization to perform an action unless the applicable specification or policy explicitly defines that behavior.
Specific default semantics MUST be defined by the relevant specification version or policy rather than being inferred inconsistently by individual implementations.
The specification MUST support explicit versioning.
Changes to the specification SHOULD be classified according to their compatibility impact.
Where practical:
- existing valid contracts SHOULD remain valid across compatible revisions,
- breaking changes SHOULD require a new specification version,
- deprecated concepts SHOULD have a documented migration path,
- and consumers SHOULD be able to determine which specification version a contract targets.
Versioning applies to both the core specification and independently versioned extensions.
Changes to the reference implementation SHOULD NOT automatically constitute specification changes.
Agent Contracts SHOULD describe operational properties without assigning inherent trust, safety, legality, or appropriateness to those properties.
A contract describes what an autonomous system declares, requires, permits, or expects.
Whether those properties are acceptable MUST remain the responsibility of the applicable policy, governance, security, regulatory, or compliance system.
For example, a declared capability is not inherently safe or unsafe merely because it appears in a valid contract.
The same contract SHOULD therefore be usable by different organizations with different governance requirements without changing the meaning of the underlying operational description.
Semantic neutrality is necessary for Agent Contracts to function as a general-purpose operational specification rather than as a universal policy framework.
A proposed feature SHOULD be evaluated using the following sequence before being added to the core specification:
- Is the concept relevant to autonomous systems generally?
- Is it independent of a particular framework, vendor, or implementation?
- Is it applicable across multiple domains?
- Does it describe operational behavior rather than implementation detail?
- Can it be defined with sufficiently precise semantics?
- Does it belong in the specification rather than tooling or enforcement?
- Can the requirement be satisfied through an existing concept?
- Can the requirement be satisfied through an extension instead?
- Would adding it improve interoperability rather than reduce it?
- Can the concept evolve without unnecessary breaking changes?
- Does the benefit justify increasing the complexity of the core specification?
- Does the feature preserve the semantic neutrality of the core specification?
A feature that cannot satisfy these criteria SHOULD NOT automatically be added to the core.
When uncertainty exists, the project SHOULD prefer experimentation through tooling or extensions before committing a concept to the core specification.
The strongest version of Agent Contracts is not the one with the largest number of fields.
The core specification SHOULD remain intentionally limited to concepts that provide durable value across autonomous systems.
The project SHOULD prefer a small number of composable, well-defined concepts over a large collection of specialized fields.
When a requirement can be solved outside the core without reducing interoperability or expressiveness, the simpler solution SHOULD be preferred.
The objective is to build a stable foundation on which a broader ecosystem can evolve rather than attempting to place the entire autonomous-system ecosystem inside a single specification.