Skip to content

librarian v0.23.0

Choose a tag to compare

@github-actions github-actions released this 17 Nov 17:38
· 9 commits to main since this release

An agent that was told only that an operation takes a body had to guess what goes in it. In live runs a small and a large Claude model both said so, and answered from what they knew of the API: that works for Stripe, and gives nothing to go on for an internal API. librarian now reads what a request body holds from the API's description, and tells it.

For every agent

  • capabilities with api and operation gives that operation in full: every argument with its type and description, and every field of its body with its type, whether it is needed, the values it takes and what it is for. labels[] is a list, author.name a field inside another. Up to 40 fields, three levels deep.
  • capabilities with api names the first fields of each body: "body": ["head", "base", "title?", "draft?"], with body_more when there are more than ten. Among several APIs an operation still says body: true, to keep that answer small.
  • The skill (skills/librarian) tells agents to ask before a write instead of guessing. A kagent Agent takes it from this release's image by digest: oci: ghcr.io/kultar/librarian@sha256:f27f8114f3f7d61ea763903a1acf256599bf3f0c03e1ff575979899e36f1ad82, path: skills/librarian.

In a live run with only the tools, a small model asked to open a draft pull request asked about the operation first and sent {"head": "fix/typo", "base": "main", "title": "...", "draft": true} at the first attempt. Asked what a Stripe refund takes, a small and a large model both listed the twelve fields with their types and values from librarian's answer.

For the people who run it

  • The console's API page shows what a body holds, under each operation.
  • Read from OpenAPI and Swagger descriptions (requestBody, in: body, formData), through $ref, allOf, oneOf and anyOf. Not from documentation pages or from a model's knowledge. A body can be written into an entry by hand (the format).
  • Told, not enforced. Nothing is checked against it: the API accepts or refuses a body. A change in a body at the source is listed as a change and holds no operation back.
  • APIs learned before get their bodies when their description next changes, or at once when a person asks: Re-check now on the console's API page, or librarian registry recheck <api>, which now read a description again even where it has not changed. For an approved API that is an update an approver takes. It adds the bodies and touches nothing else that was decided about the operations. The daily look at the sources does not do this by itself, so nobody gets a card they did not ask for.

Measured on GitHub, Stripe, Jira, PagerDuty and DigitalOcean: 1,343 of the 1,497 operations that take a body are described. A body has two to six fields at the median. An entry grows by a quarter (GitHub: 1.26 MB to 1.59 MB) to double (Stripe).

Upgrade

  • No configuration changes are needed.
  • An entry that has body fields cannot be read by 0.22 or earlier. Every API learned or read again by 0.23 has them. After a rollback, such an API is reported as invalid and is not served until you roll forward again; nothing is lost. For the same reason, finish the rollout before agents learn APIs.
  • capabilities with api and no query lists fewer operations of a large API (30 of each kind for GitHub, where it was 50), because each one now names what its body holds. The note in the answer says how to see the rest.
  • Finish the rollout before agents use operation: a replica still on 0.22 does not know the argument.
  • librarian still sends a body as JSON. Where an API's description says it takes a form (Stripe's does, for every operation), the answer says "sent_as": "form"; such an API may refuse the write.