Как читать документацию агентной платформы, если вы новичок

Вы открыли документацию агентной платформы — OpenAI Agents SDK, LangGraph, LlamaIndex или чего-то ещё — и увидели двести страниц с разделами Tools, Handoffs, Guardrails, State, Tracing. Первое желание — закрыть вкладку. Проблема не в вашей подготовке: техническую документацию агентных фреймворков пишут инженеры для инженеров, а порядок разделов в меню редко совпадает с порядком, в котором это стоит изучать. Ниже — маршрут чтения, который экономит время и нервы, и список мест, где новички обычно спотыкаются.

Почему документация агентов сложнее обычного API

С обычным REST API всё линейно: есть эндпоинт, есть параметры запроса, есть формат ответа. Агентная платформа устроена иначе. Модель сама решает, какой инструмент вызвать и в каком порядке, а фреймворк лишь задаёт рамки этого поведения. Из-за этого документация описывает не столько «что вернётся», сколько «как система себя поведёт» — а поведение зависит от модели, промпта и данных.

Отсюда три источника путаницы для новичка:

• Абстракции без примеров. Термины вроде «агент¹», «handoff» или «guardrail» описываются сначала концептуально, а рабочий код прячется в отдельном разделе Examples.
• Много способов сделать одно и то же. Один и тот же вызов инструмента показывают через декоратор, через класс и через низкоуровневый API — и не всегда говорят, какой путь рекомендуемый.
• Неочевидные ограничения. Лимит по длине контекстного окна², количество шагов агента, поведение при таймауте — всё это разбросано по разным страницам, а не собрано в один раздел «Limits».

Порядок чтения: пять разделов вместо всех подряд

Не читайте документацию сверху вниз по меню. Идите по логике «от запуска к тонкостям».

1. Quickstart / Getting Started. Здесь минимальный рабочий пример: установка, ключ API, первый запуск агента в десяти строках. Запустите его целиком, не меняя ничего, прежде чем читать дальше. Если пример не заработал — проблема почти всегда в версии SDK или в переменной окружения с ключом, а не в вашем коде.
2. Core Concepts. Раздел, где объясняют базовые сущности: что такое агент, что такое инструмент (tool), что такое цикл выполнения. Читайте по диагонали, но обязательно выпишите себе, как в этой конкретной платформе называется каждая сущность — терминология у всех разная.
3. Tools / Function Calling. Самая практичная часть. Именно здесь вы подключаете к агенту реальные действия: запрос к базе, вызов внешнего API, отправку письма. Разберитесь, как описывается схема аргументов инструмента, — от неё зависит, поймёт ли модель, когда его вызывать.
4. Limits / Pricing / Rate Limits. Раздел, который новички читают последним, а надо бы третьим. Здесь ответ на вопрос «сколько это будет стоить» и «где всё сломается под нагрузкой».
5. Tracing / Observability. Как посмотреть, что агент делал на каждом шаге. Без этого отладка превращается в гадание: вы видите итоговый ответ, но не видите, какой инструмент модель дёрнула и почему.

Хорошее правило для новичка: если раздел документации не помогает вам запустить или отладить конкретный пример прямо сейчас — отложите его. К State management и кастомным guardrails вы вернётесь, когда упрётесь в реальную задачу, а не из чувства долга.

Где искать честные ограничения

Маркетинговая страница платформы обещает «автономных агентов». Документация — та её часть, что ближе к коду, — честно говорит про потолки. Ищите эти три вещи целенаправленно, потому что в меню их редко выносят наверх:

• Максимальное число шагов (turns / iterations). У агента есть лимит циклов «подумал — вызвал инструмент — получил результат». Если задача требует больше — агент остановится на полпути. Значение по умолчанию бывает небольшим, порядка десятка шагов, и его меняют параметром при запуске.
• Размер контекстного окна. Определяется моделью, а не фреймворком. Длинная история диалога и большие результаты инструментов съедают контекст, и агент «забывает» начало разговора.
• Стоимость на токенах. Каждый шаг агента — это отдельный запрос к модели с накопленной историей. Пять шагов агента могут стоить в разы дороже одного запроса к чат-модели. Конкретные цены за токены смотрите на официальной странице тарифов провайдера модели — они меняются, и подставлять число здесь было бы враньём.

Сравнение подходов к документации у платформ

Стиль документации у популярных фреймворков отличается, и это влияет на то, насколько быстро в них входит новичок. Ниже — не сравнение «кто лучше», а описание того, чего ждать от документации каждого. Точные названия разделов и наличие функций сверяйте на официальных сайтах — они обновляются.

Кому этот подход к чтению нужен, а кому нет

Пригодится, если вы:

• умеете писать простой код на Python или JavaScript, но с агентами дела не имели;
• хотите собрать первый рабочий прототип за вечер, а не изучать фреймворк неделю;
• уже запускали примеры, но не понимаете, почему агент «зацикливается» или обрывается на середине — вам в разделы про лимиты шагов и tracing.

Не поможет, если вы:

• проектируете сложную мультиагентную систему в продакшн — тогда придётся читать документацию целиком, включая state, конкурентность и обработку ошибок;
• вообще не программируете: агентные SDK рассчитаны на код, и обойти это чтением документации нельзя. Вам ближе no-code-конструкторы агентов, а не SDK.

Три привычки, которые ускоряют чтение

1. Проверяйте версию. Агентные SDK меняются быстро, и статья или туториал полугодовой давности могут показывать устаревший синтаксис. Всегда сверяйтесь с датой обновления страницы и версией пакета.
2. Копируйте пример целиком и ломайте по одному параметру. Так вы поймёте, за что отвечает каждая строка, быстрее, чем читая описание.
3. Держите открытым раздел про ошибки. Часть документации, где перечислены типовые исключения и их причины, экономит часы: половина проблем новичка — это неверный формат схемы инструмента или превышение лимита шагов.

¹ Агент — программа поверх языковой модели, которая в цикле сама решает, какой инструмент вызвать, выполняет его и учитывает результат на следующем шаге, пока не достигнет цели или лимита шагов.

² Контекстное окно — максимальный объём текста (в токенах), который модель обрабатывает за один запрос: и ваш промпт, и история диалога, и результаты инструментов вместе.

³ RAG (retrieval-augmented generation) — подход, при котором модель перед ответом подтягивает релевантные фрагменты из внешней базы или документов, а не полагается только на то, что «знает».