Проектировать API для AI-агентов нужно совсем не так, как для людей. Большинство современных вызовов API уже пишется агентами — два года назад это было не так, и теперь правила игры изменились. Автор статьи признаётся, что пересмотрел почти все свои взгляды за последние 24 месяца: больше не верит в системы для людей, скептичен к пакетам и утилитам, и теперь предпочитает очень длинные имена переменных.
Для человека хорошее API — это когда с первой попытки получаешь работающий прототип строчек на 50. Классические примеры — Twilio и Stripe: даже 14-летний подросток мог отправить SMS или создать платёж, ничего не зная про ACH или планировщики. Для агентов так работать перестало. Агент за один промпт (в среднем 10k+ токенов) читает всю документацию целиком и может сгенерировать тысячи строк кода. Ему не нужны умные сокращения и снисходительные допущения.
Автор формулирует четыре принципа для API под агентов. Первое: умолчания — зло. Агент может сам прочитать документацию и заполнить все поля явно. Цена явности теперь почти нулевая, а цена непонимания того, что делает код — огромная. Второе: ошибки — это хорошо. Снисходительность API (когда он сам принимает true, yes, on, 1 за одно и то же) вредит: агенты начинают использовать разные варианты в разных местах, и потом код невозможно отлаживать. Точная ошибка с инструкцией — лучший инструмент навигации. По данным автора, 27% проблем агентов приходятся именно на ошибки. Третье: чёткость вместо двусмысленности. Поле name — худшее, что можно придумать: в десяти разных контекстах агент поймёт его пятью способами. Лучше displayName, slug, externalId — агент и будущий разработчик поймут их однозначно. Четвёртое: API — это факты, а не чувства. Ценность API в том, что оно даёт факт, который команда не может воспроизвести внутри себя: оплаченный счёт, отправленное сообщение, запущенная VM. Всё остальное (SDK-утилиты, абстракции) лучше заменить на документацию и гайды.
В качестве примера автор приводит собственный проект Freestyle. Раньше они прятали сложность за пакетами (VmBun и тому подобное) — получилась красивая, но непонятная агенту обёртка. Сейчас они всё выкинули. Вместо SDK используют простой exec и гайд: агент сам читает гайд, адаптирует код под свой проект, код становится прозрачным. Среди других решений автор хвалит Flue Framework (минимализм и ясность) и Vercel AI SDK (чёткие функции generateText и streamText). Критикует Mastra за тяжеловесность и двусмысленные контракты, а Eve — за монолитную систему скиллов, которую невозможно программировать.
В песочницах автор считает эталоном собственный Freestyle (простота без лишних утилит), хорошей — E2B (сдержанность, хотя есть косяк с sbx.runCode), а средненькой — Daytona (слишком много всего зашито в SDK, что агент не может настроить). В итоге, по мнению автора, многое из того, что раньше было критически важно для API (количество строк, отсутствие ошибок при онбординге, малый порог входа), для агентов перестало иметь значение. Он прогнозирует, что SDK для обёрток API умрут года через три, а CLI — и того раньше.