EXAMPLES

Start with a business action. Make its boundaries explicit.

Editing a product draft, publishing it, and changing stock should not be treated as interchangeable writes. These examples explain the business assumptions first, then show how to describe each operation with ACC and OpenAPI.

阅读商城与库存示例的中文解读 →

CATALOG + INVENTORY

Five operations. Different effects and checks.

Use this walkthrough to discuss risk and approval with the people who own the business rules.

01 / CONTENT

Edit an unpublished draft

Change its text or image URLs. The service checks ownership, draft state and version; this operation cannot change price or stock.

02 / CUSTOMERS + REVENUE

Publish a product or change its price

These are separate actions with approval intent. The service still checks approver authority, sales channels, current price and margin rules.

03 / STOCK

Read inventory or adjust it

Reading stock does not grant permission to change it. The adjustment example requires approval and checks the original stock version.

Read the walkthrough Catalog OpenAPI YAML Inventory OpenAPI YAML

Synthetic services for learning and validation. Risk choices depend on the stated business assumptions; a valid declaration does not grant access or implement the service.

What if the task spans 100 products?

“Update descriptions and pictures, and only read inventory” also limits objects, fields and cumulative effects. The runtime and business systems must enforce that task boundary; it is not an extra ACC field.

Read the responsibility guide →

DECLARATION BUILDING BLOCKS

See how individual fields fit into an operation.

Business parameters stay in standard OpenAPI schemas. These short excerpts focus on the ACC declaration.

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.