**Agent Capability Contract (ACC)** is an open declaration contract for exposing business capabilities to agents.
ACC defines how a business system describes which operations an agent may see, when those operations should be considered risky, when a human approval intent is required, how an acting subject is required, and what metadata a runtime should preserve for audit and traceability.
ACC is not a runtime, a chatbot framework, or a workflow engine. It is a portable contract that can be implemented by different control planes, gateways, SDKs, developer tools, and agent runtimes.
ACC is maintained as an independent, implementation-neutral standard. No product implementation defines ACC semantics or receives privileged compatibility status.
ACC is the capability contract for **A2B (Agent-to-Business)**: agents safely doing business work through existing systems.
The governance questions ACC addresses can recur whenever an agent action crosses an effect, authority, or trust boundary. This is a broader research observation, not a claim that ACC v1 already governs every agent action. See [Concepts](CONCEPTS.md) for the distinction between recurring questions and the current normative scope.
ACC deliberately keeps a small normative core. See [Design Rationale And Boundaries](DESIGN_RATIONALE.md) for the concerns ACC knows about but intentionally leaves to business authorization, runtime policy, approval systems, compliance policy, or other contracts.
For an implementation-neutral map of adjacent protocols, runtime controls, policy systems, and workflow layers, see [ACC in the Agent Governance Landscape](LANDSCAPE.md).
| Dimension | Current state |
|---|---|
| Specification | Stable ACC v1 core, governed by Semantic Versioning |
| Ecosystem | Early adoption; independent implementations are welcome |
| Conformance | Profiles, self-assessment, and machine-readable v1 reference vectors |
## Why ACC Exists
Existing business systems were not designed for A2B. Once an agent can call business APIs, teams need a standard way to answer:
- Which operations may be exposed to an agent?
- Which route, product surface, or scenario may use a capability?
- Does the operation require a real business subject?
- Is the operation readonly, low risk, medium risk, or high risk?
- Should specific arguments trigger a human approval intent?
- Which fields are sensitive and should be redacted from audit logs?
- How should runtime gateways preserve extension metadata without making it a security rule?
ACC puts these declarations next to the API contract, while keeping the final authorization decision inside the business system.
```text
ACC controls reach.
The business system controls authority.
```
## Five-Minute Start
Already have an OpenAPI document? Follow [Add ACC to an Existing OpenAPI
Service in Five Minutes](QUICKSTART.md) to add one declaration, validate it with
the `acc-validate` authoring tool, and then expand to the included
[multi-operation order service](examples/openapi-order-service.yaml).
Run the published validator without installing it globally:
```bash
npx --yes agent-capability-contract@1.0.5 validate ./openapi.yaml
```
The validator is a non-normative authoring aid. It does not replace the ACC
specification, a complete OpenAPI linter, business authorization, or runtime
conformance testing.
## OpenAPI Binding
OpenAPI is the first standardized ACC binding. It carries the ACC Core declaration in the operation-level `x-agent-capability` extension:
```yaml
x-agent-capability:
version: 1
enabled: true
scope: order.read
risk:
level: low
subject:
required: true
execution:
readonly: true
```
See [SPEC.md](SPEC.md) for the normative core field model, [Binding Requirements](bindings/README.md) for the interface every binding must define, and [OpenAPI Binding](bindings/openapi.md) for the first carrier-specific mapping.
ACC v1 declarations use `version: 1`. Exact specification revisions use repository tags such as `v1.0.5`; product or runtime versions are separate.
## Implement ACC
- Read the non-normative [Implementer's Guide](IMPLEMENTER_GUIDE.md).
- Review [Safety Governance Responsibilities](SAFETY_GOVERNANCE_GUIDE.md) for trust boundaries, business examples, and the evidence each layer needs.
- Choose a claim from [Conformance Profiles](conformance/PROFILES.md).
- Run the applicable [machine-readable ACC v1 vectors](conformance/v1/README.md).
- Publish evidence using [Implementation Registration and Self-Assessment](conformance/SELF_ASSESSMENT.md).
- Submit a pull request to the neutral [implementation registry](IMPLEMENTATIONS.md).
## Repository Layout
```text
SPEC.md Normative ACC v1 specification
CONCEPTS.md A2B and ACC terminology
CONCEPTS.zh-CN.md Chinese translation of core concepts and scope boundaries
bindings/README.md Common requirements for ACC bindings
bindings/openapi.md OpenAPI extension binding
schemas/acc.v1.schema.json Machine-readable JSON Schema
QUICKSTART.md Five-minute OpenAPI authoring guide
QUICKSTART.zh-CN.md Chinese five-minute authoring guide
bin/acc-validate.mjs ACC OpenAPI authoring validator CLI
lib/openapi-validator.mjs Validator library and diagnostics
examples/ OpenAPI examples, including a multi-operation service
test/ Authoring validator and CLI tests
conformance/README.md Implementation conformance checklist
conformance/PROFILES.md Parser, generator, runtime, and policy profiles
conformance/SELF_ASSESSMENT.md Open registration and evidence template
conformance/v1/ Machine-readable ACC v1 conformance vectors
proposals/ Public normative proposal process and template
IMPLEMENTER_GUIDE.md Non-normative implementation architecture guidance
DESIGN_RATIONALE.md Why ACC stays small and where adjacent concerns belong
DESIGN_RATIONALE.zh-CN.md Chinese design rationale and boundaries
LANDSCAPE.md Non-normative map of adjacent protocols and governance layers
IMPLEMENTATIONS.md Known implementations and claim language
RELEASE_NOTES_v1.0.5.md Current ACC v1 patch release summary
RELEASE_NOTES_v1.0.4.md Previous ACC v1 patch release summary
RELEASE_NOTES_v1.0.3.md Earlier ACC v1 patch release summary
RELEASE_NOTES_v1.0.2.md Earlier ACC v1 patch release summary
RELEASE_NOTES_v1.0.1.md Earlier ACC v1 patch release summary
RELEASE_NOTES_v1.0.0.md Initial stable ACC v1 release summary
GOVERNANCE.md Stewardship, versioning, and extension rules
CONTRIBUTING.md Contribution rules for contract changes
SECURITY.md Private vulnerability reporting and security scope
CHANGELOG.md Public changes
NOTICE Attribution notice
LICENSE Apache-2.0 license
```
## Implementations
ACC is implementation-neutral. It can be implemented by control planes, API gateways, SDK generators, developer tools, agent runtimes, MCP gateways, and policy engines.
Known implementations are listed alphabetically in [IMPLEMENTATIONS.md](IMPLEMENTATIONS.md). Projects implementing ACC are welcome to publish a self-assessment and submit a pull request. Listing is not certification or endorsement.
## License
ACC is licensed under the Apache License 2.0. See [LICENSE](LICENSE). Security
reports should follow [SECURITY.md](SECURITY.md).
The license allows use, modification, redistribution, and commercial implementation of ACC.
---
Source: https://agentcapability.org/docs/quickstart/
Repository file: QUICKSTART.md
---
# Add ACC to an Existing OpenAPI Service in Five Minutes
This guide adds one ACC declaration to an existing OpenAPI document and validates
the result. It does not require an ACC runtime or a business-system change.
The authoring validator is non-normative. The ACC specification and OpenAPI
binding remain authoritative.
## 1. Install the authoring validator
Run the published validator without installing it globally:
```bash
npx --yes agent-capability-contract@1.0.5 validate ./openapi.yaml
```
Or add the validator to a project:
```bash
npm install --save-dev agent-capability-contract@1.0.5
```
The package requires Node.js 20 or later.
## 2. Declare one existing operation
Find one operation in your OpenAPI document. A readonly operation is a useful
first candidate:
```yaml
paths:
/orders/{order_id}:
get:
operationId: getOrder
x-agent-capability:
version: 1
enabled: true
scope: order.read
risk:
level: low
subject:
required: true
execution:
readonly: true
responses:
'200':
description: Order details
```
The declaration says that this operation is explicitly exposed to an agent
surface, belongs to the `order.read` scope, is classified as low risk, requires
a trusted acting subject, and is readonly.
It does not grant the subject permission to read an order. The business system
still makes the final authorization decision.
Use `enabled: false` when you want to preserve a declaration without exposing
the operation to agents.
## 3. Validate your OpenAPI document
Run the validator:
```bash
npx acc-validate /absolute/path/to/openapi.yaml
```
Use JSON output in CI or another developer tool:
```bash
npx acc-validate \
--format json \
/absolute/path/to/openapi.yaml
```
Use strict mode when a document with no ACC declarations should fail:
```bash
npx acc-validate \
--strict \
/absolute/path/to/openapi.yaml
```
Exit codes are stable:
| Code | Meaning |
|---|---|
| `0` | Validation passed |
| `1` | At least one document failed, or strict mode promoted a warning |
| `2` | Invalid command-line usage |
## 4. Add conditional approval only when the input is declared
An approval condition must resolve to an OpenAPI parameter or a property in a
JSON request body:
```yaml
paths:
/refunds:
post:
x-agent-capability:
version: 1
enabled: true
scope: refund.create
risk:
level: high
subject:
required: true
approval:
when:
- param: amount
op: '>'
value: 1000
requestBody:
content:
application/json:
schema:
type: object
properties:
amount:
type: number
```
The validator rejects unresolved or ambiguous condition paths and rejects
comparison values that rely on implicit JSON type coercion.
See the complete [order service example](examples/openapi-order-service.yaml)
for read, write, approval, audit, and disabled-operation declarations in one
OpenAPI document.
## What the tool checks
- OpenAPI `3.0.x` and `3.1.x` YAML or JSON documents;
- operation-level placement of `x-agent-capability`;
- ACC v1 declaration structure;
- local and local-file `$ref` resolution;
- OpenAPI parameter and JSON request-body input mapping;
- `approval.when.param` resolution and ambiguity;
- comparison operator and JSON schema type compatibility;
- machine-readable diagnostics and stable exit codes.
## What the tool does not claim
- It is not a complete OpenAPI validator or linter.
- It does not fetch remote `$ref` targets.
- It does not evaluate dynamic business authorization.
- It does not execute approval workflows or business operations.
- Passing this authoring check is not an ACC implementation certification.
Next, read the [OpenAPI Binding](bindings/openapi.md) and the
[Implementer's Guide](IMPLEMENTER_GUIDE.md).
---
Source: https://agentcapability.org/docs/spec/
Repository file: SPEC.md
---
# Agent Capability Contract v1
Status: Stable
Ecosystem maturity: Early adoption
Conformance: Self-assessment with machine-readable reference vectors
Short name: ACC v1
Specification release: 1.0.5
First standardized binding: OpenAPI (`x-agent-capability`)
## 1. Scope
ACC v1 defines a declaration model for business capabilities that may be exposed to agents.
The normative scope of ACC v1 is:
- exposing or hiding a capability;
- declaring a stable permission scope;
- declaring runtime risk;
- declaring whether a real acting subject is required;
- declaring approval intent and parameter-level confirmation rules;
- declaring audit sensitivity;
- declaring execution hints such as readonly, idempotent, timeout, and rate limit;
- providing model-readable guidance;
- preserving extension metadata without implicitly changing security behavior.
ACC v1 does not define:
- final business authorization;
- user identity format;
- runtime storage schema;
- approval workflow ownership;
- tool invocation transport;
- model provider behavior;
- user interface requirements.
## 2. Design Principles
### 2.1 Reach And Authority
ACC controls reach: which business capabilities an agent-facing runtime may expose to an agent in a specific route or scenario.
The business system controls authority: whether the acting subject can actually perform the action at call time.
An ACC-compatible runtime MUST NOT treat ACC as a replacement for business authorization.
### 2.2 Stable Core, Open Extensions
ACC core fields are stable and have explicit runtime meaning.
Unknown fields inside the ACC declaration object MUST be ignored by runtimes unless they are standardized in a later ACC version.
Binding-native or implementation-specific extension fields MAY be preserved in an extension bag, but MUST NOT implicitly alter allowlist, risk, approval, rate limit, audit, or signature behavior. For example, the OpenAPI binding may preserve operation-level `x-business-*` fields without assigning them ACC semantics.
### 2.3 Parameters Stay In Binding-Native Schemas
Business input parameters MUST remain in the standard input-schema mechanism of the bound protocol.
ACC MUST NOT become a duplicate schema language for business parameters.
Each binding MUST define how its native input schema and invocation values map to the ACC JSON value model used by validation and approval conditions. Binding requirements are defined in [bindings/README.md](bindings/README.md).
## 3. Core And Binding Model
ACC Core is the declaration object defined by the field model in this specification. A binding carries that object on a protocol-specific operation and resolves the operation's native input schema into a form a core runtime can validate.
An ACC-declared operation is exposed only when:
- `enabled` is `true`;
- `scope` is present and non-empty;
- the runtime's route or policy allows that scope;
- the binding supplies enough input schema for safe invocation.
The first standardized ACC v1 binding is OpenAPI. It carries the declaration in the operation-level `x-agent-capability` extension. Placement, extraction, parameter resolution, and OpenAPI-specific conformance are defined in [bindings/openapi.md](bindings/openapi.md).
Core declaration example:
```yaml
version: 1
enabled: true
scope: order.read
risk:
level: low
subject:
required: true
execution:
readonly: true
idempotent: true
```
## 4. Field Model
### 4.1 `version`
Type: integer
Required: yes
Allowed value in this specification: `1`
Declares the ACC schema version used by this object.
Runtimes SHOULD reject unsupported major versions or mark the operation as skipped with diagnostics.
### 4.2 `enabled`
Type: boolean
Required: yes
When `false`, the operation MUST NOT be exposed as an agent-callable capability.
### 4.3 `scope`
Type: string
Required: yes
Recommended format: dot-separated capability scope, such as `order.read`, `staff.search`, `refund.request.create`.
The scope is the unit used by route allowlists and governance policies.
Runtimes MAY support exact matching and prefix matching such as `order.*`, but matching rules are runtime policy and not part of ACC core.
### 4.4 `risk`
Type: object
Required: no
```yaml
risk:
level: low
```
Fields:
| Field | Type | Required | Values |
|---|---|---|---|
| `level` | string | no | `low`, `medium`, `high` |
Risk levels describe the worst reasonable consequence of allowing an agent to initiate the operation automatically.
- `low`: readonly or minor recoverable effect.
- `medium`: business side effect, usually single-object, recoverable, or request/draft creation.
- `high`: money movement, deletion, permission changes, HR actions, contracts, bulk actions, cross-tenant effects, external notifications, or difficult rollback.
If omitted, runtimes SHOULD apply safe defaults:
- `execution.readonly: true`: `low`;
- operations not declared readonly: `medium`.
A binding MAY define an additional native signal for the readonly default when that signal has stable semantics in the carrier protocol. The binding MUST document its precedence and conservative fallback.
### 4.5 `subject`
Type: object
Required: no
```yaml
subject:
required: true
```
Fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
| `required` | boolean | no | Whether an acting subject is required before this capability may be exposed or invoked. |
If `subject.required` is true and the runtime has no trusted acting subject, the capability SHOULD NOT be shown to the agent.
The requirement applies at the runtime's current trust boundary. A subject identifier copied from model output, tool arguments, or an unverified upstream message is not a trusted acting subject merely because the sender labels it as one. The receiving runtime MUST resolve or verify subject trust through its own trusted context or an explicit identity/delegation binding.
ACC v1 does not prove that the same subject has remained unmodified across multiple agent, runtime, or organizational hops. End-to-end subject continuity requires a complementary identity or delegation mechanism with its own issuer, verification, freshness, and failure semantics.
At invocation time, the business system MUST still verify the subject according to its own permission model.
### 4.6 `approval`
Type: object
Required: no
```yaml
approval:
required: true
prompt: "Approve refund for order {order_id}?"
when:
- param: amount
op: ">"
value: 1000
label: Refund amount exceeds 1000.
```
Fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
| `required` | boolean | no | Every invocation should create an approval intent before execution. |
| `prompt` | string | no | Human-readable approval prompt template. |
| `when` | array | no | Parameter-level confirmation rules. |
`approval.when` items:
| Field | Type | Required | Meaning |
|---|---|---|---|
| `param` | string | yes | Argument path, using dot notation for nested values. |
| `op` | string | yes | One of `>`, `>=`, `<`, `<=`, `==`, `!=`, `in`, `contains`, `exists`. |
| `value` | any | conditional | Comparison value; not required for `exists`. |
| `label` | string | no | Human-readable explanation. |
Approval condition semantics:
- `approval.required: true` means every invocation creates an approval intent. Conditional rules MUST NOT reduce an unconditional approval requirement.
- When `approval.required` is false or omitted, `approval.when` uses **ANY** semantics: one matching item is sufficient to create an approval intent.
- An absent or empty `approval.when` array creates no conditional approval intent.
- `param` MUST resolve to an input declared by the bound operation. Each binding MUST define deterministic path resolution and map native values to the ACC JSON value model.
- Runtimes MUST evaluate conditions against JSON values. They MUST NOT coerce strings into numbers or booleans for comparison.
- `>` / `>=` / `<` / `<=` require a JSON `number` or `integer` parameter and a finite JSON number as `value`.
- `==` and `!=` use strict JSON type-aware equality. For example, `true` is not equal to `"true"`, and `0` is not equal to `"0"`.
- `in` requires `value` to be a JSON array and matches when the parameter is strictly JSON-equal to one array member.
- `contains` applies only to string or array parameters. String containment requires a string `value` and uses substring matching; array containment uses strict JSON equality for elements.
- `exists` matches only when `param` resolves in the invocation input and its value is not JSON `null`. A missing path and an explicit JSON `null` therefore do not match.
- If an invocation supplies a value whose JSON type is incompatible with the condition parameter schema, the runtime MUST reject the invocation before it reaches the business operation. It MUST NOT silently treat the condition as unmatched.
`approval.when` conditions are evaluated independently for each invocation. They do not express aggregate, rolling-window, cross-invocation, or sequence constraints. For example, `amount > 1000` does not prevent an agent from proposing multiple smaller operations whose cumulative effect exceeds 1000. Deployments whose risk model includes cumulative effects MUST enforce those constraints in the authoritative business or policy layer. They MUST NOT treat a per-invocation condition as an aggregate limit.
ACC declares approval intent. It does not define who approves, where approval occurs, or how the business workflow is completed.
An approval field or runtime-authored audit entry is not, by itself, independently verifiable evidence that approval occurred. ACC v1 does not standardize canonical serialization, digital signatures, issuer keys, freshness anchors, or replay protection for approval evidence. Deployments that require third-party verification MUST provide those semantics in a complementary approval, identity, or evidence protocol.
### 4.7 `audit`
Type: object
Required: no
```yaml
audit:
sensitive: true
```
Fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
| `sensitive` | boolean | no | Indicates that arguments or responses may contain sensitive data and should be redacted or summarized in logs. |
Runtimes SHOULD preserve audit records for invocation attempts, risk decisions, approval intent, and final result.
### 4.8 `execution`
Type: object
Required: no
```yaml
execution:
readonly: true
idempotent: true
timeout_ms: 10000
rate_limit:
count: 30
window: 1m
```
Fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
| `readonly` | boolean | no | Operation should not change business state. |
| `idempotent` | boolean | no | Operation may be safely retried with the same arguments. |
| `timeout_ms` | integer | no | Invocation timeout hint in milliseconds. |
| `rate_limit` | object | no | Runtime rate limit hint. |
`execution.rate_limit`:
| Field | Type | Required | Meaning |
|---|---|---|---|
| `count` | integer | yes | Maximum number of calls in the window. |
| `window` | string | yes | Window such as `1m`, `1h`, `1d`. |
### 4.9 `guidance`
Type: object
Required: no
```yaml
guidance:
when_to_use: Use when the user asks for order status.
returns: Returns order status, amount, customer, and fulfillment state.
examples:
- id: SO202607001
context:
- customer-service
```
Fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
| `when_to_use` | string | no | Model-readable usage guidance. |
| `returns` | string | no | Human-readable return shape explanation. |
| `examples` | array | no | Example argument objects. |
| `context` | array of strings | no | Lightweight tags preserved for runtime, UI, or indexing. |
Guidance fields help agents select and call capabilities correctly. They MUST NOT be treated as security policy.
## 5. Runtime Conformance
An ACC-compatible runtime SHOULD:
- consume a validated ACC declaration and bound operation artifact from a conforming binding, or implement that binding itself;
- expose only `enabled: true` operations with a non-empty `scope`;
- compile the declaration into a runtime tool model;
- preserve the binding-native input schema required for validation;
- enforce route or policy allowlists using `scope`;
- apply risk defaults for omitted risk values;
- hide `subject.required` capabilities when no trusted subject exists;
- detect `approval.required` and `approval.when` before invocation;
- validate `approval.when` targets and values against the declared parameter schema;
- evaluate approval conditions without implicit JSON type coercion and reject incompatible invocation values before the business operation;
- preserve audit and trace information;
- ignore unknown ACC fields safely;
- preserve implementation-specific extension fields without making them security rules.
An ACC-compatible runtime MUST NOT:
- treat ACC as final business authorization;
- allow model-generated text to override scope, risk, subject, approval, or audit decisions;
- use unknown fields to silently change security behavior;
- require business parameters to be encoded inside ACC metadata;
- reinterpret a core field because a different carrier protocol is used.
## 6. Compatibility
ACC follows semantic versioning for the specification:
- patch versions clarify wording or fix schema/documentation errors;
- minor versions add optional fields or non-breaking semantics;
- major versions may change field meaning or required behavior.
ACC v1 runtimes MUST ignore unknown fields and SHOULD produce diagnostics for unsupported versions.
Ignoring an unknown field provides syntax-level forward compatibility, not automatic security compatibility. A new field that affects exposure, approval, authority boundaries, or redaction may remain in the ACC v1 family only when an older runtime ignoring it is fail-safe or when the declaration includes a conservative ACC v1 fallback. Otherwise the behavior requires a new major contract family or explicit capability negotiation.
The declaration field and the specification release serve different purposes:
- declaration field `version: 1` identifies the major contract compatibility family;
- repository releases use semantic versions such as `v1.0.5` for an exact published revision of ACC v1;
- patch and minor releases within `v1.x.x` keep the declaration field at `1`;
- a breaking contract family would require both an ACC `v2.0.0` specification release and declaration field `version: 2`.
---
Source: https://agentcapability.org/docs/concepts/
Repository file: CONCEPTS.md
---
# Concepts
## A2B: Agent-to-Business
**A2B (Agent-to-Business)** is the scenario where an agent safely and governably connects to an existing business system, acts on behalf of a real business subject, and uses business capabilities such as querying data, creating requests, updating state, or starting workflows.
A2B is not just tool calling. It includes:
- business-side identity and authorization;
- route and scenario boundaries;
- capability declarations;
- risk and approval intent;
- audit trails and traceability;
- signatures and invocation accountability;
- the ability for the business system to remain the final authority.
Short form:
```text
A2B = agents safely doing business work through existing systems.
```
## ACC: Agent Capability Contract
**ACC (Agent Capability Contract)** is the capability declaration contract for A2B.
ACC answers:
- Which business capability may be exposed to an agent?
- Under which scope?
- With what risk level?
- Does it require an acting subject?
- Does it require approval intent?
- What should be redacted or audited?
- What execution hints should a runtime respect?
ACC does not execute the capability. It declares the capability boundary.
Short form:
```text
ACC is the capability contract for A2B.
```
## Relationship
```text
A2B is the category.
ACC is the standard contract.
Implementations turn ACC declarations into runtime behavior.
```
## Why These Questions Recur
An agent can reason, draft, or simulate without producing an external effect. Governance becomes structurally important when an agent action crosses one or more boundaries:
- an **effect boundary**, where the action reads controlled data, changes state, sends a message, moves funds, or creates another real-world consequence;
- an **authority boundary**, where the action uses authority granted by a user, organization, application, or external system;
- a **trust boundary**, where the declaring, deciding, executing, and authorizing parties are not all in the same trust domain.
Across such boundaries, systems repeatedly need to answer related questions about capability reach, acting principals, consequences, human intervention, accountability, and execution semantics. A deployment may answer that no subject or approval is required for a particular low-consequence operation; that is still an explicit governance decision.
This recurring problem family is broader than any one transport or binding. It does **not** mean that ACC v1 already governs every agent action, or that its current fields can be copied unchanged into MCP, A2A, app intents, operating-system permissions, or cross-organization delegation. ACC v1 remains the concrete contract for A2B business operations, with OpenAPI as its first binding. Broader applicability requires separate bindings, failure semantics, implementation evidence, and public proposal review.
The same distinction applies to multi-hop trust. ACC can declare that a capability requires a trusted acting subject and approval intent at a boundary. It does not, by itself, prove that an identity or approval remained authentic and unmodified across a chain of agents, runtimes, or organizations. Identity continuity, delegation, independently verifiable evidence, freshness, and replay protection are complementary protocol concerns rather than implicit guarantees of an ACC declaration.
## Adjacent Terms
| Term | Meaning | Relationship |
|---|---|---|
| A2A | Agent-to-Agent collaboration. | Adjacent, not the same problem. |
| MCP | A protocol ecosystem for exposing and invoking tools. | Can be used with A2B, but does not define business governance by itself. |
| ACC | Capability declaration contract for A2B. | Defines portable business capability metadata. |
| ACC runtime | Any implementation that parses, validates, or enforces ACC declarations. | Runtime implementation, not the contract itself. |
## Scope in Plain Language
ACC v1 is a concrete, machine-readable capability contract for A2B systems. It is maintained independently from product implementations, and no implementation defines the standard merely by supporting it.
The governance questions described above may recur in other agent-action environments. That observation motivates research and future bindings, but it does not expand the current ACC v1 compatibility claim beyond its documented A2B scope.
---
Source: https://agentcapability.org/ecosystem/
Repository file: LANDSCAPE.md
---
# ACC in the Agent Governance Landscape
> Status: Informational and non-normative. This document explains where ACC fits among adjacent specifications, protocols, policy systems, and runtime controls. It does not change ACC v1 semantics or require any named technology.
## The Short Answer
ACC is a portable, operation-level declaration contract for business capabilities that may be exposed to agents.
It is designed to sit between interface and transport descriptions on one side, and deployment-specific enforcement and final business authorization on the other:
```text
Agent applications and orchestration
|
Interface, discovery, and transport protocols
|
ACC: portable business capability governance declarations
|
Runtime policy, gateways, control planes, and approval systems
|
Business authorization, workflows, data, and final effects
```
These layers are complementary. An implementation may use OpenAPI, MCP, A2A, a runtime hook framework, a policy engine, and ACC in the same system.
## Layer Map
| Layer | Primary question | Examples | Relationship to ACC |
|---|---|---|---|
| Interface description | What operation exists, and what are its inputs and outputs? | OpenAPI, JSON Schema | ACC reuses standard interface schemas instead of duplicating business parameters. |
| Tool and agent transport | How are tools or agents discovered, connected, and invoked? | MCP, A2A | A binding or adapter may carry ACC metadata across these protocols. ACC does not replace their transport semantics. |
| Identity and trusted metadata | Which agent or artifact is this, and which claims can be verified? | OASF, AgentFacts, identity and credential systems | ACC describes a business operation, not an agent identity or a trust credential. |
| Capability governance declaration | What business operation may an agent-facing surface expose, with what subject, risk, approval intent, audit, and execution metadata? | ACC | This is ACC's core responsibility. |
| Runtime decision and enforcement | Where and how is an invocation inspected, allowed, denied, transformed, escalated, throttled, or audited? | Control planes, API gateways, policy components, runtime hook specifications, OpenPort-style secure gateways | These systems can consume ACC declarations and combine them with local policy and context. |
| Enterprise policy and authorization | Is this subject allowed to perform this action now? | RBAC, ABAC, XACML, OPA, Cedar, IAM, application authorization | These systems retain authority. ACC must not replace them. |
| Workflow and transaction coordination | How are multi-step work, compensation, retries, and recovery coordinated? | Workflow engines, Saga coordinators, approval systems | ACC can describe individual capabilities, but does not promise cross-operation atomicity. |
## Recurring Governance Questions Across Boundaries
The technologies in this landscape do not all solve the same problem, but consequential agent actions repeatedly raise a related set of governance questions:
| Question | Portable concern | Current ACC v1 expression |
|---|---|---|
| What may the agent-facing surface expose? | Capability reach | `enabled`, `scope` |
| Must the action be bound to a trusted business actor? | Acting principal | `subject` |
| What kind of consequence can the operation produce? | Risk signal | `risk` |
| When must execution pause for an external decision? | Human intervention intent | `approval` |
| What evidence must remain for explanation and traceability? | Accountability | `audit` and runtime evidence |
| What portable execution properties should be preserved? | Execution semantics | `execution` |
These questions become relevant when an action crosses an effect, authority, or trust boundary. They can recur in business APIs, MCP tools, app intents, A2A delegation, and cross-organization automation.
Recurrence does not imply protocol ownership. A2A additionally needs task, delegation, and multi-party semantics. App and operating-system integrations need sandbox, permission, lifecycle, and user-consent semantics. Cross-organization systems need credentials, disclosure, revocation, and responsibility models. ACC must not absorb those layers merely because some governance questions are shared.
ACC v1 is the concrete A2B and operation-level contract in this landscape. Whether its core semantics can support other environments must be demonstrated through separate bindings, explicit failure behavior, independent implementations, and public proposal review.
## Adjacent Protocols and Specifications
### OpenAPI and JSON Schema
[OpenAPI](https://spec.openapis.org/oas/latest.html) describes HTTP operations, parameters, request bodies, responses, and other interface details. JSON Schema describes data shape and validation constraints.
ACC's first binding uses the OpenAPI extension field `x-agent-capability`. Business parameters remain in standard OpenAPI and JSON Schema. ACC adds portable agent-facing governance meaning beside the operation.
### MCP
[Model Context Protocol](https://modelcontextprotocol.io/specification/) defines an ecosystem for connecting models and applications to tools, resources, and prompts.
MCP and ACC answer different questions:
- MCP helps a client discover and invoke a tool.
- ACC describes the governance meaning of the underlying business operation.
An MCP gateway may expose a tool derived from an ACC-marked operation. A future ACC binding may define a portable mapping, but MCP is not required to implement ACC.
### A2A
[Agent2Agent Protocol](https://a2a-protocol.org/latest/) addresses communication and collaboration between agents. Its extension mechanism can carry additional capabilities or metadata.
ACC focuses on Agent-to-Business operations rather than Agent-to-Agent collaboration. An A2A extension may transport ACC-related metadata, but the two specifications do not own the same layer.
### Runtime control specifications
Runtime control systems define interception points and decisions around a live invocation. Two similarly named efforts must not be conflated:
- Microsoft's [Agent Control Specification](https://microsoft.github.io/agent-governance-toolkit/packages/agent-control-specification/) is part of the Agent Governance Toolkit and describes runtime intervention points and control decisions.
- The independent [Agent Control Standard](https://agentcontrolstandard.org/) describes governance hooks, Guardian-style evaluation, observability, and an Agent Bill of Materials.
Runtime hooks answer where and how to enforce a decision. ACC answers what portable governance meaning the business operation declares. A runtime can use both.
### Secure gateways and OpenPort
[OpenPort](https://arxiv.org/abs/2602.20196) proposes a model- and runtime-independent service-side security gateway for exposing application tools with controlled writes, authorization, failure handling, and auditability.
This has meaningful architectural overlap with an ACC runtime or control plane, but it is not the same artifact. ACC is a declaration contract; a secure gateway is an enforcement architecture. A gateway may consume ACC declarations, translate them into local policy, or use another declaration model.
### OASF and AgentFacts
[Open Agentic Schema Framework](https://docs.agntcy.org/pages/oasf.html) focuses on describing agent records, skills, domains, and discovery metadata. [AgentFacts](https://arxiv.org/abs/2507.14263) explores signed and verifiable claims about agents.
These efforts primarily describe or establish trust in an agent or artifact. ACC describes a business operation offered to agents. Trusted agent identity and operation-level governance can be used together.
### OPA, Cedar, XACML, RBAC, and ABAC
Policy languages and authorization models evaluate deployment-specific rules using local identities, resources, context, and enterprise policy.
ACC does not attempt to become a general policy language. A runtime may map `scope`, `risk`, `subject`, or approval metadata into [OPA](https://www.openpolicyagent.org/), [Cedar](https://www.cedarpolicy.com/), an API gateway policy, or application code. The business system still makes the final authorization decision.
## Why Keep a Separate Declaration Contract?
Business capability governance should survive changes in model provider, agent framework, transport protocol, gateway, and workflow product. Keeping the portable declaration separate from a particular enforcement runtime provides three useful properties:
1. **Portability:** the same operation metadata can be consumed by different implementations.
2. **Separation of responsibility:** the declaration describes governance intent without pretending to own identity, authorization, workflow, or UI.
3. **Testability:** parsers and runtimes can publish precise conformance evidence for the fields they support.
This separation does not mean every deployment needs a standalone ACC server. ACC metadata may be parsed by an SDK, gateway plugin, policy component, control plane, build tool, or agent runtime.
## Frequently Asked Questions
### Is ACC a replacement for MCP or A2A?
No. MCP and A2A define connection and collaboration mechanisms. ACC defines portable governance metadata for operations in existing business systems. They can be composed.
### Is ACC intended to govern every agent action?
No. ACC v1 has a precise normative scope: A2B business operations, with OpenAPI as the first binding. The governance questions ACC addresses can recur when agents cross other effect, authority, or trust boundaries, but broader applicability is a research and binding question rather than a current compatibility claim.
### Does every agent action need approval or a business subject?
No. The structural requirement is to reach an explicit governance conclusion. A low-consequence operation may require no subject and no approval, while a consequential operation may require both. ACC describes those differences; it does not make every operation high risk.
### Is ACC an authorization system?
No. ACC controls reach: what an agent-facing runtime may expose. The business system controls authority: whether the acting subject may perform the action at call time.
### Why not put all ACC fields directly into MCP or A2A?
A protocol-specific extension can carry ACC metadata, but the declaration should remain usable when a deployment uses another transport or calls an HTTP API directly. Protocol bindings belong beside the core contract, not inside its portable semantics.
### Why not use OPA, Cedar, or an API gateway instead?
Those systems make or enforce local policy decisions. ACC provides a common operation-level input that implementations may translate into those systems. ACC does not replace local policy.
### Do runtime hooks make ACC unnecessary?
No. Hooks define interception points and available actions. They do not automatically provide portable business meaning for every operation. Hooks and gateways can consume ACC declarations as one source of governance intent.
### Does an ACC declaration make an operation safe by itself?
No. Safety requires a compatible runtime, trusted subject resolution where applicable, secure execution, audit, and final business authorization. ACC is one layer in that chain.
### Is ACC tied to BailingHub or another implementation?
No. ACC is maintained independently. Implementations are evaluated under the same public profiles and evidence rules, regardless of owner.
### Why is the core deliberately small?
Fields enter the core only when their meaning can remain implementation-neutral, machine-testable, compatible, and separate from final authority. Runtime policy, approval ownership, enterprise compliance, multi-step workflow, and business invariants remain in their proper layers.
## Scope of This Document
The landscape changes quickly. Named projects are examples, not endorsements, dependencies, or claims of equivalence. This page explains architectural responsibility, not market rank.
For normative ACC behavior, read [SPEC.md](SPEC.md). For the boundary and field-admission rationale, read [DESIGN_RATIONALE.md](DESIGN_RATIONALE.md).
---
Source: https://agentcapability.org/docs/design-rationale/
Repository file: DESIGN_RATIONALE.md
---
# ACC Design Rationale And Boundaries
[简体中文](DESIGN_RATIONALE.zh-CN.md)
Status: Non-normative rationale
Applies to: ACC v1
ACC is intentionally a small contract. Small does not mean incomplete: it means the normative core contains only semantics that independent runtimes can interpret consistently without understanding one product's database, UI, identity model, approval system, or deployment topology.
Normative behavior is defined by [SPEC.md](SPEC.md), the versioned schema, and binding documents. This file explains why several useful platform and business features are not ACC core fields.
## 1. The Boundary In One Sentence
```text
ACC declares the agent-facing capability boundary.
The runtime governs exposure and invocation.
The business system remains the final authority.
```
ACC answers what an agent-facing runtime needs to know about a business capability: whether it is exposed, its policy scope, consequence risk, subject requirement, approval intent, audit sensitivity, execution hints, and model-readable guidance.
ACC does not attempt to describe the entire A2B control plane.
## 2. Test For A Core Field
A field belongs in ACC core only when all of the following are true:
1. It changes portable agent-facing governance semantics.
2. Independent parsers or runtimes can implement the same meaning.
3. The behavior can be tested without one product's private database, UI, identity directory, or workflow engine.
4. Standard binding-native protocol and schema mechanisms cannot already express it cleanly across the target bindings.
5. It does not require the runtime to become the final business authorization authority.
6. An older compatible runtime can ignore the field without silently reducing security, or the change uses a new major compatibility family.
These conditions are necessary, not sufficient. Passing them makes a proposal eligible for governance review; it does not create an obligation to add the field to ACC core.
Review also considers:
- demonstrated need across independent implementation contexts;
- whether the proposal is the smallest stable semantic addition;
- whether a binding, implementation extension, or adjacent specification is a better owner;
- complete defaults, precedence, failure, and security semantics;
- backward-compatibility and ecosystem implementation cost;
- implementation evidence and machine-readable conformance vectors.
More fields are not automatically better. A field that cannot pass this test creates apparent portability while moving hidden assumptions into every implementation.
## 3. Known Concerns That Are Intentionally Outside ACC Core
| Concern | Why it is not an ACC v1 core field | Correct owner or layer |
|---|---|---|
| Final user permission | Roles, ABAC rules, ownership, data permissions, and current account state are business-specific and time-dependent. | Business authorization layer |
| Tenant or merchant isolation | Isolation must remain enforced when an API is called outside an agent runtime. Gateway parameter injection is not a security boundary. | Business data and authorization layers |
| Identity representation | Sessions, JWT claims, service principals, certificates, directory groups, and signed tickets are not interchangeable. | Runtime identity bridge and business system |
| Approval assignee and workflow | Who approves, quorum, delegation, expiry, UI, and escalation depend on an organization's process. | External approval owner |
| Cross-hop subject continuity and delegation | A Boolean subject requirement cannot prove identity continuity across agents, runtimes, organizations, issuers, and trust domains. | Identity, delegation, or protocol-binding layer |
| Independently verifiable approval evidence | Canonical bytes, signatures, issuer keys, freshness, replay protection, and external verification require a complete evidence protocol and threat model. | Approval-evidence, attestation, or delegation layer |
| Business deny rules | Blacklists, order state, inventory, refund limits, and contractual restrictions require authoritative business data. | Business policy and authorization layer |
| Cross-field or contextual invariants | Rules such as refund amount not exceeding the current order balance require fresh, authorized business state. | Business operation or preflight API |
| Context fetching | Where a value comes from, who may fetch it, freshness, failure, and caching require a separate data-access contract. | Runtime integration or business API |
| Audit retention and legal hold | Retention duration, archive, deletion, and legal hold are organization-wide compliance policies. | Deployment and compliance policy |
| Field-level audit redaction | ACC v1 declares broad sensitivity. A portable request/response path model, arrays, references, and conservative fallback still need design evidence. | OpenAPI schema annotation, runtime policy, or a future ACC proposal |
| General Boolean condition groups | ACC v1 intentionally uses bounded ANY conditions. Nested Boolean policy needs precedence, compatibility, and fail-safe semantics. | Runtime policy engine or a future ACC proposal |
| Detailed effect or business-domain taxonomy | `execution.readonly` already carries the most portable state-change distinction. Destructive, additive, open-world, and domain labels overlap binding-native metadata, may be non-exclusive, and do not yet have stable cross-industry semantics. | Binding-native annotations, authoring diagnostics, implementation extensions, or a future evidence-backed proposal |
| Approval UI or double confirmation | Some runtimes are headless gateways, queues, or deterministic workflows with no user interface. | Runtime or approval product |
| Rollback and compensation | Compensation is not necessarily an inverse call; it needs authorization, state, idempotency, and workflow semantics. | Transaction, saga, or workflow layer |
| Tool composition and ordering | Preconditions, orchestration, and multi-step transactions form a workflow or planning contract. | Workflow or orchestration layer |
| Storage, queue, signatures, metrics, and cost accounting | These are valuable control-plane features but do not change the portable declaration meaning. | Runtime implementation |
| HTTP, RPC, message queue, or MCP transport | ACC declarations can be consumed before several different invocation transports. | Binding, adapter, or transport specification |
Leaving these concerns outside ACC does not make them unimportant. It prevents ACC from giving false guarantees about responsibilities that only the business system or deployment owner can fulfill.
## 4. Thin Is Not Vague
A thin contract still needs exact semantics.
ACC therefore specifies:
- required fields and JSON types;
- exposure requirements for `enabled`, `scope`, and trusted-subject availability;
- strict, type-aware approval-condition comparison;
- safe handling of unsupported versions and unknown fields;
- the separation between model-controlled input and trusted governance metadata;
- conformance profiles and observable outcomes.
If the same declaration can be interpreted in contradictory ways by conforming implementations, that is a specification defect and should be corrected. If two organizations intentionally map the same risk classification to different local approval workflows, that is deployment policy, not a portability defect.
### 4.1 Why ACC v1 Uses A Compact Risk Classification
`risk.level` describes the worst reasonable consequence of allowing an agent to initiate an operation automatically. It is a portable classification result, not a claim that every contributing factor can already be standardized.
Candidate factors such as state-change effect, destructive behavior, money movement, permission change, external communication, or business domain may improve authoring diagnostics. They are not automatically suitable core fields:
- one operation may have several effects depending on arguments and current business state;
- industry domains are overlapping and do not map to one universal risk policy;
- OpenAPI methods, ACC execution hints, MCP annotations, and future bindings may already carry related metadata with different trust semantics;
- if a new runtime upgrades `risk.level` from optional factors while an older runtime ignores them, the compatibility fallback may become less safe.
Implementations may experiment with namespaced factors or lint rules. A future proposal must define deterministic behavior, precedence, conservative fallback, and evidence from independent bindings before any factor becomes ACC Core.
### 4.2 Why Guidance Remains In The Capability Contract
An agent-facing capability must be selectable as well as governable. `guidance` carries supplemental model-readable selection context, while remaining explicitly non-authoritative and non-security-critical.
Bindings must reuse their native schema, description, and example mechanisms wherever those mechanisms already express the API accurately. ACC guidance must not replace request or response schemas, contradict binding-native descriptions, or become authorization policy. Each binding defines the mapping and precedence between native descriptive metadata and supplemental ACC guidance.
## 5. Examples Of The Boundary
### Portable declaration
```yaml
approval:
when:
- param: amount
op: ">"
value: 10000
```
The invocation argument and literal threshold are declared in the operation contract. A runtime can evaluate the condition without private business data.
### Business invariant
```text
refund amount <= current refundable order balance
```
The current balance is authoritative business state. The business operation must validate it even when the API is called without an agent runtime.
### Trusted subject requirement
```yaml
subject:
required: true
```
ACC declares that an anonymous or untrusted invocation is not acceptable. It does not standardize whether the subject arrives as a JWT, signed ticket, service principal, or another trusted identity form.
## 6. Why ACC Does Not Standardize A Universal Policy Engine
A general policy language would need a type system, expression grammar, authoritative data sources, authorization for data access, freshness rules, deterministic failure semantics, and a sandbox. A partial expression language would make declarations look enforceable while allowing runtimes to interpret them differently.
ACC v1 uses bounded, typed conditions over declared invocation arguments. More powerful policy evaluation can be integrated by a runtime under an explicit policy namespace without pretending it is portable ACC behavior.
## 7. Safe Evolution
Unknown fields are ignored so newer declarations remain parseable by older runtimes. That rule does not make every new security field backward-compatible.
A new field that affects exposure, approval, authorization boundaries, or redaction may enter the same major family only when ignoring it is fail-safe or when the declaration carries a conservative fallback understood by older runtimes. Otherwise it requires a new major contract family or explicit capability negotiation.
Examples:
- An optional condition-combination hint may be compatible when an older runtime falls back to a more conservative approval decision.
- A new redaction field is not safely compatible if an older runtime ignores it and records raw sensitive values; it needs an existing broad sensitivity fallback or a new compatibility boundary.
## 8. How To Propose More Expressive Fields
A proposal should include:
- the portable problem, with more than one implementation context;
- why binding-native standard fields or an implementation extension cannot solve it;
- complete field and failure semantics;
- interaction and precedence with existing fields;
- backward-compatibility and fail-safe analysis;
- parser and runtime conformance vectors;
- examples that do not depend on one product's private architecture.
Features may begin as implementation extensions. Proven, portable, testable semantics can later be proposed for ACC through the process in [CONTRIBUTING.md](CONTRIBUTING.md).
---
Source: https://agentcapability.org/docs/implementer-guide/
Repository file: IMPLEMENTER_GUIDE.md
---
# ACC Implementer's Guide
Status: Non-normative guidance
Applies to: ACC v1
This guide helps teams turn ACC declarations into parsers, generators, gateways, policy components, or complete runtimes. It explains implementation patterns without prescribing a product architecture.
Normative ACC behavior is defined only by [SPEC.md](SPEC.md), the binding documents, and the versioned schema. If this guide conflicts with those sources, the normative sources win.
## 1. Reading Labels
This document uses four labels:
- **Normative**: behavior already required or recommended by ACC v1.
- **Recommended**: an implementation pattern that commonly produces safe, portable behavior.
- **Optional**: useful platform functionality that is not required for ACC compatibility.
- **Example**: one possible design. Examples do not define the standard.
ACC does not require a particular programming language, database, model provider, UI, deployment topology, tool transport, or approval product.
## 2. Choose an Implementation Profile
Before building, choose the claim that matches the component:
- **ACC binding parser**: extracts and validates ACC declarations from a named carrier protocol.
- **ACC binding generator**: produces a named binding from source code, annotations, or another contract.
- **ACC runtime**: applies ACC exposure and invocation semantics.
- **ACC policy component**: evaluates a documented subset of ACC governance semantics for another runtime or gateway.
The profiles and their minimum evidence are defined in [conformance/PROFILES.md](conformance/PROFILES.md). A component should claim only the profile it actually implements.
## 3. Reference Architecture
The following architecture is a reference, not a required topology:
```mermaid
flowchart LR
A["Binding-native operation + ACC declaration"] --> B["Binding ingestion"]
B --> C["Capability registry or adapter"]
C --> D["Exposure policy"]
D --> E["Agent, gateway, or caller"]
E --> F["Pre-invocation governance"]
F -->|"approval intent"| G["External approval owner"]
G -->|"approved or denied"| F
F --> H["Trusted subject and authority bridge"]
H --> I["Business operation"]
F --> J["Audit and diagnostics"]
I --> J
```
| Module | ACC relationship | Implementation freedom |
|---|---|---|
| Binding ingestion | **Normative** for binding parsers: extract the declaration, validate required fields, preserve the binding-native input schema, and diagnose unsupported versions. | Parser library, build-time compiler, gateway plugin, generated code, or another form. |
| Capability registry or adapter | **Recommended**: keep the binding-qualified operation, input schema, ACC metadata, and source location together. | In memory, generated artifact, database, gateway configuration, or no persistent registry. |
| Exposure policy | **Normative** for runtimes: apply `enabled`, `scope`, trusted-subject availability, and safe handling of unsupported declarations before exposing a capability. | Route policy, tenant policy, gateway policy, static allowlist, or another documented policy context. |
| Caller or selection layer | **Optional**: an LLM function-calling loop is one possible caller, not an ACC requirement. | Agent runtime, deterministic workflow, API gateway, MCP gateway, human-operated tool, or another caller. |
| Pre-invocation governance | **Normative** for runtimes: validate arguments, risk, approval intent, execution hints, and sensitive-data handling before business execution. | Inline middleware, policy engine, sidecar, gateway filter, or generated wrapper. |
| Approval owner | ACC declares approval intent but does not own the workflow. | Existing business workflow, ticketing system, human-in-the-loop service, or another authority. |
| Authority bridge | **Normative boundary**: ACC is not final authorization. The business system must decide whether the trusted acting subject may perform the operation. | Existing session/role model, service authorization API, policy engine, or another business-owned mechanism. |
| Execution transport | Outside ACC core. | HTTP, RPC, message queue, local call, MCP transport, or another mechanism. |
| Audit and diagnostics | **Normative or recommended** according to ACC fields: preserve capability, governance decision, result/failure summary, and requested redaction. | Database, event stream, logs, tracing backend, or another storage model. |
Cost tracking, console UI, routing products, model orchestration, HMAC signatures, queues, and deployment tooling may be valuable, but they are not required by ACC v1.
## 4. Declaration Ingestion Lifecycle
**Normative and recommended sequence:**
1. Parse a supported binding and locate its ACC declaration carrier.
2. Validate `version`, `enabled`, and `scope`.
3. Resolve the binding-native input schema and map it to the ACC JSON value model.
4. Validate that every `approval.when.param` resolves to a declared, typed argument.
5. Reject or skip unsupported major versions with diagnostics.
6. Ignore unknown ACC fields safely.
7. Preserve implementation-specific extensions without treating them as security policy.
8. Produce a normalized capability record or equivalent generated artifact.
A runtime should keep the original operation identity and source location so diagnostics can point back to the contract authors.
For the OpenAPI binding, steps 1 and 3 mean locating operation-level `x-agent-capability` and resolving standard OpenAPI `parameters` plus `requestBody` schemas. Other bindings must define equivalent extraction and mapping under [Binding Requirements](bindings/README.md).
**Recommended:** validate publisher authority separately from schema validity. Keep the trusted publisher, binding-qualified operation identity, input-schema revision, and change review together. A digest detects different bytes; it does not authenticate the publisher. See [Safety Governance Responsibilities](SAFETY_GOVERNANCE_GUIDE.md#2-keep-source-data-and-authority-separate) for the ingestion and cache lifecycle boundary.
## 5. Exposure Lifecycle
Before a capability becomes visible to an agent or caller:
1. Exclude declarations with `enabled: false` or an empty `scope`.
2. Apply the runtime's documented scope allowlist semantics.
3. If `subject.required` is true, require a trusted acting subject before exposure or invocation.
4. Apply safe risk defaults when `risk.level` is omitted.
5. Preserve the binding-native input schema used for argument generation and validation.
6. Emit diagnostics for skipped or unsupported declarations.
For approval evaluation, `approval.required: true` is unconditional. Otherwise, `approval.when` uses ANY semantics: the first or any matching condition is sufficient to create an approval intent. Implementations may evaluate every condition for diagnostics, but a non-matching condition cannot cancel another matching condition.
### Per-Invocation Conditions Do Not Limit Cumulative Effects
`approval.when` evaluates one invocation at a time. Consider a refund operation with this condition:
```yaml
approval:
when:
- param: amount
op: ">"
value: 1000
```
The condition creates approval intent for one refund above 1000. It does not prevent an agent from proposing 60 separate refunds of 999, and it does not calculate a customer's daily, tenant-wide, or rolling-window total.
Do not represent cumulative fraud controls, velocity limits, account balances, or other stateful business invariants as if a per-invocation ACC condition enforced them. Keep those controls in the authoritative business or policy layer, evaluate them against current state, and let that layer reject or escalate the operation even when the individual ACC condition does not match.
ACC does not standardize a route object. A runtime may use routes, products, tenants, scenarios, or static policies as its exposure context, provided its matching behavior is documented.
## 6. Invocation Lifecycle
The following sequence is suitable for an LLM tool loop, API gateway, deterministic workflow, or another caller:
```text
select capability
-> validate arguments against the binding-native input schema
-> resolve trusted acting subject
-> evaluate scope and runtime policy
-> evaluate risk and approval intent
-> apply timeout/rate-limit policy
-> request approval or continue
-> invoke the business operation
-> let the business system authorize the subject
-> record result/failure with redaction
-> return a typed result to the caller
```
The model or caller may propose a capability and arguments. It must not determine its own scope, risk, subject trust, approval decision, or audit policy.
Machine-readable reference inputs and abstract expected outcomes are published under [conformance/v1](conformance/v1/README.md). They test portable decisions rather than a particular queue, database, hash algorithm, or user interface.
### 6.1 Trust Across Multiple Hops
`subject.required: true` distinguishes a capability that needs a trusted acting subject from one that does not. It does not make an arbitrary inbound `subject` field trustworthy, and it does not establish an end-to-end delegation chain.
For a chain such as `Agent A -> Runtime B -> Runtime C -> business operation`, every trust boundary must answer separately:
- who asserted the subject;
- how that assertion was authenticated or verified;
- whether delegation to the next hop is allowed;
- what capability, arguments, task, audience, and time window the delegation covers;
- what happens when verification, freshness, or replay checks fail.
A runtime must not upgrade model output or an unverified upstream claim into trusted subject context. Deployments that need cross-hop continuity should use a complementary identity or delegation mechanism and document its binding to ACC capability identity and invocation arguments. ACC compatibility alone is not evidence that the subject at the final hop is the subject authenticated at the first hop.
## 7. Approval Intent Reference Flow
ACC declares that approval is required; it does not standardize the workflow owner or persistence model.
A portable reference state model is:
```mermaid
stateDiagram-v2
[*] --> Pending: approval intent created
Pending --> Approved: external authority approves
Pending --> Denied: external authority denies
Pending --> Expired: policy deadline reached
Approved --> Consumed: authorized invocation is accepted
Denied --> [*]
Expired --> [*]
Consumed --> [*]
```
Recommended safety properties:
- freeze or hash the capability identity and invocation arguments that were reviewed;
- bind the decision to a trusted approver or business authority;
- prevent an approval from authorizing different arguments;
- make an approval single-use unless the business policy explicitly says otherwise;
- record denial, expiry, and execution failure as distinct outcomes.
After approval, a runtime may resume a suspended invocation, enqueue a new invocation, or rerun a deterministic snapshot. Those are implementation choices, not ACC semantics.
### 7.1 Traceability And Independently Verifiable Evidence
An audit trail written by the same runtime that resolves the subject and enforces approval can provide useful operational traceability inside that runtime's trust domain. It is not independent proof against compromise of that runtime.
Where a deployment requires approval evidence that another party can verify, it should bind at least the subject, capability identity, canonical invocation arguments, task or request identity, decision, issuer, and validity context before execution. The deployment must also define:
- one canonical byte representation shared by signer and verifier;
- signature and key-discovery rules;
- freshness and clock assumptions;
- nonce, sequence, or other replay protection;
- fail-closed behavior when any verification step is unavailable or ambiguous.
These details are deliberately not ACC v1 semantics. A deployment may use a separate approval-evidence or delegation protocol, provided it does not present that protocol's guarantees as guarantees of ACC itself.
## 8. Security Invariants and Failure Modes
These are specification-derived invariants, not claims about how often a particular implementation fails.
| Invariant | Failure mode | Expected protection |
|---|---|---|
| ACC controls reach; the business system controls authority. | Treating `scope` or `subject.required` as final business permission. | Re-authorize the acting subject inside the business system at call time. |
| Governance metadata is trusted contract input, not model output. | Letting generated text lower risk, invent a subject, approve itself, or disable audit. | Keep governance decisions outside the model-controlled payload. |
| Subject trust is established at a trust boundary; it does not compose by relabeling an upstream claim. | Treating an inbound subject identifier as proof of end-to-end identity or delegation. | Resolve or verify the subject at each boundary and use a complementary delegation mechanism when continuity across hops is required. |
| Approval comparisons are JSON type-aware. | Coercing `"1000"` to `1000` or `"true"` to `true`. | Validate against OpenAPI and use strict JSON equality and numeric rules. |
| Unknown fields have no implicit security meaning. | A runtime-specific extension silently bypasses scope, approval, or audit. | Ignore unknown ACC fields or process them only under an explicit non-ACC policy namespace. |
| Approval applies to a reviewed invocation. | Approval for one argument set is reused for another. | Bind the decision to capability identity and canonical arguments. |
| Runtime audit records are traceability, not automatically independent proof. | The same compromised runtime authors the approval assertion and the evidence used to verify it. | Use externally verifiable, pre-execution evidence when the threat model requires it. |
| Sensitive declarations affect observability. | Raw secrets or personal data enter logs, traces, or metric labels. | Redact or summarize before persistence and export. |
| Unsupported versions are visible. | A runtime silently interprets a newer declaration using older semantics. | Reject or skip it with diagnostics. |
Implementation-specific incidents may be contributed as clearly labeled examples. A single product's internal failure should not be generalized into normative ACC behavior without portable semantics and conformance evidence.
**Recommended input separation:**
| Input | Use | Boundary |
|---|---|---|
| Authenticated publisher's governance declaration | Compile validated ACC semantics | Valid schema alone does not establish source trust. |
| Tool name, object display name, description, or guidance | Select and understand a capability | Do not derive identity, authorization, or approval from display text. |
| Tool result, retrieved document, or file content | Interpret business data | Embedded instructions do not change governance. |
| Changed schema/declaration or cached tool | Review changes or reuse valid artifacts | Preserve reviewed arguments and revalidate current target/policy; cache presence is not authorization. |
The [governance responsibility map](SAFETY_GOVERNANCE_GUIDE.md#3-responsibility-and-evidence-map) separates these ACC boundaries from task budgets, host isolation, lifecycle controls, and deployment evidence.
## 9. Conformance Mapping
| Reference module | Primary checklist sections |
|---|---|
| Contract ingestion | Parser |
| Exposure policy | Exposure, Authority Boundary |
| Pre-invocation governance | Governance, Authority Boundary |
| Approval integration | Governance, Traceability |
| Authority bridge | Authority Boundary |
| Audit and diagnostics | Traceability |
Use [conformance/PROFILES.md](conformance/PROFILES.md) to select the applicable profile and [conformance/SELF_ASSESSMENT.md](conformance/SELF_ASSESSMENT.md) to publish evidence.
## 10. Registering an Implementation
ACC uses open registration and self-assessment, not official certification.
1. Select an implementation profile.
2. Complete the self-assessment template.
3. Publish evidence and known limitations in the implementation repository.
4. Submit a pull request that adds the implementation to [IMPLEMENTATIONS.md](IMPLEMENTATIONS.md).
5. Keep the declared ACC version and evidence current.
Registry inclusion means the declaration is complete enough to list. It is not a security audit, production-readiness guarantee, commercial endorsement, or certification.
---
Source: https://agentcapability.org/docs/safety-governance/
Repository file: SAFETY_GOVERNANCE_GUIDE.md
---
# Safety Governance Responsibilities
Status: Non-normative guidance
Applies to: ACC v1, specification release 1.0.5
Reference review date: 2026-09-15
[中文](SAFETY_GOVERNANCE_GUIDE.zh-CN.md)
ACC describes business capabilities. A valid declaration is a useful input to governance; it is not proof of a trustworthy publisher, authorized execution, or a safe application. This guide helps a gateway, workflow, SDK, or agent runtime divide those responsibilities and choose evidence to test them.
Only [SPEC.md](SPEC.md), the [bindings](bindings/README.md), and the versioned schema define ACC semantics. **Normative reference** below points to an existing ACC rule; **Recommended**, **Optional**, and **Example** identify implementation guidance, not new ACC obligations. This document adds no fields, compatibility profile, certification, or jurisdiction-specific condition for using ACC.
## 1. Review One Business Task
**Example:** “Update pictures and descriptions for these 100 catalog items; read inventory to check availability; do not change prices or stock.”
The catalog and inventory services declare separate capabilities. ACC can describe each capability's scope, risk, required subject, approval intent, and execution/audit hints. The authorized object set, editable fields, total impact, selected service identities, and task stop conditions belong to the runtime and authoritative business policies. An agent's plan or a display name cannot grant those permissions.
**Recommended:** review the task with the [catalog and inventory worksheet](examples/BUSINESS_RISK_EXAMPLES.md), then distinguish three artifacts:
1. The declaration and binding-native operation, reviewed by its publisher.
2. The deployment's effective authorization, approval, and task controls.
3. Evidence of the exact implementation and operations actually tested.
The [reference-vector coverage index](conformance/v1/COVERAGE.md) explains how little of the third artifact can be inferred from the corpus alone.
## 2. Keep Source, Data, and Authority Separate
**Normative references:** [SPEC §§4.5, 4.9, 5](SPEC.md#5-runtime-conformance) establish subject trust, the non-policy nature of guidance, and the prohibition on model text overriding governance.
**Recommended implementation boundary:**
| Input | Appropriate use | Not established by that input |
|---|---|---|
| Governance declarations ingested through an authenticated, authorized publisher configuration | Validate and compile the declared semantics against a known operation | Schema validity does not authenticate the publisher or prove the implementation benign. |
| Tool names, object display names, descriptions, and `guidance` | Help a caller understand and select capabilities | They are not authorization identities, approval decisions, or executable policy. |
| Web pages, files, business text, and other tool results | Data to interpret and results to verify | Embedded instructions do not become trusted governance rules. |
| An updated declaration or input schema | Trigger a documented change review and revalidation | An update does not silently authorize changing previously approved arguments or targets. |
| Cached or loaded tools | Avoid repeated discovery while the task remains valid | A cache does not establish current permission, subject trust, or operation-version validity. |
**Recommended:** keep the publisher identity, binding-qualified operation identity, declaration/input-schema revision, and review history together. A digest can identify changed bytes; it does not identify a trustworthy publisher without an authenticated source. ACC does not define a signature format, trust root, or credential field.
**Recommended:** retain valid tools during a long task rather than treating every search as a security reset. Revalidate the trusted target and applicable policy at invocation; invalidate changed or revoked entries according to the implementation's documented lifecycle. A changed description is not permission to repeat an uncertain write. Use the implementation's original-call recovery mechanism; `idempotent` does not create a recovery protocol or a guarantee that a request never reached the business system.
## 3. Responsibility and Evidence Map
The following is an interpretive mapping to selected directions in China's [Artificial Intelligence Safety Governance Framework 3.0, published 2026-09-14](https://www.cac.gov.cn/2026-09/14/c_1791137092283345.htm). References to Appendix 2 use its “II. Preventive Measures” item numbers. [Official full text](https://www.cac.gov.cn/rootimages/uploadimg/1791137114683961/1791137114683961.pdf).
The framework is a reference for this review, not the exclusive basis of ACC or an ACC certification scheme. The implementation and evidence columns below are **Recommended review patterns**; they do not assert that the referenced framework prescribes ACC or a particular product design. Applicability of laws, sector rules, and deployment duties requires a separate assessment.
| Framework direction | Existing ACC reference | Runtime responsibility | Business system responsibility | Host/deployer responsibility | Useful acceptance evidence | Guarantee not established |
|---|---|---|---|---|---|---|
| Risk review: Appendix 1; Appendix 2, II.1 | §4.4 `risk`; §4.6 per-invocation conditions | Enforce effective risk/approval policy; assess cumulative task effects separately | Review consequences using current business state | Assess application purpose, autonomy, scale, and deployment context | Owner-reviewed worksheet plus boundary and batch tests | An ACC risk value is not an application risk grade. |
| Identity and task permissions: II.2 | §§4.2–4.3 `enabled`, `scope`; §4.5 `subject` | Bind selected capabilities to verified subjects and task policy | Reauthorize the actual subject and object at call time | Establish identities, credential lifecycle, and trust across boundaries | Unselected/revoked-target denial; original identity preserved on recovery | A scope or subject identifier is not final permission or end-to-end delegation. |
| Human control: II.3 | §4.6 `approval`; §5 | Evaluate intent before invocation; bind review to target and arguments | Own approver authority and business approval rules | Supply the approval service and an unavailable/expired decision policy | Changed arguments rejected; unavailable approval cannot enable dispatch | An approval declaration is not evidence that a person approved. |
| Tool and supply-chain review: II.4 | §4.1 version; binding-native schema; §4.9 guidance; §5 | Verify approved artifacts and handle revisions without changing in-flight calls | Publish accurate operation semantics and changes | Maintain source trust, dependency checks, and vulnerability response | Publisher/revision record; altered schema and poisoned-result tests | Valid ACC metadata does not prove tool safety or supply-chain integrity. |
| Runtime controls: II.5 | §4.8 execution hints; §4.6 cumulative-effects boundary | Enforce task limits, pause new dispatch, and distinguish in-flight/unknown results | Enforce balances, inventory invariants, concurrency, and supported recovery | Isolate local execution, network access, and task credentials | Concurrent budget tests; pause-before-dispatch; original-call recovery | Frequency hints are not cumulative-impact limits; cancellation is not rollback. |
| Monitoring and data handling: II.6 | §4.7 audit; §5 | Record necessary invocation/decision/result evidence with redaction | Identify sensitive business fields and protect result access | Set retention, storage, export, incident, and verification policies | Redacted export, access tests, retention/deletion tests, tamper checks where claimed | A sensitivity hint or runtime log is not full redaction, complete history, or independent proof. |
| Decommissioning: II.7 | No ACC lifecycle field; §§4.5, 4.7 remain relevant | Stop new dispatch and retain recoverable original-call associations as appropriate | Revoke relevant grants and resolve accepted operations by business rules | Stop owned processes, revoke credentials, and retain/erase required data | Shutdown/revocation test plus an explicit account of in-flight operations | ACC cannot terminate an unmanaged host process or undo accepted business effects. |
## 4. Review Different Kinds of Risk Separately
**Normative reference:** ACC `low`, `medium`, and `high` describe the worst reasonable consequence of automatically initiating an operation under [SPEC §4.4](SPEC.md#44-risk). The framework's five application-level grades use a different assessment scope. There is no unconditional conversion table.
**Example:** editing one unpublished product draft is different from autonomously publishing changes to thousands of products. Repeating a single-object operation does not encode aggregate risk into its declaration. [SPEC §4.6](SPEC.md#46-approval) already places cumulative controls in authoritative business or policy layers.
**Recommended:** distinguish a long-lived user grant from permission for a particular task. A task may narrow that grant by service, objects, operations, fields, and time. Task termination can end its execution permission while the implementation still permits authorized inspection of an original invocation's result. Neither a task lease nor its serialized format is part of ACC v1.
**Optional:** deployments can expose task budgets, a pause control, or independently verifiable evidence. These features need their own concurrency, replay, and failure semantics. A UI label or an invocation ID alone does not establish those guarantees.
## 5. State Claims Precisely
**Recommended:** publish the ACC release, implementation revision or package hash, claimed [profile](conformance/PROFILES.md), test entrypoint, observed outcomes, and untested areas using the [self-assessment template](conformance/SELF_ASSESSMENT.md).
Passing the declaration validator or reference oracle does not test a production runtime. Framework alignment does not establish legal compliance, certification, official endorsement, or independent adoption. Evidence about one runtime does not transfer to every ACC implementation.
Data residency, retention periods, content labeling, model safety, local sandboxing, and sector-specific approval remain deployment or complementary-system concerns. ACC's audit hint does not require uploading every conversational attachment or retaining private model reasoning. Define the necessary business evidence, visible conversation records, and reusable files separately for the actual purpose and applicable rules.
---
Source: https://agentcapability.org/docs/business-risk-examples/
Repository file: examples/BUSINESS_RISK_EXAMPLES.md
---
# Catalog and Inventory Risk Worksheet
Status: Non-normative examples
Applies to: ACC v1, specification release 1.0.5
[中文](BUSINESS_RISK_EXAMPLES.zh-CN.md)
These synthetic OpenAPI services illustrate reviewed business assumptions. They are not a universal retail risk rating, implemented services, or evidence of cross-system execution. A real business owner needs to review its own data, consequences, permissions, and approval policy before adapting them. HTTP verbs and names alone do not decide risk.
- [Catalog service](openapi-catalog-service.yaml): edit a draft, publish a product, change price.
- [Inventory service](openapi-inventory-service.yaml): read stock, adjust stock.
- [Governance responsibility guide](../SAFETY_GOVERNANCE_GUIDE.md): ACC, runtime, business, and deployment boundaries.
## Example Business Assumptions
One catalog tenant uses a fixed currency. All operations require a trusted subject, and the business system independently checks that subject's current access. The draft operation cannot affect a published product or change price/stock. The publication and stock-adjustment operations always require approval. Price editing uses an illustrative absolute-price condition alongside authoritative discount and margin policies; high ACC risk does not by itself define one universal approval workflow.
The example server descriptions state obligations of a hypothetical implementation. The YAML does not enforce them. Object IDs are scoped to their respective service and tenant; matching names or IDs never link authority across systems. Synthetic values and unauthenticated placeholders are unnecessary: neither example includes credentials or a live server URL.
## Reviewed Operation Choices
Every cell below is an **Example**, not a new ACC requirement. “Reviewer” names a business role that a real adoption should assign to a responsible person.
| Operation and object | Reasonable single-operation worst consequence; external effect | ACC choice | Subject and final authority | Autonomy and batch context | Parameter and cumulative controls outside ACC | Recovery assumptions | Reviewer |
|---|---|---|---|---|---|---|---|
| `editProductDraft`: one unpublished product | Corrupt draft text/pictures and create rework; not publicly visible | `medium`; trusted subject; no unconditional ACC approval | Verified editor; catalog authorizes tenant/product and draft state | Allowed editing within a selected task; 100 edits are a separate cumulative review | Editable fields, URL policy, object set, stale-version check; count unique affected products and attempted changes under documented task policy | A business snapshot may restore a draft after version/conflict checks; not automatic rollback | Catalog owner |
| `publishProduct`: one draft and channel | Incorrect product becomes public and may be purchased | `high`; `approval.required: true` | Verified publisher; business checks approver, channel and eligibility | Human review before each invocation in this example; task approval cannot bypass it | Frozen target/channel/version; separate limits for batch publication | Taking offline limits future effects; it does not reverse purchases or prior exposure | Merchandising owner |
| `changeProductPrice`: one product | Financial loss or incorrect public pricing | `high`; `price_minor > 100000` creates conditional intent | Verified pricing subject; pricing authority checks current price, margin and discounts | Separate pricing task; forbidden in the 100-item content task below | Integer minor units; server-derived reduction; object/version checks; accumulated price exposure evaluated from business state | Restore price only after a new authorized, version-aware decision; prior purchases remain | Pricing owner |
| `getStock`: one warehouse/SKU | Reveal commercially sensitive inventory; no business mutation | `low`; `readonly: true`; `audit.sensitive: true` | Verified reader; inventory system authorizes tenant/warehouse | Read within selected warehouses; repeated reads do not grant enumeration rights | Per-object access, result minimization, query volume and export policies | Re-read if authorized; the result can legitimately change | Inventory data owner |
| `adjustStock`: one warehouse/SKU | Oversell or misstate availability, affecting orders and fulfillment | `high`; unconditional approval even when delta conditions do not match | Verified operator; inventory system checks approver and stock rules | Human review for each adjustment; separate from a read-only inventory task | Nonzero integer delta; reservations/nonnegative stock; expected version; cumulative adjustments | A repeated delta is unsafe. Reconcile the original operation; a compensating adjustment requires current-state review | Warehouse operations owner |
### Approval and Parameter Details
**Normative reference:** [SPEC §4.6](../SPEC.md#46-approval).
- `approval.required: true` is unconditional. The stock adjustment with `delta: 1` still creates approval intent; the additional conditions cannot waive it.
- When `required` is false or omitted, any matching condition creates intent. In this price example, `100001` matches and `100000` does not; these are integer minor units, not display-currency amounts. Neither outcome overrides business authorization, discount review, or stricter runtime policy.
- A string such as `"100001"` is invalid against the integer input. Do not coerce it or silently call the condition unmatched.
- The price API does not accept a model-supplied discount percentage as authority. The server computes reductions using its current price. A per-call price threshold neither measures that reduction nor limits the sum of many calls.
- Arguments stay in OpenAPI `parameters` and `requestBody`, not in ACC. `expected_version` is an example business input, not an ACC field or proof that a server implements concurrency control.
All example writes declare `idempotent: false`: this contract does not promise safe retries. A stable runtime invocation ID, an HTTP method, or an expected-version field alone does not provide business idempotence. If a write may have reached the server, use the original execution association to obtain authoritative status before deciding any next operation. The read is retryable with the same arguments, although observed stock can change.
## A Task That Uses Two Systems
**Example task:** “Update pictures and descriptions for these 100 unpublished products; read inventory to check availability; do not change prices or stock.”
**Recommended implementation worksheet**, kept outside `x-agent-capability`:
| Task item | Decision to establish before execution | Evidence to inspect |
|---|---|---|
| Original targets | Selected catalog and inventory identities, trusted subject and tenant for each; a reviewed SKU mapping if needed | No requests to unselected systems; a repeated identifier cannot select a different target |
| Permitted work | Catalog draft text/picture edits and inventory reads; explicit product/warehouse set | A price edit, stock adjustment, published-product edit, or out-of-set object is rejected |
| Batch and concurrency | Define whether budgets count objects, calls, mutations, and failures; reserve atomically before dispatch | Parallel requests cannot exceed the chosen budget; original-call recovery cannot reset or double-charge it |
| Human control | Preview task boundaries; retain original per-operation approvals; pause new dispatch on an unexpected expansion | Pausing stops new calls but accurately reports accepted, pending, failed, and unknown operations |
| Completion and recovery | Keep original target and execution references; report partial success | Unknown writes are reconciled, not silently repeated under another target |
| Evidence and data | Retain necessary decision/result records with redaction; separate conversation and file-storage policies | Credentials do not enter logs; a useful image URL does not require archiving every chat attachment |
No `task_budget`, `autonomy_level`, or object-allowlist field is added to ACC by this worksheet. The two declarations do not implement a transaction spanning systems or guarantee rollback. For existing semantic coverage and missing implementation tests, see [COVERAGE.md](../conformance/v1/COVERAGE.md).
## Validate the Declarations
From a source checkout with dependencies installed:
```bash
node bin/acc-validate.mjs examples/openapi-catalog-service.yaml
node bin/acc-validate.mjs examples/openapi-inventory-service.yaml
npm run check
```
The authoring validator checks ACC extraction and declaration/condition diagnostics; it is not a complete OpenAPI validator or a business integration test. The repository examples are not automatically included in the current npm package's explicit file list.
---
Source: https://agentcapability.org/docs/governance/
Repository file: GOVERNANCE.md
---
# Governance
ACC is maintained as an open contract, not as a product-private configuration format.
## Stewardship
ACC v1 was developed from A2B engineering work, including early implementation experience in the BailingHub project. It is maintained as an implementation-neutral open contract.
The long-term goal is to keep ACC implementation-neutral:
- A2B is the category: agents safely doing business work through existing systems.
- ACC is the capability contract for A2B.
- Any compatible runtime may implement ACC independently.
- The ACC specification should not depend on any implementation's internal database tables, UI concepts, or deployment model.
## Maintainer Neutrality Invariants
ACC is an independent standard. It is not a subproject, configuration format, sales surface, or compatibility layer owned by any product implementation.
Maintainers MUST preserve the following boundaries:
- normative behavior is defined by ACC specification artifacts, not by any implementation's current code;
- no product receives privileged semantics, registry criteria, roadmap influence, or compatibility status because of its owner or relationship with maintainers;
- implementation names appear only in clearly labeled examples, evidence, or registry entries;
- an implementation-specific design may motivate discussion, but it becomes ACC behavior only when it is portable, testable, and accepted through the contract change process;
- examples and implementer guidance must distinguish normative requirements from recommended, optional, and example architecture;
- ACC governance, versioning, and licensing must remain usable by independent open-source and commercial implementations;
- registry inclusion does not imply certification, endorsement, partnership, security review, or production-readiness approval.
Implementation history does not grant control over ACC and does not make the contract dependent on any implementation.
## Versioning
ACC uses semantic versioning for the specification.
- Patch: wording clarifications, examples, schema bug fixes that do not change meaning.
- Minor: new optional fields, new examples, or new non-breaking behavior.
- Major: required behavior changes, field meaning changes, or incompatible schema changes.
The OpenAPI binding uses:
```yaml
x-agent-capability:
version: 1
```
The `version` field is an ACC schema version, not an implementation or product version.
Repository tags identify exact specification revisions:
- `v1.0.x`: wording, guidance, examples, schema corrections, and non-breaking clarifications for ACC v1;
- `v1.x.0`: new optional, portable, non-breaking ACC v1 behavior;
- `v2.0.0`: an incompatible contract family that also requires declaration `version: 2`.
Product versions and implementation release schedules MUST NOT be reused as ACC specification versions.
## Extension Rules
ACC core fields should remain small and stable.
Add a new core field only when:
- it affects runtime governance;
- the effect is portable across runtimes;
- it can be tested by conformance checks;
- it cannot be expressed cleanly with binding-native standard fields or schemas across the target bindings;
- it does not require the ACC runtime to understand business-specific authorization logic.
Business-specific metadata should use:
- binding-native standard fields where possible;
- `guidance.context` for lightweight context tags;
- binding-specific business metadata, such as OpenAPI operation-level `x-business-*` fields;
- runtime-specific extension fields for non-portable behavior.
Unknown ACC fields must be ignored by compliant runtimes unless standardized later.
Unknown-field tolerance guarantees that a newer declaration remains parseable. It does not by itself guarantee that ignoring a new security field is safe. A field that affects exposure, approval, authority boundaries, or redaction may be added within the same major family only when:
- an older runtime ignoring it produces an equally safe or more conservative outcome; or
- the declaration includes a conservative fallback already understood by that major family.
Otherwise the change requires a new major contract family or an explicit capability-negotiation mechanism.
## Proposal Decisions
The core-field tests are necessary, not sufficient. Passing them makes a proposal eligible for review; it does not automatically place the proposal in ACC core or on a release roadmap.
Normative proposals are reviewed for:
- demonstrated need across independent implementation contexts;
- minimality and correct layer ownership;
- complete normative semantics, including defaults, precedence, and failure behavior;
- fail-safe compatibility or an explicit compatibility boundary;
- implementation evidence and machine-readable conformance vectors;
- ecosystem complexity and long-term maintenance cost.
Proposal states and submission requirements are defined in [proposals/README.md](proposals/README.md). Accepted proposals still ship only through the normal versioning and release process.
## Implementations
ACC implementations may include runtime features that are not part of ACC.
When an implementation feature becomes generally useful as a portable declaration, it can be proposed for ACC only after the contract boundary is clear.
Implementations register through public self-assessment evidence under the same criteria. The registration process is defined in [conformance/SELF_ASSESSMENT.md](conformance/SELF_ASSESSMENT.md).
## Implementation Evidence
Observed implementation failures can improve guidance, but evidence must be labeled accurately:
- specification-derived invariants may be documented immediately;
- experience from one implementation must be labeled as an example, not an ecosystem-wide pattern;
- normative changes require portable semantics and conformance evidence;
- an implementation's operational modules, workflow, storage, transport, and UI remain outside ACC unless separately standardized.
## Release Planning
Public milestones should communicate planned contract and documentation work. Release timing must not be coupled to a product release schedule.
Documentation-only guidance and non-normative examples may ship in patch releases. New optional normative behavior requires a minor release; incompatible semantics require a major release.
## Attribution
Projects implementing ACC may cite the historical source as:
```text
ACC (Agent Capability Contract), first published by the BailingHub project.
```
Implementations may say:
```text
Implements the ACC v1 Runtime Profile.
```
They may not imply official certification unless a certification program exists.
---
Source: https://agentcapability.org/docs/contributing/
Repository file: CONTRIBUTING.md
---
# Contributing
ACC is a contract. Changes should prioritize compatibility, clarity, and implementation neutrality.
Normative field or behavior proposals should follow the public process in [proposals/README.md](proposals/README.md) and begin from [proposals/TEMPLATE.md](proposals/TEMPLATE.md).
## What Belongs In ACC
Good candidates:
- portable governance fields;
- behavior that can be implemented by multiple runtimes;
- behavior that can be tested by a conformance checklist;
- clarifications that make implementations more consistent;
- examples that teach safe integration patterns.
Poor candidates:
- implementation-specific table names, console UI fields, or deployment assumptions;
- business-specific approval workflows;
- provider-specific model behavior;
- fields that duplicate binding-native request or response schemas;
- fields that silently change security behavior without testable semantics.
## Change Process
For wording and examples:
1. Update the relevant markdown file.
2. Keep terminology consistent with `SPEC.md`.
3. Add or adjust an example if the change affects implementers.
For schema or normative behavior:
1. Submit a proposal that explains the portable problem and why existing fields cannot solve it.
2. Complete layer-boundary, compatibility, security, and implementation-evidence review.
3. After acceptance, update `SPEC.md`.
4. Update `schemas/acc.v1.schema.json` if the field is machine-readable.
5. Add conformance notes.
6. Add an example.
7. Add a `CHANGELOG.md` entry.
8. Add machine-readable conformance vectors for portable parser or runtime behavior.
Submitting a proposal does not place it on the roadmap. Proposal authors may provide a self-assessment, but status is recorded through public governance review with rationale.
## Neutrality Review
Every contract, guidance, example, conformance, and registry change should answer:
1. Does this text work for an implementation with a different language, owner, architecture, storage model, and deployment topology?
2. Is every product-specific concept clearly labeled as an example rather than ACC behavior?
3. Are normative requirements separated from recommendations and optional platform features?
4. Can the behavior be tested without depending on one implementation's private state or UI?
5. Does the change preserve the boundary between ACC reach and business-system authority?
6. Would the same registry and contribution criteria apply to an unrelated implementation?
A proposal that fails this review belongs in implementation documentation, not ACC core.
## Compatibility Rule
ACC v1 should remain backward-compatible.
Do not change the meaning of an existing field in a patch or minor release. Add optional fields instead.
An optional field is not safely backward-compatible merely because an older parser ignores it. If the field affects exposure, approval, authority boundaries, or redaction, the proposal must show that ignoring it is fail-safe or provide a conservative fallback understood by older ACC v1 runtimes. Otherwise propose a new major compatibility family.
## Language
Use "agent" for the actor that may call a business capability.
Use "model" only when specifically discussing model selection, model output, or model-readable guidance.
Use implementation names only when discussing a concrete implementation, not when defining ACC itself.
---
Source: https://agentcapability.org/docs/implementations/
Repository file: IMPLEMENTATIONS.md
---
# ACC Implementations
This document is an open registry of projects that publicly declare ACC support.
The registry is implementation-neutral. Entries are ordered alphabetically and evaluated under the same evidence rules regardless of language, architecture, owner, commercial model, or relationship with ACC maintainers.
Registry inclusion is not official certification, a security audit, production-readiness endorsement, partnership, or commercial recommendation.
## Registered Implementations
| Project | Profile | ACC version | Status | Last assessed | Evidence | Notes |
|---|---|---|---|---|---|---|
| [BailingHub](https://github.com/bailinghub/bailinghub) | Runtime | v1 | Self-declared | 2026-07-11 | [ACC implementation](https://github.com/bailinghub/bailinghub/blob/main/docs/TOOLS_MODEL.md) | First public implementation used to validate the initial contract; its product architecture does not define ACC semantics. |
## Register an Implementation
Projects are welcome to register through a pull request:
1. choose a claim from [conformance/PROFILES.md](conformance/PROFILES.md);
2. publish a dated self-assessment using [conformance/SELF_ASSESSMENT.md](conformance/SELF_ASSESSMENT.md);
3. provide public evidence and known limitations;
4. add one alphabetically ordered row to the registry table.
Maintainers verify submission completeness, evidence reachability, claim scope, and neutral wording. They do not certify the implementation's security or production readiness.
## Available Profiles
| Profile | Meaning |
|---|---|
| ACC binding parser | Extracts and validates ACC declarations from a named binding, such as OpenAPI `x-agent-capability`. |
| ACC binding generator | Produces a named ACC binding while keeping business parameters in the carrier protocol's standard schemas. |
| ACC runtime | Applies exposure, governance, authority-boundary, and traceability semantics. |
| ACC policy component | Enforces a named subset of ACC semantics for another runtime or gateway. |
An implementation may support only part of the lifecycle and still be useful, as long as its profile and limitations are explicit.
Recommended claim language:
```text
Implements the ACC v1 Runtime Profile.
```
Avoid:
```text
ACC certified.
Official ACC implementation.
```
---
Source: https://agentcapability.org/docs/bindings/
Repository file: bindings/README.md
---
# ACC Binding Requirements
Status: Normative requirements for ACC v1 bindings
ACC Core defines the portable declaration object and its governance semantics. A binding defines how that object is carried by, resolved from, and validated against another protocol or interface description.
OpenAPI is the first standardized ACC v1 binding. It is not part of the identity of ACC Core, and future bindings MUST NOT redefine core field meaning.
## 1. Core And Binding Responsibilities
ACC Core defines:
- the `version`, `enabled`, `scope`, `risk`, `subject`, `approval`, `audit`, `execution`, and `guidance` fields;
- field defaults, precedence, failure behavior, and compatibility rules;
- the JSON value model used by portable approval-condition evaluation;
- runtime invariants that do not depend on one carrier protocol.
Each binding defines:
- the carrier object and placement of the ACC declaration;
- the operation granularity and stable operation reference used by the binding;
- how native input schemas and invocation values map to the ACC JSON value model;
- how `approval.when.param` paths resolve against native input definitions;
- how native descriptions, examples, lifecycle markers, and behavioral annotations interact with ACC metadata;
- extraction, validation, unsupported-version, and diagnostic behavior;
- binding-specific parser or generator conformance evidence.
When a carrier protocol provides standard schema or description mechanisms, bindings MUST reuse them. Bindings MUST NOT turn ACC into a duplicate request or response schema language.
## 2. Validated Capability Artifact
A binding parser produces or supplies the equivalent of a validated capability artifact containing:
- the ACC declaration object;
- a binding-qualified operation reference;
- the bound input schema needed for argument validation and condition resolution;
- the binding name and supported binding version;
- diagnostics produced during extraction and validation.
This is a conceptual interface, not a required storage format or wire object. Implementations MAY represent it with generated code, an in-memory model, a gateway route, or another equivalent structure.
A core runtime MAY consume this validated artifact without implementing the source binding itself. A runtime that also parses a binding MUST satisfy both the core runtime requirements and the applicable binding profile.
## 3. Input And Value Mapping
ACC condition evaluation uses JSON types and strict JSON equality. A binding MUST define a deterministic mapping from its native input model to:
- object;
- array;
- string;
- finite number;
- boolean;
- null.
If a native type, field-presence rule, reference, or numeric value cannot be represented faithfully, the binding MUST reject or skip the affected declaration with diagnostics. It MUST NOT silently coerce values in a way that changes approval-condition outcomes.
The binding MUST define whether parameter paths address a combined argument object, separate parameter locations, or another normalized input view. Two conforming implementations of the same binding MUST resolve the same path to the same declared input.
## 4. Native Metadata And Precedence
A binding MUST document every mapping between ACC and semantically related native metadata.
- Native request and response schemas remain authoritative for API shape.
- Native restrictions MUST NOT be weakened by ACC metadata.
- Agent-specific `guidance` MAY supplement native descriptions, but MUST NOT replace a declared input or output schema.
- Native behavioral annotations MAY be mapped into ACC only when the binding defines trust, precedence, defaults, and conservative failure behavior.
- Unknown native or ACC extension fields MUST NOT silently change exposure, risk, subject, approval, audit, or execution behavior.
Bindings MUST NOT infer final business authorization from carrier-protocol metadata.
## 5. Exposure And Failure
Every binding MUST preserve these core outcomes:
- `enabled: false` is never exposed as an agent-callable capability;
- an empty or missing `scope` is invalid for exposure;
- unsupported ACC major versions are rejected or skipped with diagnostics;
- insufficient input schema for safe invocation causes the operation to be skipped or rejected;
- binding extraction failure never creates a less-governed fallback tool.
A binding MAY define additional conservative rejection conditions required by its native protocol. It MUST NOT redefine the meaning of an existing ACC core field.
## 6. Binding Conformance
A binding specification MUST provide:
- at least one minimal valid declaration;
- placement and extraction examples;
- native type and parameter-path mapping rules;
- malformed, unsupported-version, unresolved-reference, and insufficient-schema outcomes;
- machine-readable parser vectors before a stable compatibility claim;
- claim language that names the binding and version.
The current OpenAPI mapping is defined in [OpenAPI Binding](openapi.md).
---
Source: https://agentcapability.org/docs/openapi-binding/
Repository file: bindings/openapi.md
---
# OpenAPI Binding
Status: Normative ACC v1 binding
Applies to: OpenAPI operation objects carrying ACC v1 declarations
This binding conforms to the common [ACC Binding Requirements](README.md). It defines carrier-specific placement, extraction, input mapping, and parser behavior; it does not redefine ACC Core fields.
ACC v1 is bound to OpenAPI through the operation-level extension field:
```yaml
x-agent-capability:
version: 1
enabled: true
scope: order.read
```
## Placement
The extension MUST be placed on an OpenAPI operation object.
```yaml
paths:
/orders/{id}:
get:
operationId: order_get
summary: Query one order by ID.
x-agent-capability:
version: 1
enabled: true
scope: order.read
```
The extension SHOULD NOT be placed at the root, path item, schema, parameter, or response level.
## Extraction And Exposure
An OpenAPI operation is ACC-declared when its operation object contains `x-agent-capability`.
The parser MUST extract the extension value as the ACC declaration object and retain a binding-qualified reference to the source operation. An operation is eligible for exposure only when:
- `x-agent-capability.enabled` is `true`;
- `x-agent-capability.scope` is present and non-empty;
- the runtime's route or policy allows that scope;
- the OpenAPI operation provides enough parameter or request-body schema for safe invocation.
Malformed extension values, unsupported ACC major versions, and insufficient input schemas MUST be rejected or skipped with diagnostics. A parser MUST NOT fall back to exposing the same operation as an ungoverned tool.
## What Belongs In OpenAPI
Keep standard API shape in standard OpenAPI fields:
- path and method;
- `operationId`;
- `summary` and `description`;
- `parameters`;
- `requestBody`;
- `responses`;
- standard JSON Schema definitions.
ACC does not replace OpenAPI.
## Input And Value Mapping
The bound input view consists of the operation's resolved standard OpenAPI `parameters` and `requestBody` schema. Implementations MUST declare which OpenAPI versions they support and MUST apply their documented `$ref` resolution behavior consistently.
`approval.when.param` MUST resolve to a declared input in that bound view. Nested paths use the ACC dot-notation rules from the core specification. If parameters from different OpenAPI locations would produce an ambiguous normalized path, the parser MUST reject the affected condition with diagnostics rather than choose one silently.
OpenAPI and JSON Schema string, number, integer, boolean, array, object, and null values map to the corresponding ACC JSON value types. Comparison behavior remains strict and type-aware as defined by ACC Core.
An unresolved reference, unsupported schema construct, non-finite numeric value, or invocation value incompatible with the declared schema MUST NOT be silently coerced into a value that changes an approval outcome.
For the ACC risk default, an OpenAPI `GET` operation is treated as the binding-native readonly signal when `execution.readonly` and `risk.level` are both omitted. An explicit `execution.readonly` or `risk.level` declaration takes precedence. Other operations not declared readonly default to `medium` risk under ACC Core.
## What Belongs In ACC
Place agent governance metadata in `x-agent-capability`:
- exposure switch;
- scope;
- risk;
- subject requirement;
- approval intent;
- audit sensitivity;
- execution hints;
- agent guidance.
`guidance` is supplemental agent-selection metadata:
- `guidance.when_to_use` MAY add agent-specific selection context that is not already clear from `summary` or `description`;
- `guidance.returns` MUST NOT replace or contradict standard OpenAPI `responses` schemas;
- `guidance.examples` MUST NOT replace standard parameter, request-body, or schema examples;
- OpenAPI schema remains authoritative for request and response shape;
- no guidance field is authorization or security policy.
## Extension Bags
Business-specific metadata should not be added as new ACC core fields unless it has portable governance meaning.
Use operation-level extensions such as:
```yaml
x-business-owner: trade-team
x-business-policy:
approval_scene: order_over_limit
```
ACC-compatible runtimes may preserve these fields, but must not silently treat them as security rules.
## Minimal Valid Declaration
```yaml
x-agent-capability:
version: 1
enabled: true
scope: member.read
```
Runtimes should apply safe defaults for omitted fields.
## Recommended Declaration
```yaml
x-agent-capability:
version: 1
enabled: true
scope: member.read
risk:
level: low
subject:
required: true
execution:
readonly: true
idempotent: true
guidance:
when_to_use: Use when the user asks for a member profile.
returns: Returns member name, level, tags, and last visit time.
```
## Write Operation Example
```yaml
x-agent-capability:
version: 1
enabled: true
scope: refund.request.create
risk:
level: medium
subject:
required: true
approval:
when:
- param: amount
op: ">"
value: 1000
label: Refund amount exceeds 1000.
audit:
sensitive: true
execution:
readonly: false
idempotent: false
```
`approval.when` uses ANY semantics: when `approval.required` is false or omitted, any matching item creates an approval intent. `approval.required: true` remains unconditional and cannot be reduced by `approval.when`.
## OpenAPI Parser Conformance
An implementation claiming the ACC v1 OpenAPI Binding Parser Profile MUST:
- read `x-agent-capability` only from OpenAPI operation objects;
- validate required ACC fields and supported major versions;
- preserve the resolved OpenAPI input schema needed for invocation validation;
- resolve `approval.when.param` against declared operation inputs;
- preserve unknown ACC and operation-level extension metadata without assigning it implicit security meaning;
- emit diagnostics for malformed declarations, unresolved parameter targets, unsupported schema constructs, and skipped operations.
The implementation SHOULD run the OpenAPI-oriented vectors in [../conformance/v1](../conformance/v1/README.md) and publish the supported OpenAPI versions in its self-assessment.
## Non-Goals
The OpenAPI binding does not define:
- how a runtime signs tool calls;
- where approval is completed;
- how subjects are encoded;
- how route allowlists are stored;
- how audit records are persisted.
Those are runtime concerns. ACC defines the declaration, not the whole control plane.
The reasoning behind these boundaries is documented in [Design Rationale And Boundaries](../DESIGN_RATIONALE.md).
---
Source: https://agentcapability.org/docs/conformance/
Repository file: conformance/README.md
---
# ACC Conformance Checklist
This checklist records ACC v1 OpenAPI Binding and core runtime responsibilities. Before making a compatibility claim, select the applicable binding Parser, binding Generator, Runtime, or Policy Component profile in [PROFILES.md](PROFILES.md).
Use [SELF_ASSESSMENT.md](SELF_ASSESSMENT.md) to publish evidence and register an implementation. ACC currently uses self-assessment, not official certification.
OpenAPI parser implementations normally complete the Parser section. Runtime implementations complete every applicable section for the bindings they support. Generator and Policy Component requirements are defined in their profiles because they do not own the full runtime lifecycle.
## OpenAPI Binding Parser
- [ ] Reads `x-agent-capability` from OpenAPI operation objects.
- [ ] Requires `version`, `enabled`, and `scope`.
- [ ] Skips or reports unsupported `version` values.
- [ ] Preserves OpenAPI `parameters` and `requestBody` schemas.
- [ ] Ignores unknown ACC fields safely.
- [ ] Preserves implementation-specific extensions without treating them as security policy.
## Exposure
- [ ] Does not expose operations with `enabled: false`.
- [ ] Does not expose operations without a non-empty `scope`.
- [ ] Applies route or policy allowlists using `scope`.
- [ ] Hides `subject.required` capabilities when no trusted acting subject exists.
- [ ] Provides diagnostics for skipped operations.
## Governance
- [ ] Applies safe risk defaults.
- [ ] Detects `risk.level: high` before invocation.
- [ ] Detects `approval.required` before invocation.
- [ ] Treats `approval.required: true` as unconditional approval intent.
- [ ] Evaluates `approval.when` with ANY semantics when unconditional approval is not required.
- [ ] Treats an absent or empty `approval.when` as no conditional approval intent.
- [ ] Requires every `approval.when.param` to resolve to a declared, typed input in the bound OpenAPI operation.
- [ ] Uses strict JSON type-aware comparison for approval conditions; does not coerce strings into numbers or booleans.
- [ ] Rejects a condition parameter whose invocation value is incompatible with its declared schema before calling the business operation.
- [ ] Applies `execution.rate_limit` or maps it to runtime limits.
- [ ] Applies `execution.timeout_ms` or maps it to runtime timeout policy.
- [ ] Treats `audit.sensitive` as a redaction or summarization hint.
## Authority Boundary
- [ ] Does not treat ACC as final business authorization.
- [ ] Propagates or requires a trusted acting subject when `subject.required` is true.
- [ ] Lets the business system decide whether the subject may perform the operation.
- [ ] Does not allow model-generated text to override scope, risk, approval, subject, or audit decisions.
## Traceability
- [ ] Records which ACC capability was exposed.
- [ ] Records risk and approval decisions.
- [ ] Records invocation result or failure summary.
- [ ] Redacts sensitive values when requested.
Machine-readable ACC v1 inputs and abstract expected outcomes are available in [v1/README.md](v1/README.md). They complement this checklist; they do not create an official certification program.
## Claim Language
Recommended wording:
```text
This project implements the ACC v1 OpenAPI Binding Parser Profile.
```
Avoid:
```text
This project is officially ACC certified.
```
There is no certification program until one is explicitly published by the ACC maintainers.
---
Source: https://agentcapability.org/docs/conformance-profiles/
Repository file: conformance/PROFILES.md
---
# ACC Conformance Profiles
Status: Non-normative claim framework
Applies to: ACC v1
Profiles let implementations make precise compatibility claims without pretending that every parser, generator, gateway, and runtime has the same responsibilities. Profiles do not add semantics to ACC; they group existing requirements from [../SPEC.md](../SPEC.md) and [README.md](README.md).
## 1. Claim Format
Recommended public wording:
```text
Implements the ACC v1 OpenAPI Binding Parser Profile.
Implements the ACC v1 OpenAPI Binding Generator Profile.
Implements the ACC v1 Runtime Profile.
Implements the ACC v1 Policy Component Profile for: risk, approval, audit.
```
An implementation should include:
- the ACC major version;
- the claimed profile;
- a dated self-assessment;
- evidence links;
- unsupported optional fields or known limitations.
Parser and generator claims MUST name their binding. Future bindings define their own extraction, native-schema mapping, and binding-specific evidence under [Binding Requirements](../bindings/README.md).
Do not use `ACC certified` or imply review by an independent certification body.
## 2. OpenAPI Binding Parser Profile
For libraries or tools that read ACC declarations from OpenAPI operations.
Minimum behavior:
- reads `x-agent-capability` from OpenAPI operation objects;
- validates required fields and supported versions;
- preserves standard OpenAPI parameter and request-body schemas;
- validates typed `approval.when` references when that field is supported;
- ignores unknown ACC fields safely;
- preserves non-ACC extensions without giving them implicit security meaning;
- emits diagnostics for invalid or unsupported declarations.
A parser does not claim to enforce runtime governance.
## 3. OpenAPI Binding Generator Profile
For SDKs, annotations, code generators, or authoring tools that produce ACC declarations.
Minimum behavior:
- emits declarations that validate against the ACC v1 schema;
- emits `version`, `enabled`, and a non-empty `scope`;
- keeps business parameters in standard OpenAPI schemas;
- emits typed parameters for every generated `approval.when.param`;
- preserves strict JSON value types in generated conditions;
- does not generate unknown fields that silently change ACC security behavior;
- identifies the ACC version used by generated artifacts.
A generator does not claim that a downstream runtime enforces the generated metadata.
## 4. Runtime Profile
For runtimes, control planes, or gateways that expose and invoke ACC-declared capabilities.
Minimum behavior:
- satisfies an applicable binding Parser Profile or consumes an equivalent validated capability artifact;
- applies exposure semantics for `enabled`, `scope`, and trusted-subject availability;
- applies safe risk defaults;
- evaluates `approval.required` and `approval.when` before invocation;
- validates arguments against the binding-native input schema without implicit coercion that changes ACC JSON values;
- maps timeout and rate-limit hints to documented runtime policy;
- preserves the boundary between capability reach and final business authorization;
- prevents model-controlled input from overriding governance metadata;
- records capability, governance decision, result/failure summary, and requested redaction;
- emits diagnostics for skipped or unsupported declarations;
- evaluates `approval.when` with ANY semantics and keeps unconditional `approval.required` dominant.
The Runtime Profile does not require an LLM, UI, database, queue, signature algorithm, cost system, or approval product.
## 5. Policy Component Profile
For components that evaluate a documented subset of ACC on behalf of another runtime, such as a gateway plugin or policy engine.
The claim must name every supported area, for example:
```text
Implements the ACC v1 Policy Component Profile for risk, approval, and audit.
```
Minimum behavior:
- documents which ACC fields it consumes and which component supplies the remaining lifecycle;
- follows the same field semantics and type rules as ACC v1;
- fails safely when required context is missing;
- does not claim full Runtime Profile compatibility;
- publishes integration evidence showing where its decision is enforced.
## 6. Evidence Levels
Self-assessments may provide:
| Evidence | Meaning |
|---|---|
| Documentation | Public explanation of supported fields and limitations. |
| Examples | Reproducible ACC inputs and resulting artifacts or decisions. |
| Tests | Automated tests linked to checklist items. |
| Interoperability | Evidence that declarations produced or consumed by another implementation behave consistently. |
Evidence depth may vary, but unsupported behavior must not be hidden.
Machine-readable reference vectors under [v1](v1/README.md) may be used as reproducible evidence. A result should identify the corpus specification release, applicable vectors, implementation version or commit, skipped vectors, and known limitations.
## 7. Version Maintenance
A profile claim applies only to the named ACC version. Implementations should reassess when ACC adds normative behavior that affects the profile and should update or remove stale registry entries.
---
Source: https://agentcapability.org/docs/self-assessment/
Repository file: conformance/SELF_ASSESSMENT.md
---
# ACC Implementation Registration and Self-Assessment
Status: Non-normative process
Applies to: ACC v1
ACC uses open registration backed by self-assessment evidence. It does not currently operate a certification program.
## 1. Registration Process
1. Choose a profile from [PROFILES.md](PROFILES.md).
2. Copy the template below into the implementation's public repository.
3. Complete the applicable checks in [README.md](README.md).
4. Link documentation, examples, tests, and known limitations.
5. Submit a pull request updating [../IMPLEMENTATIONS.md](../IMPLEMENTATIONS.md).
6. Reassess when the claimed ACC version or implementation behavior changes.
Maintainers review whether the submission is complete, accurately scoped, publicly verifiable, and neutrally worded. Registry inclusion is not a security audit, production-readiness guarantee, endorsement, partnership, or official certification.
## 2. Self-Assessment Template
```markdown
# ACC Self-Assessment
- Project:
- Public repository:
- Maintainer:
- Assessment date: YYYY-MM-DD
- ACC version: v1
- Claimed profile: Binding Parser / Binding Generator / Runtime / Policy Component
- Binding and binding version:
- Implementation version or commit:
- Distributed package SHA-256, if applicable:
- License:
## Supported Surface
- Supported ACC fields:
- Unsupported optional fields:
- Supported carrier-protocol versions:
- Runtime or integration assumptions:
- Conformance corpus release:
- Conformance corpus commit or SHA-256:
- Public interface / adapter entrypoint and command:
- Applicable vectors passed / failed / skipped / not run:
- Per-skip reason (not applicable versus applicable but unsupported):
## Conformance Evidence
| Checklist area | Status | Evidence link | Notes |
|---|---|---|---|
| Binding Parser | Pass / Partial / Fail / Not run / N/A | | |
| Exposure | Pass / Partial / Fail / Not run / N/A | | |
| Governance | Pass / Partial / Fail / Not run / N/A | | |
| Authority Boundary | Pass / Partial / Fail / Not run / N/A | | |
| Traceability | Pass / Partial / Fail / Not run / N/A | | |
| Machine-readable vectors via implementation adapter | Pass / Partial / Fail / Not run / N/A | | |
## Corpus Maintenance Check (Separate From Implementation Evidence)
- Reference oracle command/date/result, if run:
- This result checks corpus consistency; it does not execute the claimed implementation.
## Known Limitations
-
## Declaration
This is a self-assessment by the project maintainers. It does not claim official ACC certification, an independent security audit, or production-readiness endorsement.
```
## 3. Registry Entry Template
Use [the coverage index](v1/COVERAGE.md) to separate abstract vector outcomes from integration evidence. Record `Not run` when an applicable interface was not exercised; do not count reference-oracle success as a runtime pass. A claimed `N/A` needs a profile or scope reason, and unsupported applicable behavior needs an explicit limitation.
Add one row to the alphabetically ordered table in `IMPLEMENTATIONS.md`:
```markdown
| Project | Profile | ACC version | Status | Last assessed | Evidence | Notes |
|---|---|---|---|---|---|---|
| Example | Runtime | v1 | Self-declared | YYYY-MM-DD | [Assessment](https://example.com/assessment) | Short neutral description. |
```
## 4. Acceptance Criteria
A registry pull request should be accepted when:
- the project and evidence are publicly reachable;
- the claim names an ACC version and profile;
- the self-assessment is dated and tied to an implementation version or commit;
- partial support and known limitations are explicit;
- the description does not imply certification or official partnership;
- the implementation is not using ACC terminology deceptively.
Maintainers should not require a particular language, product architecture, deployment model, commercial relationship, or affiliation with any existing implementation.
## 5. Removal and Updates
An entry may be marked stale or removed when its links no longer work, the project no longer claims ACC support, the evidence materially contradicts the claim, or maintainers do not respond to a documented update request.
Removal from the registry does not restrict anyone from implementing or using ACC under its license.
---
Source: https://agentcapability.org/docs/conformance-v1/
Repository file: conformance/v1/README.md
---
# ACC v1 Machine-Readable Conformance Vectors
Status: Reference conformance corpus
Specification release: 1.0.5
Declaration compatibility family: ACC v1
This directory publishes portable declaration inputs, core runtime outcomes, and OpenAPI-specific default cases for the ACC v1 OpenAPI Binding Parser and Runtime profiles. Core-only consumers may reuse the vectors whose inputs do not depend on `http_method` or another binding-native signal.
The vectors complement the human checklist in [../README.md](../README.md). They do not prescribe an implementation API, database, queue, approval UI, logging backend, or hash algorithm, and passing them is not official certification.
## Files
- `vectors.schema.json`: schema for the corpus format.
- `vectors.json`: versioned parser and runtime cases.
- `../../scripts/check-conformance.mjs`: reference oracle used to verify that the corpus is internally consistent.
- [Coverage and implementation evidence](COVERAGE.md) ([中文](COVERAGE.zh-CN.md)): all 26 vector IDs, their limits, and the integration evidence they do not replace.
## Abstract Kinds
| Kind | Portable observation |
|---|---|
| `declaration` | Whether the ACC object is structurally valid and whether its major version is supported. |
| `exposure` | Whether a capability may be exposed for the supplied scope policy and trusted-subject availability. |
| `approval` | Whether valid invocation arguments allow execution, require approval, or must be rejected. |
| `risk-default` | The effective ACC risk when it is explicit or inferred from method and readonly hint. |
| `audit-hint` | Whether the broad ACC sensitivity hint is present. |
## Using The Corpus
An implementation may write an adapter that:
1. reads each vector applicable to its claimed Profile;
2. maps the abstract input into its public parser or runtime interface;
3. observes the abstract outcome;
4. compares it with `expected`;
5. publishes the ACC release, implementation version, passed vectors, skipped vectors, and known limitations.
Diagnostics may use implementation-specific wording. The corpus compares portable categories and decisions, not private error messages.
## Security Scope
The corpus deliberately avoids product-specific behavior. For example, approval evidence must remain bound to the reviewed capability and arguments, but ACC does not require one hash algorithm or persistence model. Such invariants belong in portable behavior vectors only after they are normative in [../../SPEC.md](../../SPEC.md).
---
Source: https://agentcapability.org/docs/conformance-coverage/
Repository file: conformance/v1/COVERAGE.md
---
# ACC v1 Coverage and Implementation Evidence
Status: Non-normative coverage index
Corpus: `vectors.json`, format version 1, specification release 1.0.5
[中文](COVERAGE.zh-CN.md)
This index describes the existing 26 reference vectors without changing their expected outcomes or the reference oracle. Normative obligations and recommendations remain in [SPEC.md](../../SPEC.md) and the [OpenAPI binding](../../bindings/openapi.md). Choose the applicable [Profile](../PROFILES.md) first.
## What Each Layer Proves
- `npm run conformance:check` checks the corpus against the reference oracle. Success is **corpus internal consistency**, not acceptance of a gateway, SDK, or production runtime.
- An implementation adapter needs to feed applicable vectors through its public interface and observe expected outcomes. Implementation evidence here is **Not run** because this index does not execute an external implementation.
- Integration evidence is needed to show actual dispatch gating, correct subjects, redacted persistence, and failure recovery. The [self-assessment template](../SELF_ASSESSMENT.md) keeps these claims separate.
`allow` in approval vectors means the tested condition does not create approval intent; it does not grant final permission. `scope_allowed` and `trusted_subject` are supplied abstract inputs, not verified identities or network observations.
## Existing Vectors
Every row has an abstract vector. The last two columns concern a real implementation, not the oracle. Section references point to SPEC except where the OpenAPI binding is named.
| ID | Existing semantic reference | Abstract observation covered | Expected outcome | Additional implementation evidence | Implementation status |
|---|---|---|---|---|---|
| `T-PARSE-01` | §§4.1–4.3, 6 | A minimal ACC v1 declaration is valid. | `valid=true` | Parser interface extraction and diagnostics | Not run |
| `T-PARSE-02` | §§4.1–4.3, 6 | A declaration without scope is invalid. | `valid=false, diagnostic="invalid_declaration"` | Parser interface extraction and diagnostics | Not run |
| `T-PARSE-03` | §§4.1–4.3, 6 | An unsupported major version is rejected or skipped with diagnostics. | `valid=false, diagnostic="unsupported_version"` | Parser interface extraction and diagnostics | Not run |
| `T-PARSE-04` | §§4.1–4.3, 6 | An unknown field is ignored without making the declaration invalid. | `valid=true` | Parser interface extraction and diagnostics | Not run |
| `T-PARSE-05` | §§4.1–4.3, 6 | A declaration without a version is invalid rather than classified as an unsupported version. | `valid=false, diagnostic="invalid_declaration"` | Parser interface extraction and diagnostics | Not run |
| `T-EXPOSE-01` | §§4.2–4.3, 4.5, 5 | A disabled capability is not exposed. | `exposed=false` | Real target/subject checks and dispatch boundary | Not run |
| `T-EXPOSE-02` | §§4.2–4.3, 4.5, 5 | A subject-required capability is not exposed without a trusted subject. | `exposed=false` | Real target/subject checks and dispatch boundary | Not run |
| `T-EXPOSE-03` | §§4.2–4.3, 4.5, 5 | A capability outside the runtime scope policy is not exposed. | `exposed=false` | Real target/subject checks and dispatch boundary | Not run |
| `T-EXPOSE-04` | §§4.2–4.3, 4.5, 5 | An enabled and allowed capability with required subject available is exposed. | `exposed=true` | Real target/subject checks and dispatch boundary | Not run |
| `T-APPROVAL-01` | §4.6 | approval.required true creates approval intent even when a condition does not match. | `decision="approval_required"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-02` | §4.6 | The first matching approval.when item is sufficient under ANY semantics. | `decision="approval_required"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-03` | §4.6 | A later matching approval.when item is sufficient under ANY semantics. | `decision="approval_required"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-04` | §4.6 | No conditional approval intent is created when no approval.when item matches. | `decision="allow"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-05` | §4.6 | An invocation value incompatible with its bound input schema is rejected before condition evaluation. | `decision="reject_invalid_arguments"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-06` | §4.6 | An empty approval.when array creates no conditional approval intent. | `decision="allow"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-07` | §4.6 | The in operator matches a parameter that is strictly JSON-equal to one array member. | `decision="approval_required"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-08` | §4.6 | The in operator does not coerce a JSON number into a string. | `decision="allow"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-09` | §4.6 | The contains operator uses substring matching for a string parameter and string value. | `decision="approval_required"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-10` | §4.6 | The contains operator uses strict JSON equality for members of an array parameter. | `decision="approval_required"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-11` | §4.6 | Array containment does not coerce a JSON number element into a string. | `decision="allow"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-12` | §4.6 | The exists operator matches a path that resolves to a non-null JSON value. | `decision="approval_required"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-13` | §4.6 | The exists operator does not match a path that is absent from the invocation input. | `decision="allow"` | Decision interface plus argument/dispatch binding | Not run |
| `T-APPROVAL-14` | §4.6 | The exists operator does not match an explicit JSON null value. | `decision="allow"` | Decision interface plus argument/dispatch binding | Not run |
| `T-RISK-01` | §4.4; [OpenAPI input mapping](../../bindings/openapi.md#input-and-value-mapping) | Under the OpenAPI binding, a GET operation defaults to low risk when risk and execution.readonly are omitted. | `effective_risk="low"` | Binding mapping and effective policy preservation | Not run |
| `T-RISK-02` | §4.4; [OpenAPI input mapping](../../bindings/openapi.md#input-and-value-mapping) | A non-readonly write operation defaults to medium risk when risk is omitted. | `effective_risk="medium"` | Binding mapping and effective policy preservation | Not run |
| `T-AUDIT-01` | §4.7 | The broad audit sensitivity hint is preserved as true. | `audit_sensitive=true` | Hint propagation; separate redacted-persistence test | Not run |
Inventory: declaration 5; exposure 4; approval 14; risk defaults 2; audit hint 1. Total: **26**.
## Where the Corpus Stops
The corpus does not exhaust every rule or checklist item. An absence below does not remove a normative obligation, and a recommended deployment control does not become an ACC requirement merely because it appears here.
| Concern | Existing reference / status | Abstract corpus coverage | Evidence still needed | Implementation evidence |
|---|---|---|---|---|
| Approval operators and defaults outside the supplied cases | SPEC §§4.4, 4.6; OpenAPI binding | Partial: sample values, not every operator/type/default combination | Boundary and invalid-input tests for the claimed surface | Not run |
| Timeout and rate-limit hint mapping | SPEC §4.8 hints; mapping is implementation policy | None | Effective windows/timeouts and observed mapped behavior | Not run |
| Final business authorization and cross-hop subject verification | SPEC §§2.1, 4.5, 5 | Abstract exposure booleans only | Actual revoked, forged, wrong-tenant and wrong-object decisions at each authority | Not run |
| Model/tool-result text cannot override governance | SPEC §§4.9, 5 | None | Adversarial input through actual ingestion, selection and dispatch interfaces | Not run |
| Approval intent versus completed approval | SPEC §4.6; implementer guide §7 recommends binding | Abstract intent only | Approver authority, frozen target/arguments, expiry and failure observations | Not run |
| Cumulative business effects | SPEC §4.6; enforcement belongs to business/policy layer | None | Concurrent/batch tests using authoritative state and documented limits | Not run |
| Sensitive hints versus actual logs | SPEC §4.7; retention/verification are deployment policies | Presence of one broad hint only | Redaction before persistence/export; access, completeness and retention tests; independent verification if claimed | Not run |
| Uncertain writes, cancellation, restart and replay | Implementation recovery policy; §4.8 idempotence is a hint | None | Preserve original call/target; inspect accepted/unknown effects; demonstrate no unsafe replay | Not run |
| Source trust, local sandboxing, task shutdown and data residency | Complementary implementation/deployment controls, not ACC fields | None | Named ownership, policy and deployment-specific integration evidence | Not run |
A generator also needs evidence of its emitted binding-native artifacts. An abstract declaration pass does not validate a complete OpenAPI document or a business API's semantics.
## Attach an Implementation Report
**Recommended:** record specification release, corpus commit or SHA-256, implementation commit/package hash, applicable Profile, public interface/adapter entrypoint, date, passed/failed/skipped/not-run IDs, evidence links and limitations. Explain each skip: not applicable differs from applicable but unsupported.
Do not copy oracle output into a runtime assessment as if it exercised that runtime. Keep the implementation's adapter and integration results separate. The [business worksheet](../../examples/BUSINESS_RISK_EXAMPLES.md) supplies scenarios for planning integration evidence, not pre-passed tests.
---
Source: https://agentcapability.org/docs/proposals/
Repository file: proposals/README.md
---
# ACC Proposal Process
ACC proposals provide a public, implementation-neutral path for changing normative fields or behavior. They are design inputs, not roadmap promises or compatibility claims.
Use [TEMPLATE.md](TEMPLATE.md) for a new proposal.
## Current Drafts
- [Agent-Facing Capability Deprecation](agent-facing-deprecation.md) records a minimal advisory deprecation candidate. It is not part of released ACC v1 and currently lacks the independent implementation evidence required for review.
## States
| State | Meaning |
|---|---|
| `Draft` | The author is still defining semantics or collecting evidence. |
| `Under Review` | The proposal is complete enough for public technical review. |
| `Accepted` | Governance review accepted the semantics for a future release. |
| `Rejected` | The proposal does not fit ACC core or did not satisfy the evidence requirements. |
| `Withdrawn` | The author withdrew the proposal. |
| `Superseded` | A later proposal replaced it. |
Proposal authors may suggest a state, but maintainers record state transitions in public review with a rationale. `Accepted` does not mean released; the change still follows ACC versioning, implementation, conformance, and release checks.
## Admission Gate
A normative proposal must first satisfy the core-field tests in [DESIGN_RATIONALE.md](../DESIGN_RATIONALE.md). Those tests are necessary, not sufficient.
Review additionally considers:
1. Evidence that the problem appears across independent implementation contexts.
2. Whether the proposal is the smallest stable semantic addition.
3. Whether ACC core is the correct layer rather than OpenAPI, a binding, an implementation extension, runtime policy, business authorization, or workflow orchestration.
4. Complete types, defaults, precedence, failure behavior, and security semantics.
5. Fail-safe behavior for older runtimes, a conservative fallback they already understand, or a new compatibility boundary.
6. Reference implementations or implementation descriptions that do not share one private product architecture.
7. Machine-readable parser or runtime conformance vectors.
8. Ecosystem complexity and long-term maintenance cost.
Examples alone do not prove cross-implementation demand. A self-assessment does not decide acceptance.
## File Naming
Before an identifier is assigned, use a descriptive draft filename in a pull request. Accepted or long-running proposals may be assigned a stable filename such as:
```text
0001-short-title.md
```
Do not reuse identifiers from rejected, withdrawn, or superseded proposals.
## Compatibility Rule
An optional security restriction is not backward-compatible merely because an older parser ignores it. Review the declaration author's security intent:
- if ignoring the field broadens exposure, weakens approval, extends authorization, or records data that should be redacted, ignoring it is not fail-safe;
- same-major evolution requires a conservative fallback understood by older runtimes or explicit capability negotiation;
- otherwise use a new major compatibility family.
## Decision Record
The merged proposal or pull request must preserve:
- final state;
- decision date;
- concise rationale;
- compatibility conclusion;
- links to conformance evidence;
- superseding proposal, when applicable.
Private conversations, product-specific negotiations, and personal attribution are not normative evidence. Public decisions should stand on portable semantics and reproducible evidence.
---
Source: https://agentcapability.org/docs/proposals/agent-facing-deprecation/
Repository file: proposals/agent-facing-deprecation.md
---
# ACC Proposal: Agent-Facing Capability Deprecation
State: Draft
Decision date: Not decided
Compatibility conclusion: Candidate same-major advisory addition; evidence pending
## Summary
Define a minimal, machine-readable signal for an ACC capability that remains enabled but is no longer recommended for new agent plans or integrations.
This draft does not change ACC v1. It records candidate semantics for public review and implementation evidence.
## Problem
`enabled` is intentionally binary: an enabled capability may be exposed, while a disabled capability must not be exposed. It cannot express a migration interval in which an existing agent-facing capability still works but new consumers should prefer another path.
Standard OpenAPI already supports operation-level `deprecated: true`. That signal is correct when the HTTP operation itself is deprecated. It does not cover the distinct case where the HTTP operation remains supported for non-agent clients but its agent-facing capability should no longer be selected for new use.
A portable deprecation signal could let parsers, catalogs, authoring tools, and runtimes preserve that distinction without turning lifecycle metadata into a second exposure or authorization mechanism.
## Non-Goals
This proposal does not define:
- API or schema versioning;
- automatic disabling at a future time;
- a `stable`, `sunset`, or `removed` lifecycle state machine;
- automatic redirection to another capability;
- argument translation or workflow migration;
- whether an LLM will follow migration guidance;
- final business authorization or endpoint availability;
- HTTP `Deprecation` or `Sunset` response-header behavior.
Actual removal remains explicit: the publisher sets `enabled: false`, removes the ACC declaration, or retires the underlying operation under the rules of the bound protocol and business system.
## Independent Implementation Contexts
The portable problem should be validated in at least these independent contexts before review advances:
1. An OpenAPI gateway or compiler where an HTTP operation remains active for conventional clients while its agent-facing capability is being replaced.
2. An agent platform or catalog that consumes a validated ACC capability artifact and needs to identify deprecated capabilities without owning the source API lifecycle.
Evidence from one product implementing both contexts is not sufficient by itself. This draft currently has no independent implementation evidence.
## Proposed Syntax
```yaml
x-agent-capability:
version: 1
enabled: true
scope: refund.create
lifecycle:
deprecated: true
migration_uri: https://example.com/migrations/refund-create
```
Candidate fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
| `lifecycle` | object | no | Agent-facing lifecycle metadata. |
| `lifecycle.deprecated` | boolean | no | The capability remains governed by `enabled`, but is not recommended for new agent use. Default: `false`. |
| `lifecycle.migration_uri` | absolute URI string | no | Human-facing migration documentation. It is not a capability reference or executable instruction. |
## Normative Semantics
The following semantics are candidates for review, not released ACC v1 requirements:
1. Missing `lifecycle` or missing `lifecycle.deprecated` means no ACC-specific deprecation signal.
2. `lifecycle.deprecated: true` MUST NOT change `enabled`, scope policy, risk, subject, approval, audit, execution, or final authority semantics.
3. An enabled deprecated capability remains eligible for exposure under ACC Core. A consumer MUST preserve the deprecation state in its validated capability artifact when it supports this proposal.
4. A runtime or authoring tool SHOULD make the deprecation state available as structured diagnostics. ACC does not require a particular warning UI, model prompt, or ranking algorithm.
5. A consumer MUST NOT automatically invoke, redirect to, authorize, or translate arguments for another capability based on `migration_uri`.
6. Consumers are not required to fetch `migration_uri`. If retrieved, its content is untrusted descriptive material and MUST NOT override governance metadata or become authority for execution.
7. A malformed `lifecycle` object or invalid field type MUST produce diagnostics under the supporting parser's documented validation behavior. It MUST NOT create a less-governed fallback tool.
8. Unknown lifecycle fields follow the existing ACC unknown-field compatibility rule and MUST NOT implicitly change security behavior.
## Interaction And Precedence
### `enabled`
`enabled` remains the only ACC Core field that directly enables or disables exposure. `enabled: false` always prevents exposure, regardless of lifecycle metadata.
Deprecation is therefore advisory migration state, not delayed enforcement. A publisher that intends to stop exposure must update `enabled` or use a separate deployment mechanism understood by all relevant runtimes.
### OpenAPI `deprecated`
For the OpenAPI binding:
- OpenAPI operation `deprecated: true` makes the bound operation effectively deprecated for agent consumers even when ACC lifecycle metadata is absent;
- `lifecycle.deprecated: true` may add an agent-specific deprecation signal while the OpenAPI operation remains active;
- ACC lifecycle metadata MUST NOT negate OpenAPI `deprecated: true`.
The OpenAPI binding would define this effective-state mapping if the proposal advances.
### Replacement Capabilities
This draft deliberately does not define `superseded_by: `. ACC `scope` is a policy and allowlist unit, not a globally unique operation reference. Replacements may be one-to-many, may require different arguments, and may have different risk or authorization semantics.
A future replacement reference would need binding-qualified identity, resolution, trust, and failure rules. Until then, migration details belong in non-executable documentation.
## Layer Boundary
Agent-specific deprecation is a plausible ACC declaration concern because it describes whether a capability is recommended to agent consumers while leaving the underlying operation active.
The lifecycle of the underlying API, RPC method, message consumer, deployment, or business operation remains owned by the binding-native contract and provider. Binding-native deprecation should be reused when it already expresses the intended scope.
## Compatibility And Security
An older ACC v1 runtime ignores `lifecycle` and continues to apply the existing `enabled`, scope, subject, risk, and approval behavior. This is a candidate same-major addition only because the draft forbids lifecycle metadata from acting as an automatic exposure restriction.
The fallback is not safe if a publisher treats deprecation or a date as automatic removal. Such behavior would require an existing conservative `enabled: false` fallback, explicit capability negotiation, or a new compatibility boundary.
The proposal does not weaken business authorization. It also does not guarantee that a model stops selecting the capability; the portable outcomes are preservation and structured deprecation state, not model obedience.
## Alternatives
### Use OpenAPI `deprecated` only
Preferred when the operation itself is deprecated for all consumers. It cannot distinguish agent-specific deprecation from general API deprecation.
### `status: stable | deprecated | sunset`
Not proposed. `deprecated` is a current recommendation state, while sunset is a future availability event or instant. Combining them creates overlapping state and time semantics and risks turning lifecycle into a second exposure switch.
### `sunset_at`
Deferred. A portable timestamp would need absolute-time syntax, clock and failure semantics, binding interaction, and a clear statement that it does not automatically change `enabled`. The minimal deprecation problem does not require it.
### `superseded_by: `
Not proposed because scope is not a unique operation identity and cannot safely drive automatic migration.
## Implementation Evidence
None yet. The proposal remains `Draft` until independent implementations or implementation descriptions demonstrate the same semantics without sharing one private architecture.
## Conformance Vectors
Candidate vectors, not yet part of the released corpus:
| ID | Input | Expected portable outcome |
|---|---|---|
| `T-LIFECYCLE-01` | lifecycle absent | no ACC-specific deprecation signal |
| `T-LIFECYCLE-02` | `enabled: true`, `deprecated: true` | capability remains exposure-eligible and carries deprecated state |
| `T-LIFECYCLE-03` | `enabled: false`, `deprecated: true` | capability is not exposed |
| `T-LIFECYCLE-04` | OpenAPI `deprecated: true`, ACC lifecycle absent | OpenAPI binding reports effective deprecation |
| `T-LIFECYCLE-05` | migration URI present | URI is preserved; no automatic redirect or invocation |
| `T-LIFECYCLE-06` | invalid deprecated type | diagnostic; no less-governed fallback tool |
Machine-readable vectors and a reference oracle are required before this proposal can advance to `Under Review`.
## Ecosystem Cost
The smallest candidate adds one optional object, one boolean, and one optional documentation URI. Costs include parser preservation, diagnostics, native-deprecation precedence in each binding, authoring guidance, and long-term naming stability.
Adding dates, replacement graphs, automatic migration, or enforcement would materially increase ecosystem cost and is outside this draft.
## Open Questions
- Is an ACC-specific signal needed in at least two independent bindings, or should OpenAPI-specific usage remain a binding extension?
- Is `lifecycle` the smallest stable namespace, or would a top-level `deprecated` boolean be more appropriate?
- Should `migration_uri` enter with the boolean or remain binding-native documentation?
- Which structured diagnostic is portable enough for conformance without prescribing UI?
---
Source: https://agentcapability.org/docs/changelog/
Repository file: CHANGELOG.md
---
# Changelog
## Unreleased
## 1.0.5 - 2026-08-04
[Detailed release notes](RELEASE_NOTES_v1.0.5.md)
- Clarified that `approval.when` evaluates one invocation and cannot enforce
aggregate, rolling-window, cross-invocation, or sequence constraints.
- Defined portable `in`, `contains`, and `exists` runtime semantics, including
strict JSON equality and explicit-null behavior.
- Expanded the ACC v1 conformance corpus from 18 to 26 vectors with focused
operator coverage.
- Added continuous integration for repository, conformance, and test checks.
- Added no ACC Core field and required no declaration migration.
## 1.0.4 - 2026-07-28
[Detailed release notes](RELEASE_NOTES_v1.0.4.md)
- Added the non-normative `acc-validate` OpenAPI authoring CLI with human and
JSON diagnostics, stable exit codes, local-file `$ref` resolution, ACC v1
schema checks, and typed `approval.when` input validation.
- Added English and Chinese five-minute authoring guides.
- Added a multi-operation order-service example covering readonly access,
write operations, conditional approval, audit sensitivity, and explicit
disabled exposure.
- Added package-install smoke coverage and focused validator/CLI tests.
- No ACC Core field, OpenAPI Binding requirement, declaration compatibility, or
conformance profile changed.
## 1.0.3 - 2026-07-20
[Detailed release notes](RELEASE_NOTES_v1.0.3.md)
- Defined a common Core/Binding interface covering carrier placement, validated capability artifacts, native input mapping, metadata precedence, failure behavior, and binding-specific conformance.
- Moved OpenAPI-specific extraction, parameter resolution, `GET` risk fallback, guidance mapping, and Parser Profile responsibilities into the OpenAPI binding.
- Clarified why detailed effect or business-domain taxonomies remain experimental authoring or binding metadata rather than ACC v1 core fields.
- Clarified why agent-selection guidance remains in the capability contract while native schemas and descriptions remain authoritative.
- Added a Draft Proposal for minimal agent-facing capability deprecation without automatic disabling, redirection, or schema changes.
- No released schema, core field, OpenAPI declaration behavior, or existing conformance outcome changed.
## 1.0.2 - 2026-07-18
[Detailed release notes](RELEASE_NOTES_v1.0.2.md)
- Added a public normative proposal lifecycle and template.
- Clarified that core-field admission checks are necessary but not sufficient.
- Added an implementation-neutral landscape of adjacent transport, identity, runtime-control, policy, workflow, and business-authorization layers.
- Clarified that broader cross-boundary agent-action governance is a research direction, while ACC v1 remains the concrete A2B contract with OpenAPI as its first binding.
- Clarified that `subject.required` applies at the receiving runtime's trust boundary and does not prove subject continuity across multiple hops.
- Clarified that runtime-authored approval assertions and audit records are not automatically independently verifiable evidence.
- Documented identity, delegation, canonicalization, freshness, replay protection, and third-party approval evidence as complementary protocol concerns.
- Refined provenance wording without granting any implementation privileged status in ACC governance or compatibility.
- Added Chinese concept and design-boundary documentation.
- No schema, core field, declaration compatibility, or conformance outcome changed; existing ACC v1 declarations require no migration.
## 1.0.1 - 2026-07-12
[Detailed release notes](RELEASE_NOTES_v1.0.1.md)
- Clarified that `approval.when` uses ANY semantics when unconditional approval is not required.
- Clarified that `approval.required: true` remains unconditional and cannot be reduced by conditional rules.
- Added machine-readable ACC v1 parser and runtime conformance vectors plus a reference oracle.
- Added a design-rationale document covering known A2B concerns that intentionally belong outside ACC core.
- Added a fail-safe compatibility rule for security-relevant optional fields.
- Separated stable specification status from early ecosystem maturity.
- No existing ACC v1 declaration requires migration.
## 1.0.0 - 2026-07-11
[Detailed release notes](RELEASE_NOTES_v1.0.0.md)
- Published the stable ACC v1 specification release while keeping declaration compatibility at `x-agent-capability.version: 1`.
- Clarified typed `approval.when` semantics: condition targets must resolve to declared parameters, comparisons do not coerce JSON types, and incompatible invocation values must be rejected before business execution.
- Added an implementation-neutral implementer's guide with reference lifecycles, approval patterns, security invariants, and conformance mapping.
- Added separate Parser, Generator, Runtime, and Policy Component conformance profiles.
- Added an open implementation registration and self-assessment process without implying certification.
- Strengthened maintainer neutrality invariants so no product implementation defines ACC semantics or receives privileged registry status.
- Reworked the implementation registry around profile claims, public evidence, known limitations, and equal criteria.
## Initial public draft - 2026-07-09
- Introduced ACC v1 as an OpenAPI `x-agent-capability` declaration contract.
- Defined core fields: `version`, `enabled`, `scope`, `risk`, `subject`, `approval`, `audit`, `execution`, and `guidance`.
- Added JSON Schema for ACC v1.
- Added OpenAPI examples for readonly query, approval intent, and subject-required capabilities.
- Added conformance checklist and governance notes.
---
Source: https://agentcapability.org/docs/releases/v1.0.5/
Repository file: RELEASE_NOTES_v1.0.5.md
---
# ACC v1.0.5
ACC v1.0.5 is a compatible security-clarification and conformance-coverage
release for the ACC v1 declaration family.
## Contract Version
ACC declarations continue to use:
```yaml
x-agent-capability:
version: 1
```
This release adds no core field, changes no JSON Schema rule, and requires no
declaration migration.
## Per-Invocation Approval Boundary
`approval.when` conditions evaluate one invocation at a time. They do not
express aggregate, rolling-window, cross-invocation, or sequence constraints.
A threshold such as `amount > 1000` therefore does not prevent multiple smaller
operations from creating a larger cumulative effect.
Deployments whose risk model includes cumulative effects must enforce those
constraints in the authoritative business or policy layer. The implementer's
guide includes a concrete decomposition example and preserves ACC's boundary
between portable declaration semantics and stateful business policy.
## Operator Semantics
The specification now states explicitly that:
- `in` requires an array comparison value and uses strict JSON equality;
- string `contains` uses substring matching;
- array `contains` uses strict JSON equality for elements;
- `exists` matches only a resolved, non-null JSON value.
These statements codify the existing reference-oracle behavior so independent
runtimes do not interpret the same declaration differently.
## Conformance Coverage
The reference corpus expands from 18 to 26 vectors. New vectors cover positive
and negative behavior for `in`, string and array `contains`, and present,
missing, and explicit-null `exists` inputs.
Passing the corpus remains reference evidence rather than official
certification.
## Continuous Integration
Repository checks, conformance vectors, and automated tests now run for pushes
and pull requests through a minimal read-only GitHub Actions workflow.
---
Source: https://agentcapability.org/docs/releases/v1.0.4/
Repository file: RELEASE_NOTES_v1.0.4.md
---
# ACC v1.0.4
ACC v1.0.4 is a compatible authoring-experience release for the ACC v1
declaration family.
## Contract Version
ACC declarations continue to use:
```yaml
x-agent-capability:
version: 1
```
This release adds no core field, changes no JSON Schema rule, changes no
OpenAPI Binding requirement, and requires no declaration migration.
## OpenAPI Authoring Validator
The `agent-capability-contract` npm package now publishes the non-normative
`acc-validate` command. It checks:
- OpenAPI 3.0 and 3.1 documents in YAML or JSON;
- operation-level `x-agent-capability` placement and ACC v1 declaration shape;
- local and relative local-file `$ref` targets without hidden network access;
- parameter and JSON request-body paths used by `approval.when`;
- strict JSON type compatibility without implicit coercion;
- human-readable and JSON diagnostics with stable exit codes.
The validator is an authoring aid. It is not a complete OpenAPI linter,
business-authorization engine, runtime, policy service, or ACC certification.
## Five-Minute Quickstart
English and Chinese quickstarts now provide one continuous path from an
existing OpenAPI document to a validated ACC declaration. The published
package can be run without a global installation:
```bash
npx --yes agent-capability-contract@1.0.4 validate ./openapi.yaml
```
## Multi-Operation Service Example
The new order-service example shows multiple ACC declarations in one OpenAPI
document:
- a low-risk readonly order query;
- a medium-risk order creation operation;
- a high-risk refund with parameter-level conditional approval;
- an audit-log operation that is explicitly disabled for agent exposure;
- reusable local OpenAPI components and references.
The example is validated by the same command documented in the quickstart.
## Tests And Packaging
The authoring validator and CLI have focused automated coverage for valid and
invalid declarations, references, ambiguous input paths, strict value types,
recursive schemas, diagnostics, and exit codes.
The npm artifact is also installed into a clean temporary project and exercised
through its published command during release verification.
## Conformance And Compatibility
The ACC v1 conformance corpus remains at 18 vectors. Existing vector inputs,
expected outcomes, Schema rules, core semantics, and OpenAPI Binding behavior
are unchanged. The corpus release marker is updated to `1.0.4`.
---
Source: https://agentcapability.org/docs/releases/v1.0.3/
Repository file: RELEASE_NOTES_v1.0.3.md
---
# ACC v1.0.3
ACC v1.0.3 is a compatible Core/Binding architecture clarification release for the ACC v1 declaration family.
## Contract Version
ACC declarations continue to use:
```yaml
x-agent-capability:
version: 1
```
This release adds no released core field, changes no JSON Schema rule, and requires no declaration migration.
## Core And Binding Architecture
ACC Core now has an explicit boundary from protocol-specific bindings:
- Core owns the portable declaration fields, defaults, compatibility rules, and protocol-independent runtime invariants.
- A binding owns declaration placement, operation identity, native input mapping, parameter-path resolution, metadata precedence, extraction failures, diagnostics, and binding-specific conformance evidence.
- A validated capability artifact is defined as a conceptual interface between binding parsers and core runtimes, not as a required wire or storage format.
- OpenAPI remains the first standardized ACC v1 binding; future bindings must preserve core semantics rather than redefine them.
These clarifications make future binding work possible without turning ACC Core into an OpenAPI-specific model.
## OpenAPI Binding
OpenAPI-specific responsibilities are now consolidated in `bindings/openapi.md`, including:
- operation-level `x-agent-capability` extraction;
- standard `parameters` and `requestBody` preservation;
- strict native-value mapping and condition-path resolution;
- the OpenAPI `GET` readonly default and its precedence;
- the relationship between OpenAPI descriptions, schemas, examples, and supplemental ACC guidance;
- precise OpenAPI Binding Parser and Generator claim language.
No existing valid OpenAPI declaration changes meaning in this release.
## Risk And Guidance Boundaries
The design rationale now records why detailed state-effect or business-domain taxonomies remain experimental authoring diagnostics, binding metadata, or future evidence-backed proposals rather than ACC v1 core fields.
`guidance` remains in the capability contract because an agent-facing capability must be selectable as well as governable. Binding-native request and response schemas remain authoritative, and guidance remains supplemental, non-authoritative, and non-security-critical.
## Agent-Facing Deprecation Draft
The repository now contains a Draft Proposal for a minimal agent-facing deprecation signal. The draft deliberately does not define automatic sunset, disabling, redirection, argument migration, or replacement by `scope`.
The proposal is not part of released ACC v1. It has no effect on the v1 Schema or conformance corpus and cannot advance without independent implementation evidence and machine-readable vectors.
## Conformance
Binding Parser and Generator claims must now name the binding they implement. Runtime and Policy Component profiles remain protocol-independent when they consume an equivalent validated capability artifact.
The ACC v1 corpus remains at 18 vectors. Existing inputs and expected outcomes are unchanged; wording now distinguishes portable bound-input behavior from OpenAPI-specific defaults, and the corpus release marker is updated to `1.0.3`.
---
Source: https://agentcapability.org/docs/releases/v1.0.2/
Repository file: RELEASE_NOTES_v1.0.2.md
---
# ACC v1.0.2
ACC v1.0.2 is a compatible boundary, governance, and documentation clarification release for the ACC v1 declaration family.
## Contract Version
ACC declarations continue to use:
```yaml
x-agent-capability:
version: 1
```
This release does not add or change any ACC field, JSON Schema rule, OpenAPI binding, or conformance outcome. No existing valid ACC v1 declaration requires migration.
## Trust Boundaries
- `subject.required: true` requires a trusted acting subject at the receiving runtime's current trust boundary.
- Model output, tool arguments, and unverified upstream claims do not become trusted subject context merely because they contain a subject identifier.
- ACC compatibility does not prove that one subject remained authentic and unmodified across a chain of agents, runtimes, organizations, or trust domains.
- Cross-hop continuity requires a complementary identity or delegation mechanism with explicit issuer, verification, audience, freshness, replay, and failure semantics.
These clarifications preserve the existing rule that the business system remains the final authorization authority at invocation time.
## Approval Evidence And Traceability
ACC continues to declare approval intent rather than an approval-evidence protocol.
- A runtime-authored approval field or audit record can provide operational traceability inside that runtime's trust domain.
- It is not automatically independent proof against compromise of the same runtime.
- Deployments requiring third-party verification need a complementary protocol that defines canonical bytes, signatures, issuer keys, freshness, replay protection, and fail-closed verification before execution.
No cryptographic or workflow mechanism is added to ACC v1 by this release.
## Public Governance
The repository now includes a public normative proposal lifecycle and template. Core-field admission checks are explicitly necessary but not sufficient. Proposals are also reviewed for independent demand, minimality, correct layer ownership, complete failure semantics, fail-safe compatibility, implementation evidence, conformance vectors, and ecosystem cost.
Submitting or accepting a proposal does not make it part of a released ACC version. Normative changes still follow the normal versioning, review, implementation, and release process.
## Scope And Ecosystem Boundaries
The new implementation-neutral landscape distinguishes ACC from adjacent concerns such as:
- OpenAPI and transport protocols;
- identity and delegation;
- runtime enforcement and policy systems;
- workflow and transaction coordination;
- final business authorization.
The recurring governance questions may also appear in broader cross-boundary agent-action environments. That observation is a research direction, not an expansion of ACC v1 compatibility. ACC v1 remains the concrete contract for A2B business operations, with OpenAPI as its first binding.
## Neutrality And Provenance
Public wording now describes ACC v1 as developed from A2B engineering work, including early BailingHub implementation experience, while preserving strict implementation neutrality. No product receives privileged semantics, governance influence, registry status, or compatibility treatment.
## Conformance
The ACC v1 machine-readable corpus remains at 18 vectors with unchanged inputs and expected outcomes. The corpus release marker is updated to `1.0.2` so implementations can identify the exact specification revision used for self-assessment.
---
Source: https://agentcapability.org/docs/releases/v1.0.1/
Repository file: RELEASE_NOTES_v1.0.1.md
---
# ACC v1.0.1
ACC v1.0.1 is a compatible clarification and conformance release for the ACC v1 declaration family.
## Contract Version
ACC declarations continue to use:
```yaml
x-agent-capability:
version: 1
```
No existing valid ACC v1 declaration requires migration.
## Approval Semantics
- `approval.required: true` creates approval intent for every invocation.
- Otherwise, `approval.when` uses ANY semantics: one matching item is sufficient to create approval intent.
- An absent or empty `approval.when` creates no conditional approval intent.
- Existing strict JSON type comparison and argument-schema validation remain unchanged.
This clarification removes an ambiguity that could otherwise produce inconsistent independent runtimes.
## Conformance Corpus
The repository now includes machine-readable ACC v1 vectors for:
- declaration validation and unknown-field tolerance;
- exposure decisions for enabled, scope policy, and trusted-subject availability;
- unconditional and parameter-conditional approval decisions;
- strict argument-type rejection;
- risk defaults;
- audit sensitivity hints.
`npm run check` validates the specification repository and verifies the corpus against a reference oracle. Implementations may consume the same abstract inputs through their own adapters and publish results as self-assessment evidence.
## Design Boundaries
[DESIGN_RATIONALE.md](DESIGN_RATIONALE.md) documents known concerns that are intentionally outside ACC core, including final business permissions, tenant isolation, identity representation, approval ownership, audit retention, contextual business invariants, rollback, workflow composition, storage, transport, and observability.
The document also defines a test for proposed core fields and explains the difference between a small contract and an ambiguous contract.
## Safe Evolution
Unknown-field tolerance provides syntax-level compatibility only. Security-relevant optional fields may remain within ACC v1 only when older runtimes ignoring them are fail-safe or when a conservative ACC v1 fallback is present. Other changes require a new major family or explicit capability negotiation.
## Maturity
The ACC v1 specification core is stable. The implementation ecosystem is in early adoption, and conformance currently uses public profiles, machine-readable vectors, and self-assessment rather than official certification.
---
Source: https://agentcapability.org/docs/releases/v1.0.0/
Repository file: RELEASE_NOTES_v1.0.0.md
---
# ACC v1.0.0
ACC v1.0.0 is the first stable specification release of Agent Capability Contract for A2B capability declarations.
## Contract Version
ACC declarations continue to use:
```yaml
x-agent-capability:
version: 1
```
The declaration field identifies the ACC v1 compatibility family. The `v1.0.0` repository tag identifies this exact specification revision. Product and runtime versions are independent.
## Specification Clarification
- `approval.when.param` must resolve to a typed standard OpenAPI parameter or request-body field.
- Comparisons use strict JSON type semantics and do not coerce strings into numbers or booleans.
- Incompatible invocation values must be rejected before the business operation is called.
## Implementer Path
- Added a non-normative implementer's guide covering reference modules and lifecycles without prescribing a product architecture.
- Added Parser, Generator, Runtime, and Policy Component profiles.
- Added open implementation registration and self-assessment templates.
- Added specification-derived security invariants and clearly separated optional platform features.
## Neutral Governance
- No product implementation defines ACC semantics or receives privileged compatibility or registry status.
- Implementation observations are examples until portable, testable semantics are accepted through the contract process.
- Registry inclusion is self-declared and evidence-backed; it is not certification, endorsement, partnership, or a production-readiness guarantee.
## Compatibility
This release keeps the ACC v1 declaration shape and does not require a new declaration version. Existing valid ACC v1 declarations remain in the same compatibility family.
---
Source: https://agentcapability.org/zh-CN/
Repository file: README.zh-CN.md
---
