EXAMPLES

Attach capability meaning to the API contract you already have.

ACC examples are OpenAPI-first. Business parameters remain in standard OpenAPI schemas; ACC adds the agent-facing capability layer.

READONLY QUERY

Expose safe business lookup.

Read operations usually declare low risk, subject requirements, and readonly execution hints. The business system still checks whether the subject may read the requested object.

order-read.yaml

x-agent-capability:
  version: 1
  enabled: true
  scope: order.read
  subject:
    required: true
  risk:
    level: low
  execution:
    readonly: true
    idempotent: true

SUBJECT REQUIRED

Keep authority inside the business system.

ACC can require a trusted acting subject before the runtime exposes a capability. This prevents anonymous agent calls from seeing tools that require a real user, employee, tenant, or business actor.

staff-search.yaml

x-agent-capability:
  version: 1
  enabled: true
  scope: staff.search
  subject:
    required: true
  risk:
    level: low
  guidance:
    when_to_use: Search staff before assigning work.
    returns: Matching staff records visible to the subject.

PARAMETER APPROVAL

Declare approval intent without owning approval workflow.

High-risk operations can declare approval intent globally or only when arguments cross a business threshold. The approving person, location, and workflow remain a business-side decision.

refund-approval.yaml

x-agent-capability:
  version: 1
  enabled: true
  scope: refund.create
  subject:
    required: true
  risk:
    level: high
  approval:
    required: false
    when:
      - param: amount
        op: ">"
        value: 1000
        label: Refund amount exceeds threshold.