# 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 four binaries share
  [one table](/docs/reference/cli/overview#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`; 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](/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).

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

```markdown
## 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.

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

```text
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](/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 --formatter 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.

## 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/overview#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/overview#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.