**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.
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.
| 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.
```
## OpenAPI Binding
The first ACC binding is OpenAPI extension field:
```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 field model.
ACC v1 declarations use `version: 1`. Exact specification revisions use repository tags such as `v1.0.1`; product or runtime versions are separate.
## Implement ACC
- Read the non-normative [Implementer's Guide](IMPLEMENTER_GUIDE.md).
- 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
bindings/openapi.md OpenAPI extension binding
schemas/acc.v1.schema.json Machine-readable JSON Schema
examples/ OpenAPI examples
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
IMPLEMENTATIONS.md Known implementations and claim language
RELEASE_NOTES_v1.0.1.md Current 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
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).
The license allows use, modification, redistribution, and commercial implementation of ACC.
---
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.1
OpenAPI extension: `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 `x-agent-capability` MUST be ignored by runtimes unless they are standardized in a later ACC version.
OpenAPI operation-level extension fields such as `x-business-*` or implementation-specific fields MAY be preserved in an extension bag, but MUST NOT implicitly alter allowlist, risk, approval, rate limit, audit, or signature behavior.
### 2.3 Parameters Stay In OpenAPI
Business input parameters MUST remain in standard OpenAPI `parameters` and `requestBody` JSON Schema.
ACC MUST NOT become a duplicate schema language for business parameters.
## 3. OpenAPI Binding
ACC v1 uses the OpenAPI extension field `x-agent-capability` on an operation object.
An operation is considered ACC-declared when it contains `x-agent-capability`.
An operation is exposed 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 operation has enough parameter schema for safe invocation.
Example:
```yaml
paths:
/orders/{id}:
get:
operationId: order_get
summary: Query one order by ID.
parameters:
- name: id
in: path
required: true
schema:
type: string
x-agent-capability:
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:
- HTTP `GET` or `execution.readonly: true`: `low`;
- non-readonly write operations: `medium`.
### 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.
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 a parameter declared in the operation's standard OpenAPI `parameters` or `requestBody` JSON Schema.
- 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 `in` use strict JSON type-aware equality. For example, `true` is not equal to `"true"`, and `0` is not equal to `"0"`.
- `contains` applies only to string or array parameters. String containment requires a string `value`; array containment uses strict JSON equality for elements.
- 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.
ACC declares approval intent. It does not define who approves, where approval occurs, or how the business workflow is completed.
### 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:
- parse `x-agent-capability` from OpenAPI operations;
- expose only `enabled: true` operations with a non-empty `scope`;
- compile the declaration into a runtime tool model;
- preserve standard OpenAPI parameter schema;
- 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.
## 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:
- `x-agent-capability.version: 1` identifies the major contract compatibility family;
- repository releases use semantic versions such as `v1.0.1` 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 `x-agent-capability.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.
```
## 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. |
## Recommended Messaging
Use:
```text
ACC is the capability contract for A2B.
```
Avoid:
```text
ACC is a product-specific configuration format.
```
Avoid:
```text
Any implementation is the ACC standard.
```
The standard and the implementation should remain clearly separated.
---
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 OpenAPI and JSON Schema cannot already express it cleanly.
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 |
| 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 |
| 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.
## 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 standard OpenAPI 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 parser**: reads and validates ACC declarations.
- **ACC generator**: produces ACC declarations 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["OpenAPI + ACC declaration"] --> B["Contract 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 |
|---|---|---|
| Contract ingestion | **Normative** for parsers and runtimes: read the declaration, validate required fields, preserve OpenAPI parameter schemas, and diagnose unsupported versions. | Parser library, build-time compiler, gateway plugin, generated code, or another form. |
| Capability registry or adapter | **Recommended**: keep the normalized operation, parameter 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 the OpenAPI operation and locate `x-agent-capability`.
2. Validate `version`, `enabled`, and `scope`.
3. Resolve standard OpenAPI `parameters` and `requestBody` schemas.
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.
## 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 standard parameter 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.
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 OpenAPI
-> 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.
## 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.
## 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. |
| 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. |
| 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.
## 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/governance/
Repository file: GOVERNANCE.md
---
# Governance
ACC is maintained as an open contract, not as a product-private configuration format.
## Stewardship
ACC was initially proposed by 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.
Historical attribution does not grant control over implementations and does not make the contract dependent on the project that first proposed it.
## 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 standard OpenAPI schema;
- it does not require the ACC runtime to understand business-specific authorization logic.
Business-specific metadata should use:
- standard OpenAPI fields where possible;
- `guidance.context` for lightweight context tags;
- operation-level `x-business-*` fields for business-defined metadata;
- 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 standard OpenAPI parameter schema;
- 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 parser | Reads and validates `x-agent-capability`. |
| ACC generator | Produces ACC-compatible declarations while keeping business parameters in standard OpenAPI 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/openapi-binding/
Repository file: bindings/openapi.md
---
# OpenAPI Binding
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.
## 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.
## 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.
## 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`.
## 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 runtime responsibilities. Before making a compatibility claim, select the applicable Parser, 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.
Parser implementations normally complete the Parser section. Runtime implementations complete every applicable section. Generator and Policy Component requirements are defined in their profiles because they do not own the full runtime lifecycle.
## 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 OpenAPI parameter.
- [ ] 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 ACC v1 OpenAPI declarations.
```
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 Parser Profile.
Implements the ACC v1 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.
Do not use `ACC certified` or imply review by an independent certification body.
## 2. Parser Profile
For libraries or tools that read ACC declarations.
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. 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 the Parser Profile or consumes equivalent validated artifacts;
- 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 standard OpenAPI schemas without implicit JSON type coercion;
- 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: Parser / Generator / Runtime / Policy Component
- Implementation version or commit:
- License:
## Supported Surface
- Supported ACC fields:
- Unsupported optional fields:
- OpenAPI versions:
- Runtime or integration assumptions:
- Conformance corpus release:
- Applicable vectors passed / skipped:
## Conformance Evidence
| Checklist area | Status | Evidence link | Notes |
|---|---|---|---|
| Parser | Pass / Partial / N/A | | |
| Exposure | Pass / Partial / N/A | | |
| Governance | Pass / Partial / N/A | | |
| Authority Boundary | Pass / Partial / N/A | | |
| Traceability | Pass / Partial / N/A | | |
| Machine-readable vectors | Pass / Partial / N/A | | |
## 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
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.1
Declaration compatibility family: ACC v1
This directory publishes portable inputs and abstract expected outcomes for ACC v1 parser and runtime profiles.
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.
## 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/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.
## 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/changelog/
Repository file: CHANGELOG.md
---
# Changelog
## Unreleased
- Added a public normative proposal lifecycle and template.
- Clarified that core-field admission checks are necessary but not sufficient.
## 1.0.1 - 2026-07-12
- 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
- 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/zh-CN/
Repository file: README.zh-CN.md
---
