# Work with AI agents

Source: https://apigenie.pl/docs/guides/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](/docs/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 binaries share
  [one table](/docs/reference/cli#exit-status): 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`; `apigenie-catalog` and
  `apigenie-mcp` are experimental.
- **Output it can parse.** Since 0.12.0 every command takes `--json` and then prints one JSON
  document: its report (`lint`, `diff`, `format`, `test`, `apigenie-catalog list`, ...) or the
  status of the run, with the exit status and the messages
  ([JSON output](/docs/reference/cli#json-output)). Each has a `formatVersion` and a published
  schema.
- **Settings in a file it can check.** `apigenie.yaml` is validated against
  [its JSON Schema](/docs/reference/cli/configuration) 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`](/llms.txt) and collected in [`llms-full.txt`](/llms-full.txt). So do
  the sites of your own APIs: the build of
  [`apigenie-generator docs`](/docs/guides/publish-api-documentation) writes a Markdown copy of
  each page with its own `llms.txt`, which an agent that calls your API can read.

## Tell the agent about the commands

Most agents read an instructions file at the root of the repository: `AGENTS.md`, `CLAUDE.md`,
`.github/copilot-instructions.md`, `.cursor/rules` or the equivalent of your tool.
[`apigenie init`](/docs/reference/cli/init) adds this section to it (`AGENTS.md` unless you name
another with `--agents-file`) and writes `apigenie.yaml` with the rules of the descriptions it
finds. Or add the section by hand. Either way, say in its first sentence where your descriptions
are:

```markdown
## API descriptions

This repository keeps its API descriptions (OpenAPI, Swagger 2.0, AsyncAPI, GraphQL, Protobuf)
under version control and checks them with the API Genie CLI (`apigenie`; install it with
`npm install -g @mykulyak/api-genie`). The project's rules are in `apigenie.yaml`. After changing a
description:

1. `apigenie lint --fix --json <file>`, then fix what is left by hand and lint again. The JSON
   lists every issue with its line, rule and message; the command exits with 1 while errors
   remain. Fix the issues your change introduced, not the ones that were there before.
2. `apigenie format <file>`.
3. Compare with the base branch: `git show origin/main:<file> > /tmp/base` and
   `apigenie diff --json /tmp/base <file>`. Exit status 1 means a breaking change: say so in the
   pull request and propose a compatible alternative. Do not remove the change, or weaken
   `apigenie.yaml` (turn a rule off, lower a severity), to make a check pass without asking.

Every command takes `--json` and then prints one JSON document: its report, or
`{"exitStatus", "messages", "output"}`. Exit statuses: 0 success, 1 findings, 2 a usage or input
error. `apigenie <command> --help` lists the options; generate code with
`apigenie-generator <client|server|docs> <target> --help`, mock with `apigenie-server <file>`.
```

The sentence about weakening the checks matters: an agent told only to make a 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.

```sh
apigenie lint apis/orders.yaml --fix --json > lint.json; echo $?
```

```text
1
```

With `--json`, each remaining issue has its file, line, column, severity, rule and
message, and each rule links its page under [the linter rules](/docs/linter), 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.

```sh
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.

```sh
git show main:apis/orders.yaml > /tmp/orders.main.yaml
apigenie diff /tmp/orders.main.yaml apis/orders.yaml --report status --json
```

```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](/docs/ci/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](/docs/guides/catch-breaking-changes-in-ci) sets it up.

## Serve the checks to the agent over MCP

Agents that reach tools through the Model Context Protocol can call the checks directly. These
are desktop and IDE clients, or an agent whose every shell command needs an approval.
[`apigenie-mcp`](/docs/reference/cli/mcp) (since 0.12.0), installed with the CLI, serves `lint`,
`check_breaking_changes`, `changelog`, `format`, `bundle` and `describe`. `lint` and
`check_breaking_changes` run `apigenie` with the repository's `apigenie.yaml`. Their result starts
with a sentence that says whether the check passed.

In Claude Code, add it with:

```sh
claude mcp add api-genie -- apigenie-mcp
```

Other clients take the command `apigenie-mcp` in their own MCP settings
([Usage](/docs/reference/cli/mcp#usage)). `apigenie-mcp` writes nothing unless started with
`--allow-write` (`claude mcp add api-genie -- apigenie-mcp --allow-write`), which lets `lint` fix,
`format` rewrite and `bundle` write files. Without it, `format` returns the formatted text for the
agent to apply. It is [experimental](/docs/reference/cli#experimental-commands).

## 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:

```sh
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](/docs/guides/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](/docs/reference/cli#experimental-commands): MCP and its SDK
are still moving, and the tool names and result shapes can change with them.

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

## Next steps

- [Lint and format API descriptions](/docs/guides/lint-and-format-api-descriptions): the rulesets
  and your own rules.
- [Exit statuses](/docs/reference/cli#exit-status) and
  [the compatibility promise](/docs/reference/cli/compatibility): what a script can rely on.
- [`llms.txt`](/llms.txt): the documentation, for the agent to read.
