Repository navigation
librarian v0.23.0
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
capabilitieswithapiandoperationgives 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.namea field inside another. Up to 40 fields, three levels deep.capabilitieswithapinames the first fields of each body:"body": ["head", "base", "title?", "draft?"], withbody_morewhen there are more than ten. Among several APIs an operation still saysbody: 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,oneOfandanyOf. 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.
capabilitieswithapiand 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.