Конструктор AI-агентов

Эта страница — каноническое руководство по сборке LLM-агентов с AI Agent Builder от DevUtilities. Используйте пошаговый workflow выше во время чтения или перейдите к теме ниже. Schemas, MCP JSON, промпты и подсчёт токенов остаются в браузере — ничего не загружается для инференса.

AI Agent Builder — клиентская мастерская для сборки production-ready конфигов агентов: JSON Schema tools для OpenAI function calling, проверка mcpServers для Cursor и Claude Desktop, system prompts, суммарные бюджеты токенов и экспортируемые артефакты для передачи команде.

Что вы получаете

• Четыре режима workflow: полный агент, только function calling, настройка MCP, структурированный ответ
• Стартовые шаблоны: Filesystem MCP, OpenAI function calling, структурированный классификатор
• Вывод пример-JSON → JSON Schema с опциональным строгим additionalProperties: false
• Локальный MCP lint с ошибками и предупреждениями по JSON-pointer
• Суммарный бюджет токенов по prompt, минифицированным tools и MCP JSON
• Экспорт: OpenAI tools JSON, response_format, MCP-конфиг, markdown-сводка, полный bundle

Используйте этот builder, когда

• Нужен OpenAI tools JSON и не хотите писать JSON Schema вручную
• Подключаете MCP-серверы Cursor или Claude Desktop и хотите lint перед вставкой
• Нужно доказать, что prompt + tools агента ещё помещаются в окно контекста
• Нужна сохранённая сессия, связывающая schema → MCP → prompt → export

Предпочитайте отдельный инструмент, когда

• Нужно только глубокое сравнение encoding или расчёт стоимости → LLM Token Counter
• Нужен только разовый MCP lint без промптов → MCP Validator
• Нужен только вывод схемы из образца → Structured Output Generator

Выберите режим до определения tools. Режимы скрывают лишние шаги, чтобы не бороться с пустыми панелями.

Первый проход для полного агента. Ярлыки шаблонов пропускают несколько из этих шагов.

1. Выберите Полный агент (или загрузите шаблон OpenAI function calling).
2. В Определении tools добавьте каждый tool с ясным именем, описанием и репрезентативным примером JSON аргументов.
3. Проверьте выведенную JSON Schema — включите строгий режим для OpenAI structured outputs / strict tool calling.
4. Вставьте или отредактируйте mcpServers JSON, если агент будет работать в Cursor или Claude Desktop; исправьте каждую ошибку перед продолжением.
5. Напишите system instructions, которые говорят модели, когда вызывать какой tool и что никогда не выдумывать.
6. Откройте Бюджет токенов, выберите cl100k_base или o200k_base и подтвердите, что суммарный итог помещается в вашу модель.
7. Экспортируйте OpenAI tools JSON для API, MCP-конфиг для десктопного клиента и markdown-сводку для команды.
8. Опционально экспортируйте полный bundle JSON, чтобы другой инженер мог позже перезагрузить то же состояние сессии.

Проблема: нужен агент поддержки, который ищет погоду и заказы через OpenAI function calling, но рукописная JSON Schema снова и снова не проходит строгую валидацию.

Как этот инструмент решает задачу

1. Выберите режим Function calling или загрузите шаблон OpenAI function calling (погода + поиск заказа).
2. Отредактируйте пример JSON так, чтобы каждое нужное в production поле появилось хотя бы раз — отсутствующие ключи не станут required свойствами.
3. Включите строгий режим, чтобы каждый объект выдавал additionalProperties: false.
4. Ужесточите system prompt: подтверждайте ID заказов, никогда не выдумывайте результаты tools, держите ответы краткими.
5. Проверьте бюджет токенов под o200k_base, если деплоите на GPT-4o.
6. Экспортируйте OpenAI tools JSON и вставьте в клиент Chat Completions или Responses API.

Итог: строгий, готовый к API массив tools плюс промпт, согласованный со схемами — без отдельного редактора схем.

Проблема: Cursor или Claude Desktop отклоняют ваш mcp.json, или filesystem-сервер стартует с неверной директорией и видит слишком много диска.

Как этот инструмент решает задачу

1. Выберите режим Настройка MCP или загрузите шаблон Filesystem MCP.
2. Замените /path/to/allowed/dir абсолютным путём к единственной директории, к которой агент может обращаться.
3. Запустите проверку — исправьте отсутствующие command/args, неверные URL и нестроковые значения env.
4. Используйте placeholder-значения env (не production-секреты) при lint в браузере.
5. Экспортируйте проверенный mcpServers JSON в конфиг Cursor или Claude Desktop.
6. Добавьте system instructions, требующие подтверждения перед разрушительными файловыми операциями.

Итог: проверенный lint’ом MCP-клиентский конфиг и промпт, согласованный с возможностями сервера, до перезапуска десктопного приложения.

Проблема: модель должна вернуть тональность, уверенность, темы и краткое резюме как JSON — свободный текст ломает ваш downstream-парсер.

Как этот инструмент решает задачу

1. Выберите режим Структурированный ответ или загрузите шаблон структурированного классификатора.
2. Отредактируйте пример JSON под точную форму, которую ожидает ваш пайплайн.
3. Включите строгий режим, чтобы необъявленные ключи отклонялись при валидации.
4. Напишите system prompt, запрещающий прозу вне JSON-объекта.
5. Экспортируйте response_format json_schema для OpenAI structured outputs.
6. Убедитесь, что бюджет токенов ещё оставляет место для входного документа, который вы классифицируете.

Итог: одна выходная схема, которую можно вставить в structured-output API с соответствующими инструкциями.

Проблема: после добавления трёх tools и длинного MCP-конфига суммарный промпт агента больше не помещается в практический бюджет GPT-4o, когда включена история чата.

Как этот инструмент решает задачу

1. Откройте шаг Бюджет токенов и отметьте суммарный итог prompt + минифицированные tools + MCP JSON.
2. Сократите описания tools и удалите неиспользуемые поля примера, раздувающие required-схемы.
3. Вынесите многословный policy-текст из всегда включённого system prompt в on-demand retrieval.
4. Если нужна только более глубокая математика encoding, скопируйте собранный payload в LLM Token Counter.
5. Повторно экспортируйте только когда бюджет показывает комфортный запас для истории и completions.

Итог: вы ловите переполнение в builder — а не после первой production-ошибки 400.

Пример JSON должен быть строгим JSON. Только ключи из примера становятся required свойствами. Вложенные объекты и массивы выводят типы из значений образца.

Практические правила

• Включите каждое поле, которое модель должна иметь право отправить — пропуск значит «не required», а не «опционально с default».
• Используйте реалистичные enum как строковые образцы, затем вручную правьте схему, если нужен явный массив enum.
• Включите строгий режим, чтобы выдавать additionalProperties: false на каждом объекте — рекомендуется для OpenAI structured outputs и strict tool calling.
• Пустые массивы выводят слабые типы элементов — добавьте хотя бы один репрезентативный элемент.

Stdio-серверам нужны command и обычно args. Удалённым серверам нужен валидный http или https url. Значения env должны быть строками. Ошибки блокируют уверенность экспорта; предупреждения заслуживают ручного прохода.

Типичные клиентские envelope

• Ключ верхнего уровня должен быть "mcpServers" по соглашениям Cursor и Claude Desktop
• Filesystem-серверы должны использовать абсолютные пути allow-list
• Предпочитайте placeholder env при правке в браузере; реальные секреты внедряйте только на локальной машине

Подсчёт токенов объединяет system prompt, минифицированные схемы tools и MCP JSON. Выберите cl100k_base для приближения GPT-4 / Claude или o200k_base для GPT-4o. Подсчёт использует локальные таблицы tiktoken — без вызовов API.

• Считайте число нижней границей: история чата и результаты tools добавляют ещё на runtime
• Перепроверяйте после каждого изменения схемы или промпта
• Используйте LLM Token Counter, когда нужны карты границ или карточки месячной стоимости на кастомном payload

Симптомы: OpenAI отклоняет payload tools, или модель не может передать аргументы, которые реально нужны вашему приложению.

Почему это происходит

Строгие схемы отклоняют необъявленные ключи. Если пример JSON опустил поле, оно никогда не стало свойством. Если строгий режим выключен, лимиты OpenAI structured-output всё равно могут отклонять открытые объекты.

Диагностика

Сравните properties выведенной схемы с аргументами, которые отправляет приложение. Убедитесь, что строгий режим включён при нацеливании на OpenAI structured outputs.

Исправления

1. Добавьте недостающие ключи в пример JSON и перегенерируйте схему.
2. Включите строгий режим, чтобы additionalProperties: false был согласован на вложенных объектах.
3. Сократите неподдерживаемые конструкции (глубоко вложенный oneOf, экзотические типы) по лимитам structured output OpenAI.
4. Повторно экспортируйте tools JSON и перепроверьте известным корректным payload аргументов.

Симптомы: ошибки валидации на command/url, клиент не может запустить сервер, или удалённый транспорт никогда не подключается.

Почему это происходит

Записи stdio без command, удалённые без http(s) URL, числовые значения env или неверные ключи верхнего уровня ломают парсеры клиента.

Диагностика

Прочитайте JSON pointer каждой ошибки lint. Подтвердите, что envelope использует mcpServers и что каждый сервер либо stdio (command), либо remote (url), а не сломанный гибрид.

Исправления

1. Добавьте command и args для stdio-серверов; заключайте все значения env в кавычки как строки.
2. Используйте URL http:// или https:// для удалённых MCP-транспортов.
3. Исправьте имя ключа верхнего уровня на mcpServers.
4. Повторяйте проверку, пока ошибки не исчезнут; разберите предупреждения перед релизом.

Симптомы: API-ключи появляются в экспортированном JSON, git-diff или скриншотах builder.

Почему это происходит

Блоки env MCP — обычный JSON. Вставка production-секретов в браузерный инструмент — даже локальный — повышает риск утечки через буфер обмена, демонстрацию экрана и случайные коммиты.

Диагностика

Ищите в экспортах и панели MCP шаблоны sk-, Bearer или ключи вендоров. Проверьте, что закоммиченные конфиги содержат только placeholder’ы.

Исправления

1. Замените секреты на placeholder’ы вида ${ENV_VAR} в builder.
2. Внедряйте реальные значения только в локальном десктопном клиенте или хранилище секретов деплоя.
3. Ротируйте любой ключ, вставленный в чат, тикеты или общие экраны.
4. Добавьте pre-commit сканирование секретов для mcp.json и файлов bundle агента.

Это рабочее пространство не загружает ваш конфиг — но буфер обмена и git всё ещё могут его утечь.

• Никогда не коммитьте API-ключи в блоках env MCP — используйте placeholder переменных окружения
• Используйте абсолютные пути с минимальными привилегиями для filesystem MCP-серверов
• Проверяйте бюджет токенов перед добавлением больших few-shot примеров в production-промпты
• Предпочитайте строгие схемы, чтобы tools не принимали неожиданные ключи
• Считайте экспортированные bundle чувствительными, если они содержат внутренние имена tools или хосты инфраструктуры

• Начинайте с шаблона, затем удаляйте ненужные tools — меньшие схемы дешевле и безопаснее
• Называйте tools ясными глаголами (lookup_order, get_weather), совпадающими с инструкциями system prompt
• Держите один источник истины: экспортируйте из этого builder вместо расходящихся копий схем
• Повторно проверяйте MCP после каждого изменения пути или command
• Документируйте бюджет токенов в markdown-экспорте, чтобы ревьюеры видели влияние на стоимость в PR
• Используйте LLM Token Counter для глубоких diff encoding; этот builder — для собранного агента