Turn discovery into an executable operation

Advertise what can happen next

An Action describes an HTTP operation associated with one Offering. It can tell an Agent how to download content, request a quote, reserve capacity, purchase an item, or invoke an online capability.

Actions are optional and appear only in a Full Offering. An Offering with no applicable operation omits actions and remains valid for discovery, comparison, and browser navigation. One Offering can advertise up to 16 Actions.

Read an Action contract

Every Action has a stable local identifier, a rel value describing its purpose, and an authentication expectation. It also contains exactly one target description: a compact HTTP target or an OpenAPI target.

Keep an Action ID stable while that Action remains the same operation on the Offering. Duplicate IDs make every Action bearing that ID unusable because an Agent cannot select one unambiguously.

Choose the intended relation

rel communicates the kind of outcome the caller is seeking. It does not define the response schema, commerce workflow, authentication mechanism, or payment requirement.

free is a Price Preview type, not an Action relation. An Agent retains an Action with an unknown relation so a caller can select it explicitly by ID, but never chooses it automatically based on an assumed meaning.

Choose a target description

Both forms identify the same kind of Action. The choice changes how the operation is described, not its relation, identity, authentication expectation, or execution safety.

Describe a compact HTTP target

The compact form places the target in http. Its required href is a Resource Reference and its required method is GET or POST.

{
  "id": "run-search",
  "rel": "invoke",
  "authentication": "required",
  "description": "Run a web search and return cited results.",
  "http": {
    "href": "/actions/search",
    "method": "POST",
    "request": {
      "content_type": "application/json",
      "schema": {
        "url": "/schemas/search-request.json"
      }
    },
    "response_content_types": [
      "application/json"
    ]
  }
}

• Request body: describe one optional body with a media type, a JSON Schema reference, or both
• Request schema: apply the same reference resolution, anonymous retrieval, caching, and narrow-failure rules used by Attribute Schemas
• Successful responses: advertise up to eight possible media types without constraining challenges, redirects, or errors
• Live response: treat the returned Content-Type as authoritative

An Agent sends no request body unless the caller supplies one or the operation contract supplies a complete value. A compact target cannot describe URL, header, or cookie parameters; use OpenAPI when those inputs are part of the operation.

Reference an OpenAPI operation

An OpenAPI Action names exactly one Operation Object by its case-sensitive operation_id. The example inherits the OpenAPI document from http.openapi.url in the Service Document.

{
  "id": "reserve-seat",
  "rel": "reserve",
  "authentication": "optional",
  "openapi": {
    "operation_id": "reserveSeat"
  }
}

Set openapi.url on the Action when it uses a different document. The Action-level reference overrides the Service-level reference. The Action is unusable when neither location is available or when the identifier resolves to zero or multiple operations.

The document must be OpenAPI 3.1 JSON. Retrieve it anonymously, enforce the ODP size, depth, and redirect limits, and match only operationId. An Agent must not guess from the path, method, summary, or description.

Keep discovery separate from execution

Action resolution prepares the method, URL, content type, and request contract for a caller. The caller selects the Action and approves any required inputs before the Agent sends the network request.

Follow live access requirements

authentication describes whether Service authentication is expected at the Action target. It does not create a credential, replace an AEP challenge, or prove that the target currently requires authentication.

Begin the Action request in its current authentication context. Follow a live AEP, MPP, x402, or other HTTP challenge according to that protocol. An advertisement without a challenge must not cause the Agent to enroll, authenticate, or pay speculatively.

A cross-origin Action starts without credentials belonging to the Offering Service. Credentials can be obtained or sent only under the target origin's own policy and live challenge flow.

Isolate unusable Actions

Action metadata is independently usable. Preserve the Offering and unrelated Actions when one Action cannot be resolved safely.

• Invalid Action: omit only that Action from the usable Action set and report a scoped issue
• Duplicate ID: treat every Action with that identifier as unusable rather than choosing one
• Failed schema: leave the target unresolved without discarding the Offering's identity, price, or presentation fields
• Failed OpenAPI lookup: do not guess an operation from nearby metadata
• Unknown relation: retain the Action for explicit selection but do not select it automatically

Retry state changes carefully

A Service must give every compact GET Action safe HTTP semantics. Loading or retrying it must not create the state change that a POST Action would represent.

After an ambiguous outcome from a state-changing Action, an Agent must not retry automatically unless the operation defines an applicable idempotency mechanism and the retry preserves it. Challenge-response retries remain governed by AEP, MPP, x402, and the exact request binding of the protocol involved.

Next steps