ИИ-агенты
Если интеграцию пишет ИИ-агент, первым делом дайте ему https://occultapi.com/AGENTS.md. Это короткая памятка о четырёх вещах, в которых агенты стабильно ошибаются с нашим API.
Дайте агенту это
Вставьте это в агента до начала работы. Обычный markdown, без авторизации, CORS открыт — агент может скачать файл сам.
Read https://occultapi.com/AGENTS.md before writing any code against Occult API.
Use the OpenAPI spec at https://occultapi.com/openapi.json for exact field names.Что там написано и почему
Четыре правила. Каждое появилось потому, что агенты действительно совершают здесь эту ошибку, — это не общий гайд по стилю.
- Объединяйте расчёты через
keys, а не в цикле. Несколько расчётов в одном запросе стоят один кредит, те же расчёты отдельными вызовами — по кредиту за каждый. Агент, который стремится к читаемому коду, напишет цикл, а платить за него будет ваш баланс. - Не повторяйте запрос после 402. Этот код значит, что ключ действителен, а баланс пуст. Агент, который примет его за временный сбой, будет повторять запрос бесконечно, а агент, который примет его за ошибку авторизации, перевыпустит вполне рабочий ключ. Повторять можно только 429 и 5xx.
- Ключ — только на сервере. Говорим об этом прямо, потому что «вызвать с клиента» — самый простой путь, и он раскрывает ваш ключ всем.
- Читайте спецификацию, а не угадывайте имена полей. В документе OpenAPI есть каждое поле, его допустимые значения и пример для каждого эндпоинта, у большинства — проверенный на работающем сервере. Один запрос спецификации лучше трёх ошибок 400.
Если агент поддерживает MCP, подключите его так
Наш MCP-сервер открывает все эндпоинты (их 299) через пять инструментов, причём поиск и чтение схем не стоят ни кредита — платить нужно только за сам расчёт. Агент может бесплатно изучить весь API и тратить кредиты, только когда действительно что-то считает. Это и дешевле, и надёжнее, чем заставлять его угадывать по документации.
Сначала прочитайте сами
Две минуты вашего времени этот файл заслуживает раньше, чем внимание агента: /AGENTS.md. Если совет окажется неверным, разбираться всё равно вам.