OAP
RFC 0020

Agent Query Language

The canonical query surface of the Open Agent Protocol. Agents express what they want as a signed Intent with constraints, a projection, a budget, and a quality floor. Resolvers evaluate the Intent against their indexed Manifests and return ranked candidates with per candidate Decision Records.

One language
Discovery, commerce, knowledge, action, delegation, and subscription all use the same Intent shape.
Closed operator set
15 operators. Predicates a Resolver cannot evaluate are not expressible.
Verifiable result
Every candidate carries a Decision Record. Match Brokers add Inclusion Proofs.

Try it

The playground runs the reference evaluator and projection in your browser. No server roundtrip, no signature, no policy stack. For the full reference implementation see reference/aql in the spec repository.

Intent shape

An Intent is a JSON document conforming to oap-intent.schema.json. The required blocks are listed below. The full normative description lives in RFC 0020.

  • intent_id
    URN minted by the issuer.
  • issuer_did
    Decentralized identifier of the signing Principal.
  • category
    commercial, knowledge, action, delegation, discovery, subscription.
  • constraints
    Constraint tree built from leaves and the boolean combinators all_of, any_of, not.
  • projection
    Include and exclude pointer sets that bound what data crosses the boundary.
  • budget
    Cost ceiling, currency, and allocation policy across candidates.
  • quality_floor
    Minimum acceptable performance, conformance, latency, reputation.
  • validity
    Window during which the Intent is open for response.
  • resolution_policy
    single_best, ranked_set, or full_set.
  • signature
    EdDSA, ES256, or ES384 signature over the canonicalized body.

Operator set

The closed operator set defined by RFC 0020 section 3.2. Operators outside this set are introduced through additive minor versions of the RFC.

eq
equals
ne
not equals
lt
less than
lte
less than or equal
gt
greater than
gte
greater than or equal
in
value in array
not_in
value not in array
contains
string or array contains
matches
regex match
before
date before
after
date after
within
date within {from,to}
outside
date outside {from,to}
exists
path resolves to a value

Categories

Six normative Intent categories. Additional categories are introduced through additive minor versions of the RFC.

  • commercial
    Procurement Intent of RFC 0013, generalized with the AQL constraint, projection, budget, and quality semantics.
  • knowledge
    Request for Knowledge Nodes that satisfy the constraints, with metering and Citation Attribution.
  • action
    Invocation of an Action class on any conformant Provider, gated by the four layer Policy Stack.
  • delegation
    Delegation of a sub task under the cost attribution model of RFC 0004.
  • discovery
    Enumeration of Providers whose Manifests satisfy the constraints.
  • subscription
    Subscription to a feed of Manifest changes that satisfy the constraints, with backpressure.

Reference implementation

The reference implementation is open source under Apache 2.0 and published in the spec repository at reference/aql. It includes a parser, an evaluator, a projection engine, a resolution helper, a CLI tool, and a unit test suite covering the full operator set. Implementers MAY vendor or fork the package without restriction.

# Install and run
git clone https://github.com/openagentprotocol-OAP/oap-spec
cd oap-spec/reference/aql && npm install
node bin/oap-aql.js validate ../../examples/aql/discovery-intent.json
node bin/oap-aql.js resolve  ../../examples/aql/discovery-intent.json \
                              ../../examples/aql/candidates.json

See also