How-to guidesWork with AI agents

Work with AI agents

A coding agent edits an API description the way it edits code: quickly, and without the context a reviewer has. The checks that protect a repository from a hurried person protect it from an agent too, provided the agent can run them and read their answers. This guide puts apigenie lint, apigenie format and apigenie diff in an agent’s loop, tells the agent about them, and keeps the same checks in CI for the pull request the agent opens.

You need the CLI installed where the agent runs; the Quickstart shows how. The commands below work with OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files.

What an agent needs from a tool

  • An exit status that means one thing. The four binaries share one table: 0 is success, 1 is findings (lint errors, breaking changes, files to reformat), 2 is a usage or input error. The 1.0 compatibility promise freezes it for apigenie, apigenie-generator and apigenie-server; the catalog is experimental.
  • Output it can parse. lint, diff, format, test, apigenie-catalog list and the server’s contract report print JSON on request, with a formatVersion where the shape may grow.
  • Settings in a file it can check. apigenie.yaml is validated against its JSON Schema before any command reads it, so a wrong key is an error with a line, not a silently ignored setting.
  • Documentation it can read. Guides, reference pages and linter rules have Markdown copies, indexed in llms.txt and collected in llms-full.txt.

Tell the agent about the commands

Most agents read an instructions file at the root of the repository (AGENTS.md, CLAUDE.md or the equivalent of your tool). Three lines are enough:

## API descriptions

The files under `apis/` are OpenAPI and AsyncAPI documents. After changing one:

1. `apigenie lint <file> --fix`, then fix what is left; the command exits with 1 while errors remain.
2. `apigenie format <file>`.
3. `apigenie diff <base> <file>`: a status of 1 means a breaking change. Say so in the pull request,
   and do not remove the breaking change to make the check pass without asking.

The last sentence matters: an agent told only to make the check pass will make it pass.

The loop

Each step prints something the agent can act on, and exits with a status it can test.

apigenie lint apis/orders.yaml --fix --formatter json > lint.json; echo $?
1

With --formatter json, each remaining issue has its file, line, column, severity, rule and message, and each rule links its page under the linter rules, which says why the rule exists and what a fix looks like. --fix has already applied the safe fixes and kept the comments of the file.

apigenie format apis/orders.yaml

The formatter gives the same file for the same input, whoever ran it, so a formatted file is a small diff: only the lines the agent meant to change. The first formatting pass can change many lines; commit it on its own, before the API changes, so reviewers can tell the two apart.

git show main:apis/orders.yaml > /tmp/orders.main.yaml
apigenie diff /tmp/orders.main.yaml apis/orders.yaml --report status --formatter json
{ "formatVersion": 1, "status": "non-breaking" }

--report status is the one-word answer; --report changelog lists every change with its rating, and --report detailed every property that changed, for the pull request’s description.

Keep the same checks in CI

The agent’s checks are advisory until CI runs them on the pull request. The GitHub Action lints the changed files and compares each with the base of the pull request, and shows the issues on the changed lines, where the reviewer and the agent both see them. Catch breaking changes in CI sets it up.

Check the code the agent generates

When an agent writes the server too, put apigenie-server in front of it as a validating proxy: every response is checked against the contract, and the run fails on a violation:

apigenie-server apis/orders.yaml --proxy-to http://localhost:8080 --port 4010 \
  --report contract.json --fail-on errors &
API_URL=http://localhost:4010 npm test
curl -X POST http://localhost:4010/__apigenie/shutdown
wait $!

Mock and contract-test an API explains the report and the coverage gate.

Give an agent the API as tools

apigenie-generator server mcp writes an MCP server with a tool per operation of an OpenAPI document, so an agent can call the API through the Model Context Protocol instead of writing HTTP by hand. It is experimental: MCP and its SDK are still moving, and the tool names and result shapes can change with them.

apigenie-generator server mcp apis/orders.yaml -o orders-mcp

Next steps