Создание ии агента это инженерная работа, а не настройка готового сервиса. Разработчик пишет системный промпт, описывает инструменты функциями с JSON Schema, подключает хранилище истории, ставит лимит шагов и обработку ошибок. Ниже маршрут от постановки задачи до прототипа, который прогоняется на своей машине, с опорой на документацию OpenAI Agents SDK, спецификацию Model Context Protocol и SDK российских платформ.
Что входит в создание ии агента
По итогам работы в репозитории появляются шесть артефактов: системный промпт (в Agents SDK это поле instructions объекта Agent), описания инструментов с полями type, name, description, parameters и strict по документации OpenAI, реализации этих инструментов, хранилище истории, правила остановки и набор тестовых обращений.
Цикл выполнения в документации Agents SDK описан так: вызываем модель для текущего агента с текущим входом; если ответ классифицирован как финальный, цикл заканчивается; если запрошена передача другому агенту, меняем агента и повторяем; если вернулись вызовы инструментов, выполняем их, дописываем результаты и повторяем. Остальное в проекте это обвязка вокруг четырёх веток.
Как создать ии агента: маршрут из семи шагов
Вопрос «как создать ии агента» на практике распадается на семь шагов, и порядок важнее инструмента.
- Выбрать один процесс и критерий успеха. Не «поддержка клиентов», а «ответ о статусе заказа без менеджера». Критерий это доля обращений, закрытых без эскалации.
- Собрать 30-50 настоящих обращений. Из почты, чата или тикетов, вместе с кривыми формулировками и опечатками. Это тестовый набор, а не иллюстрация.
- Составить список действий. Каждое превращается в функцию: посмотреть заказ, найти документ, создать задачу. Действия без API в первую версию не берутся.
- Написать системный промпт. Роль, границы, формат ответа, условия обращения к человеку.
- Описать и подключить инструменты. Схема аргументов, обработчик, поведение при ошибке.
- Подключить память и лимиты. Сессия для истории и предел числа шагов.
- Прогнать тестовый набор локально. Смотреть не только ответы, но и цепочку вызовов: какие функции выбраны и с какими аргументами.
Первый прогон почти всегда даёт три класса дефектов: агент вызывает не ту функцию, передаёт неполные аргументы или отвечает по общим знаниям модели вместо данных компании.
Системный промпт: инструкция, по которой агент принимает решения
Системный промпт это не приветствие и не описание тона, а документ, по которому модель на каждом шаге решает, вызвать инструмент, ответить текстом или остановиться. Рабочая структура состоит из пяти блоков.
- Роль и границы. Какие обращения агент обрабатывает и какие темы не берёт.
- Порядок работы с инструментами. Правило вида «прежде чем назвать срок доставки, вызови функцию статуса заказа; без результата вызова срок не называть».
- Формат ответа. Длина, структура, обязательные поля. Если ответ уходит в другую систему, формат задаётся схемой, а не просьбой в тексте.
- Условия остановки. Когда диалог передаётся человеку: жалоба, возврат денег, отсутствие данных.
- Запрет на догадки. Прямая формулировка «если данных нет, скажи, что не знаешь, и передай человеку».
Поле instructions может быть функцией, формирующей текст динамически: имя клиента, тариф, доступные разделы. Правки промпта проверяются прогоном того же тестового набора, иначе исправление одного сценария незаметно ломает соседний.
Инструменты и вызов функций: схема, по которой агент действует
Инструмент это описание функции, которое отдаётся модели вместе с запросом. По документации OpenAI цикл вызова состоит из пяти шагов: запрос к модели со списком инструментов, ответ модели с вызовом, выполнение вашего кода с полученными аргументами, второй запрос с результатом, финальный ответ или новые вызовы.
| Поле | Что задаёт | Практическое правило |
|---|---|---|
| type | Тип инструмента, для функций всегда function | Задаётся один раз в шаблоне |
| name | Идентификатор функции | Глагол и объект: get_order_status, а не handler2 |
| description | Когда и как вызывать функцию | Пишется для модели: условия вызова и краевые случаи |
| parameters | JSON Schema аргументов | Типы, допустимые значения, описание каждого поля |
| strict | Строгое следование схеме | Все поля из properties обязаны быть в required, additionalProperties выставлен в false |
Отсюда ограничение строгого режима: необязательных аргументов в привычном виде нет, документация предлагает объявлять их объединением типов, например “type”: [“string”, “null”], и обрабатывать null в коде. Второе ограничение про количество: рекомендация OpenAI звучит как «стремитесь держать меньше 20 функций, доступных в начале хода», с оговоркой, что это мягкая рекомендация. Документация связывает размер стартового набора с точностью выбора и предлагает откладывать редкие инструменты через tool_search, а не выкладывать всё сразу.
Выбор управляется параметром tool_choice: auto по умолчанию разрешает ноль, один или несколько вызовов, required требует хотя бы одного, none запрещает вызовы, allowed_tools сужает набор. Режим required это рычаг отладки: он показывает, где ошибка, в описании функции или в промпте.
В Python-версии SDK описание генерируется автоматически: декоратор function_tool берёт имя из имени функции, описание из докстринга, схему аргументов строит по аннотациям через Pydantic, разбирая докстринги в форматах google, sphinx и numpy. Докстринг становится частью контекста модели. Что добавляется к инструментам при выходе в прод, разобрано отдельно: подтверждения действий и наблюдаемость.
MCP: подключение инструментов без собственных обёрток
Model Context Protocol это открытый стандарт, по которому агент подключается к внешним системам без отдельного коннектора под каждую. Протокол построен на JSON-RPC 2.0, серверы выставляют три примитива: Tools (исполняемые функции: операции с файлами, вызовы API, запросы к базе), Resources (источники контекста: содержимое файлов, записи в базе, ответы API) и Prompts (переиспользуемые шаблоны обращений к модели).
Клиент запрашивает список методом tools/list и вызывает выбранный через tools/call с полями name и arguments. Каждый инструмент несёт name, title, description и inputSchema, то есть ту же JSON Schema, что и при обычном вызове функций. Штатных транспорта два: stdio для локальных процессов на той же машине и Streamable HTTP для удалённых серверов, с рекомендацией использовать OAuth для получения токенов.
Версию протокола стоит фиксировать явно: ревизия 2026-07-28 сделала протокол stateless, убрала рукопожатие initialize, методы ping и logging/setLevel, а версию и возможности клиента перенесла в поле _meta каждого запроса. Сервер обязан реализовать метод server/discover, отдающий поддерживаемые версии, возможности и идентификацию; клиент может вызвать его заранее или сразу слать нужный запрос и разбирать UnsupportedProtocolVersionError. Запросы сервера к пользователю (sampling/createMessage, elicitation/create) идут теперь не встречным вызовом, а результатом InputRequiredResult: сервер перечисляет нужное в поле inputRequests, клиент повторяет запрос с inputResponses. Для агента elicitation это готовый механизм «спросить человека»: форма с JSON-схемой или переход по ссылке, если данные чувствительные.
Память и контекст: что агент помнит между шагами
Модель не помнит ничего между запросами, история передаётся заново каждый раз, и её хранение это отдельный компонент. В Agents SDK он называется сессией и поддерживает четыре операции: get_items для чтения, add_items для записи, pop_item для удаления последнего элемента и clear_session для очистки.
| Реализация | Где применяется |
|---|---|
| SQLiteSession | Локальная разработка, файл или база в памяти |
| SQLAlchemySession | Прод на существующей базе, поддерживаемой SQLAlchemy |
| RedisSession | Общая память между несколькими воркерами |
| MongoDBSession | Многопроцессное горизонтально масштабируемое хранилище |
| EncryptedSession | Обёртка поверх любого хранилища с прозрачным шифрованием |
Деталь, которая ловит почти всех: SQLiteSession с одним аргументом создаёт базу в памяти, живущую столько, сколько живёт процесс. Чтобы история пережила перезапуск, вторым аргументом передаётся путь к файлу. Второй вопрос это размер: история растёт вместе с расходами и временем ответа, поэтому старые шаги сворачивают в резюме, а порог подбирают по средней длине диалога на тестовом наборе.
Ии агент в компанию: подключение к данным и системам
Агент на общих знаниях модели бесполезен внутри организации: он не знает ваш прайс, регламент возврата и остатки. Ии агент в компанию отличается от учебного прототипа этим слоем из трёх частей.
- Поиск по документам. Регламенты, инструкции, каталог складываются в индекс, и агент отвечает по найденному фрагменту, а не по памяти модели. В SDK Yandex AI Studio есть управление индексами трёх типов: текстовый, векторный и гибридный, в Agents SDK ту же роль играет встроенный FileSearchTool.
- Оперативные данные. Заказы, задачи, остатки берутся вызовом функции в момент запроса: они меняются быстрее, чем переиндексируется база.
- Права и токены. Токены хранятся вне кода, вызов выполняется от имени конкретного сотрудника, иначе агент отдаст одному пользователю данные другого.
Разграничение поиска и вызова функций снимает главную проблему внедрения: агент перестаёт выдумывать, потому что на каждый тип вопроса есть точный источник. Правило: всё, что меняется реже раза в неделю, идёт в индекс, остальное запрашивается функцией.
Нужен агент под ваш процесс, а не учебный прототип
Разберём один процесс, опишем инструменты и границы, соберём агента и подключим к вашим системам с прогоном на реальных обращениях.
Ошибки, повторы и приёмка прототипа
Агент отличается от одиночного запроса тем, что может крутиться: инструмент вернул ошибку, модель попробовала снова, и так до исчерпания бюджета. Ограничители ставятся в трёх местах.
- Лимит шагов. За это отвечает max_turns: при превышении выбрасывается исключение MaxTurnsExceeded. Значение None отключает лимит, в прототипе так делать не стоит.
- Поведение инструмента при сбое. По умолчанию срабатывает default_tool_error_function, которая сообщает модели об ошибке, и та может попробовать другой путь. Своя функция меняет текст сообщения, явный None пробрасывает исключение в ваш код.
- Проверки входа и выхода. Декораторы input_guardrail и output_guardrail возвращают GuardrailFunctionOutput; при взведённом tripwire_triggered поднимаются InputGuardrailTripwireTriggered и OutputGuardrailTripwireTriggered, а для инструментов ToolInputGuardrailTripwireTriggered и ToolOutputGuardrailTripwireTriggered.
У входных проверок есть неочевидный режим: по умолчанию они выполняются параллельно с агентом, задержка меньше, но токены расходуются даже при срабатывании стоп-сигнала. Флаг run_in_parallel со значением False переводит проверку в блокирующий режим. Рядом стоит параметр is_enabled: он принимает True, False или функцию, решающую по контексту, так что неоплаченному тарифу инструмент выгрузки просто не показывают.
Прототип принимается по прогону: набор из 30-50 обращений прогнан целиком, для каждого зафиксирована цепочка вызовов с аргументами, на вопрос без данных агент отказывается, срабатывание max_turns проверено намеренно сломанным инструментом, замерено среднее число шагов. Частые дефекты: описания функций написаны для разработчика без условий вызова; инструментов сразу больше двадцати; strict включён, а схема содержит необязательные поля вне объединения с null; история лежит в базе в памяти и теряется при перезапуске.
Ии агент и ии ассистент: что меняется в коде
Пара «ии агент и ии ассистент» в инженерном смысле различается не уровнем интеллекта, а составом кода. Ассистент это один вызов модели и возврат текста: цикла нет, инструментов нет, состояние хранит интерфейс. Агент добавляет к этому цикл с разбором ответа на три ветки, инструменты, состояние в сессии и ограничители. Помимо своих функций в Agents SDK доступны встроенные WebSearchTool, FileSearchTool, CodeInterpreterTool, ImageGenerationTool и HostedMCPTool.
Отсюда вывод про бюджет: ассистент это один платный вызов модели на реплику, агент это столько вызовов, сколько шагов он сделал, причём каждый следующий несёт всю накопленную историю. Цену агента считают не по числу диалогов, а по среднему числу шагов, замеренному на тестовом наборе до запуска.
Как создать ии агента бесплатно: локальный прогон своего кода
Ответ на вопрос «как создать ии агента бесплатно» в инженерном контуре такой: бесплатны библиотеки и запуск, платными остаются вызовы модели, если она не локальная.
- Фреймворк. OpenAI Agents SDK ставится командой pip install openai-agents, распространяется под лицензией MIT и на 22 августа 2026 года собрал около 28,8 тысячи звёзд на GitHub. Заявлена независимость от провайдера: поддерживаются Responses API и Chat Completions, а также, по формулировке репозитория, «100+ других LLM».
- Модель локально. Ollama распространяется под лицензией MIT и запускает открытые модели на своей машине, включая gpt-oss, Qwen, Gemma и DeepSeek. Плата за токены исчезает, остаётся требование к железу.
- Память и разбор. SQLiteSession без внешней базы плюс встроенная трассировка, которая показывает последовательность вызовов модели, инструментов и передач между агентами.
Бесплатный контур закрывает проверку гипотезы и отладку описаний инструментов. Нагрузку и качество на сложных запросах он не закрывает, поэтому на платную модель переходят, когда тестовый набор собран и есть с чем сравнивать.
Российский контур: GigaChat и Yandex AI Studio
Если данные не должны покидать российскую юрисдикцию, схема сборки не меняется, меняются имена полей и SDK. Актуальные лимиты и тарифы проверяются на страницах вендоров.
| Что задаём | GigaChat | Yandex AI Studio |
|---|---|---|
| Описание инструментов | Массив functions в запросе к /chat/completions с полями name, description, parameters и return_parameters | OpenAI-совместимый чат-интерфейс с вызовом инструментов, Function Tool в Python SDK |
| Режим вызова | Параметр function_call, значение auto оставляет решение модели | Совместимые с OpenAI параметры выбора инструмента |
| Готовые функции | Встроенные text2image, get_file_content, text2model3d | Встроенный поиск и работа с индексами |
| База знаний | Поиск на своей стороне | Индексы трёх типов: текстовый, векторный, гибридный |
| Установка SDK | Работа по HTTP API | pip install yandex-ai-studio-sdk, синхронный и асинхронный режимы |
В документации GigaChat указано, что все модели GigaChat поддерживают встроенные и пользовательские функции, а возвращаемые значения описываются явно через return_parameters, чего нет в схеме OpenAI. Гибридный индекс Yandex AI Studio снимает типовую проблему векторного поиска: когда в запросе артикул или номер договора, семантическая близость не помогает.
Частые вопросы
Сколько инструментов давать агенту в первой версии
Два-три. Документация OpenAI рекомендует держать меньше 20 функций, доступных в начале хода, и это верхняя граница, а не цель: каждая лишняя функция это ещё один способ ошибиться выбором.
Чем задаётся остановка бесконечного цикла
Параметром max_turns в Agents SDK: при превышении лимита поднимается исключение MaxTurnsExceeded. Значение None отключает ограничение, для прототипа это плохая идея.
Нужен ли MCP, если инструментов всего три
Нет. MCP окупается, когда инструменты переиспользуются несколькими агентами: он даёт единые методы tools/list и tools/call и два транспорта, stdio и Streamable HTTP. Для трёх своих функций проще обычный вызов функций.
Как хранить историю диалога, чтобы она не терялась
Передать сессии путь к файлу: SQLiteSession с одним аргументом создаёт базу в памяти на время жизни процесса. Для нескольких воркеров берут RedisSession, для существующей базы SQLAlchemySession.
Можно ли собрать агента без оплаты сервисов
Да, в контуре своего кода: OpenAI Agents SDK под лицензией MIT ставится командой pip install openai-agents, модель поднимается локально через Ollama, тоже MIT. Платить придётся за железо и, при переходе на облачную модель, за токены.
