Liking cljdoc? Tell your friends :D

OpenAPI services as agent tools

autonomous.openapi turns an OpenAPI 3 spec into agent tools with no change to the service. Only the operations you name become tools.

(require '[autonomous.openapi :as openapi]
         '[autonomous.openapi.load :as load]
         '[autonomous.openapi.invoke :as oinv])

(def spec (:ok (load/load-bundle "libs/openapi/sisf-payment.yaml"))) ; follows ./common.yaml refs

(openapi/install! spec
  {:prefix    "payment"                                   ; tools payment_getPayment, ...
   :base-url  "https://staging.example/api/payment"       ; required, never taken from `servers`
   :principal (oinv/bearer (fn [grant] (token-for (:actor grant))))
   :expose    {"getPayment"   {:scope :payment/read}
               "listPayments" {:scope :payment/read}}})

How it works

StepNamespacePure?
Read the YAML/JSON and every file its $refs reachautonomous.openapi.loadIO
Resolve $refs, inside one file and across filesautonomous.openapi.docyes
Convert JSON Schema to malliautonomous.openapi.schemayes
Turn the operations you opt into into tool specsautonomous.openapi.deriveyes
encode args into a request; decode the response into an Answerautonomous.openapi.codecyes
Run encode, then identity, then HTTP, then decodeautonomous.openapi.invokeHTTP only
Default HTTP client (java.net.http, JVM and bb)autonomous.openapi.httpIO
derive-surface :autonomous.openapi/specautonomous.openapi.spiyes
  • Input schema. One flat map: path, query and header parameters plus the JSON body's properties. If a body property shares a name with a parameter, or the body is not an object, the whole body goes under :body instead.

  • decode. A call succeeds only when the response is a 2xx that the spec declares and its body matches the declared schema. Everything else becomes a refusal that carries the server's own message (problem+json detail, then title, then message):

    • :openapi/bad-request, :openapi/unauthenticated, :forbidden, :openapi/not-found, :openapi/conflict, :openapi/server-error
    • :openapi/undeclared-response, :openapi/response-mismatch, :openapi/unreachable

    decode never throws.

  • Identity port. :principal (fn [grant request] request). Two helpers ship with it: oinv/bearer and oinv/persona-headers.

  • HTTP port. :http (fn [request] response). Pass a stub in tests or a gateway client in a cluster. A transport failure returns {:error e} instead of throwing.

  • Refused when you derive the tools, not when they are called: an unknown operationId, an empty :expose, and non-JSON bodies such as multipart.

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close