Как создать ИИ-агента одним файлом

Что значит создать ИИ-агента?

Коротко: Создать ИИ-агента в Claude Code или Codex - значит написать один текстовый файл, в котором сказано, кто этот агент и когда его звать. Ни кода, ни сервера, ни ключей к сторонним сервисам для этого не нужно. Дальше инструмент сам подхватывает файл и передаёт агенту подходящие задачи.

Если ты открывал руководства по этой теме, то видел три разных маршрута: одни предлагают склонировать репозиторий и раздобыть семь ключей, другие ведут в визуальный конструктор, третьи начинают с установки Python. Все три про настоящих агентов. Просто ни один из них не отвечает человеку, у которого уже стоит Claude Code или Codex и который хочет своего помощника под свои задачи.

Ответ для этого случая короткий. Чтобы создать ИИ-агента здесь, ты пишешь текстовый файл и кладёшь его в определённую папку. Всё.

Файл содержит две вещи: короткое описание, задающее, когда этого агента применять, и инструкцию самому агенту - как себя вести, что можно трогать, что возвращать. Документация Anthropic описывает субагентов Claude Code дословно так: Subagents are Markdown files with YAML frontmatter. По-русски: субагенты - это markdown-файлы с настройками в шапке.

Сразу оговорюсь, на чём эта статья стоит. Я не снимал здесь свой экран и не проходил установку на чистой машине: всё ниже собрано по документации Anthropic и OpenAI на 27 сентября 2026 года, с прямыми ссылками в конце. Где вендор говорит дословно, я привожу цитату и перевод. Про непроверенное прямо пишу, что оно непроверенное.

Какого агента ты собрался создать?

Коротко: Словом «агент» называют четыре разные вещи: помощника у себя на компьютере, бота для клиентов в переписке, программу на SDK вендора и сценарий в визуальном конструкторе. Маршруты у них несовместимые. Эта статья про первый, потому что именно его ищут люди, у которых уже установлен Claude Code или Codex.

Путаница тут стоит людям вечеров. Человек читает про агентов вообще, открывает руководство про другой класс и упирается в стену из требований, которых его задача не предполагала.

Проверить, туда ли ты попал, можно за секунду. Нужно, чтобы кто-то разбирал папку с файлами, читал документы, правил тексты и запускал проверки на твоей машине - читай дальше. Ищешь того, кто будет отвечать покупателю в чате, - это соседний рынок, и о нём я здесь не пишу. Создать ИИ-агента для второго случая тоже можно, но маршрут будет другой, и начинается он не с файла.

Термин сам по себе разобран отдельно: что такое агент в словаре.

Чем агент отличается от чата и от готового сценария?

Коротко: Разница в том, кто решает порядок действий. В сценарии порядок прописан заранее человеком, у агента модель сама выбирает шаги и инструменты по ходу дела. Anthropic разводит эти два случая дословно и советует брать самое простое решение из возможных - иногда это означает не собирать агента вообще.

В разборе «Building effective agents» формулировка различия такая:

Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.

По-русски: воркфлоу - это системы, где модели и инструменты выстроены по заранее написанным путям в коде. Агенты - системы, где модели сами направляют свои процессы и применение инструментов, сохраняя контроль над тем, как они выполняют задачи.

Там же сказано, что слово многозначно: "Agent" can be defined in several ways. То есть разночтения в статьях про агентов - не следствие чьей-то безграмотности, так устроен сам термин.

И отдельная фраза оттуда, которую стоит прочитать до того, как создать ИИ-агента: we recommend finding the simplest solution possible, and only increasing complexity when needed. This might mean not building agentic systems at all. По-русски: советуем искать простейшее возможное решение и наращивать сложность только по необходимости; иногда это означает вообще не строить агентные системы.

Для нашей задачи вывод практический. Если тебе нужно один раз переписать текст - хватит обычного запроса в чат, промпт закроет вопрос. Свой агент оправдан тогда, когда ты ловишь себя на том, что раз за разом объясняешь одно и то же одними и теми же словами.

Что нужно проверить до того, как создать ИИ-агента?

Коротко: Три вещи, и все три быстрее проверить заранее, чем упереться в них на середине. Установлен ли инструмент, открыт ли у тебя доступ к модели по тарифу и подходит ли твоя система по требованиям вендора. Создать ИИ-агента файлом можно бесплатно. Деньги нужны для доступа к модели, которая будет за этим агентом работать.

Инструмент на месте. Свой агент работает внутри Claude Code или Codex, отдельно он не запускается. Если инструмента ещё нет, начни с установки: как установить Claude Code и как установить Codex.

Тариф. Тут у двух инструментов разные правила, и документация Anthropic говорит о своём прямо:

Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free claude.ai plan does not include Claude Code access.

По-русски: для Claude Code нужен аккаунт Pro, Max, Team, Enterprise или Console, а бесплатный план claude.ai доступа к Claude Code не включает. Где вообще проходит граница бесплатного у разных агентов, я разбирал отдельно: бесплатные ИИ-агенты и их предел.

Требования системы. В тех же требованиях Claude Code, наравне с оперативной памятью и версией системы, стоит строка Location: Anthropic supported countries - страна из списка поддерживаемых. Я открыл этот список и поискал по нему: России и Беларуси в нём нет ни одного вхождения. Перечня там два, отдельно для доступа к API и отдельно для claude.ai, и ни в одном из них этих стран нет.

Способов обойти это я не привожу и работоспособность таких способов не подтверждаю. Официального списка стран OpenAI я в этот раз не проверял, поэтому про Codex ничего подобного не утверждаю.

Шаг 1. Выбрать, где будет лежать файл агента

Коротко: От папки зависит, кому агент будет доступен. Положишь в проект - агент работает только там. В домашней папке инструмента он становится доступен во всех твоих проектах. У Claude Code это .claude/agents и ~/.claude/agents, у Codex - .codex/agents и ~/.codex/agents. Папки может ещё не быть - тогда её создают руками перед первым файлом.

Первое решение, когда ты собрался создать ИИ-агента, - в какой папке будет лежать его файл. Агент под конкретный проект ложится в папку внутри этого проекта, и его можно положить в репозиторий, чтобы им пользовалась вся команда. Универсальный помощник ложится в домашнюю папку инструмента и едет с тобой из проекта в проект.

Знак ~ в начале пути означает твою домашнюю папку пользователя. Создавать каталог агентов руками - обычное дело, и именно с этим связан самый частый затык новичка: инструмент, запущенный раньше новой папки, её не подхватит. Подробности - в разделе «Почему файл есть, а агента не видно?».

У Claude Code источников агентов больше четырёх, и при совпадении имён документация описывает порядок дословно: When multiple subagents share the same name, Claude Code uses the one from the higher-priority location. По-русски: когда несколько субагентов имеют одинаковое имя, Claude Code берёт того, что лежит в папке с более высоким приоритетом. Проект старше домашней папки, а настройки организации старше обоих.

Шаг 2. Написать файл агента

Коротко: Форматы у двух инструментов разные, и это первое место, где чужие инструкции перестают работать. Чтобы создать ИИ-агента для Claude Code, нужен markdown с YAML-настройками в шапке, обязательных полей там два. Codex вместо этого читает TOML, и обязательных полей у него три. Всё остальное можно не заполнять.

Вот минимальный агент для Claude Code. Файл ~/.claude/agents/redaktor.md:

---
name: redaktor
description: Вычитывает тексты статей и предлагает правки по ясности. Звать после того, как черновик написан.
tools: Read, Grep, Glob
model: sonnet
---

Ты редактор. Читаешь текст и возвращаешь список правок.
Для каждой правки: что не так, исходная фраза, предложенная замена.
Файлы не меняешь, только предлагаешь.

Три дефиса открывают настройки, три дефиса закрывают. Всё, что после них, становится системным промптом агента. Документация формулирует это дословно: The body becomes the system prompt that guides the subagent's behavior. Subagents receive only this system prompt plus basic environment details like the working directory, not the Claude Code system prompt. По-русски: тело файла становится системным промптом, который направляет поведение субагента; субагент получает только этот промпт и базовые сведения об окружении вроде рабочей папки, а системный промпт самого Claude Code ему не передаётся.

Отсюда следует практическое ограничение: агент не наследует контекст твоей переписки. Он приходит на задачу пустым. Значит, инструкция в теле файла должна быть самодостаточной.

Обязательных полей в шапке ровно два. Документация говорит: Only name and description are required. Поля tools и model в примере выше стоят по желанию: tools сужает набор доступных инструментов, model задаёт модель короткими именами вроде sonnet, opus или haiku. Опустишь их - агент унаследует настройки по умолчанию.

Тот же агент для Codex. Файл ~/.codex/agents/redaktor.toml:

name = "redaktor"
description = "Вычитывает тексты статей и предлагает правки по ясности. Звать после того, как черновик написан."
model_reasoning_effort = "medium"
developer_instructions = """
Ты редактор. Читаешь текст и возвращаешь список правок.
Для каждой правки: что не так, исходная фраза, предложенная замена.
Файлы не меняешь, только предлагаешь.
"""

Формат другой, смысл тот же. Документация OpenAI вводит перечень обязательного фразой Every standalone custom agent file must define: и дальше даёт список из трёх пунктов: name, description, developer_instructions. По-русски: каждый отдельный файл кастомного агента обязан задавать эти три поля. Три кавычки подряд открывают и закрывают многострочное значение - так инструкция пишется в несколько строк.

Создать ИИ-агента можно и не открывая редактор: обоим инструментам достаточно описать задачу словами и попросить написать файл самим. В документации Claude Code это первый из предложенных способов. Мастера в терминале там больше нет: по документации, начиная с версии v2.1.198 команда /agents перестала открывать интерактивное окно создания и печатает напоминание попросить Claude или отредактировать папку напрямую. Так что если ты нашёл руководство, которое начинается со слов «запусти /agents и жми Enter», оно устарело. Механизм агентов Claude Code со всеми полями разобран отдельно: агенты Claude Code.

Шаг 3. Позвать агента и убедиться, что он сработал

Коротко: Агент вызывается обычной просьбой: скажи инструменту словами, чтобы он применил агента по имени. Признак того, что делегирование случилось, - отдельная строка в переписке, где стоит имя агента и короткое описание задачи в скобках. Нет такой строки - значит, работу сделал основной сеанс. В Codex ветки запущенных агентов открываются командой /agent.

Позвать агента можно просто фразой. Например: примени агента redaktor к этому черновику.

Дальше надо убедиться, что инструмент действительно передал работу агенту. Создать ИИ-агента и добиться, чтобы его звали, - две разные задачи, и вторая обычно занимает больше времени. Проверка нужна по простой причине: ответ придёт в любом случае, и понять по тексту ответа, кто его написал, невозможно. Документация Claude Code описывает признак дословно: In the transcript, the delegation appears as a tool call row showing the subagent's name followed by a short task description, such as code-improver(Suggest code improvements). По-русски: в переписке делегирование выглядит строкой вызова инструмента, где стоит имя субагента и короткое описание задачи в скобках.

Такая строка в ленте подтверждает, что задача ушла агенту. Нет строки - агента не позвали, работу сделал основной сеанс.

В Codex проверка другая. Документация описывает команду для интерактивного сеанса: Use /agent to inspect and switch between agent threads while they run. По-русски: командой /agent открывают ветки агентов и переключаются между ними, пока те работают. Там же сказано, что главная ветка собирает результаты агентов в свой итоговый ответ.

Полезная привычка на первый раз: дай агенту задачу, ответ на которую ты знаешь заранее. Так ты отличишь «агент отработал» от «агент отработал правильно» - это разные проверки, и вторая без первой ничего не значит.

Я сам плачу за подписки на нейросети картой для подписок «Плати по миру»: выпускается за пару минут, пополняется рублями через СБП. Оформить карту

Что написать в описании, чтобы агента позвали?

Коротко: Поле description работает маршрутизатором: по нему инструмент решает, передавать задачу агенту или делать самому. Описание должности («помощник по текстам») задачу к агенту не приводит. Работает описание повода: «звать, когда черновик готов и нужна вычитка». Держи описание коротким: описания всех твоих агентов грузятся в контекст при каждом запуске.

Это самая частая причина, по которой человек считает, что создать ИИ-агента у него не получилось. Файл лежит, формат верный, а задачи уходят мимо. Дело в описании.

Инструмент читает description и сопоставляет с тем, что ты просишь. Значит, писать туда надо повод его позвать. Должность агента для этого поля бесполезна. Сравни:

Второе правило - краткость, и у неё есть измеримая причина. Описания всех твоих агентов грузятся в контекст постоянно. Документация Claude Code задаёт потолок дословно: When the combined descriptions of your subagents, except the built-in ones, exceed 15,000 tokens, Claude Code shows a warning at startup with the total token count. По-русски: когда суммарные описания твоих субагентов, кроме встроенных, превышают 15 000 токенов, Claude Code показывает при запуске предупреждение с общим числом токенов. Совет оттуда же: сокращать description, а подробности переносить в системный промпт агента, который грузится только при его запуске.

Почему файл есть, а агента не видно?

Коротко: Чаще всего потому, что папку агентов ты завёл уже после запуска сессии. Наблюдатель за папками подхватывает только те каталоги, которые существовали на момент старта, поэтому самый первый файл в новой папке становится виден лишь после перезапуска инструмента. Второе по частоте - имя: оба инструмента опознают агента по полю name внутри файла, и название файла на диске тут ни при чём.

Обычно правка файла подхватывается сама. Документация Claude Code описывает это дословно: Claude Code detects the change within a few seconds and the next delegation uses the updated definition, with no restart needed. По-русски: Claude Code замечает изменение за несколько секунд, и следующее делегирование идёт уже по обновлённому описанию, перезапуск не нужен.

Исключение там же, и оно ровно про твой первый агент: The watcher covers only directories that existed when the session started, so after creating a scope's first agent file in a new agents directory, restart to load it. По-русски: наблюдатель покрывает только те папки, которые существовали на момент старта сессии, поэтому после создания первого файла агента в новой папке нужен перезапуск.

Отдельная ловушка формата: в шапке Claude Code составные имена полей пишутся слитно со строчной буквы посередине, вроде disallowedTools. Документация предупреждает, что поле, которое инструмент не опознал, пропускается без ошибки. Поэтому опечатка в имени поля выглядит как «настройка не действует» и на сломанный файл совсем не похожа.

Нужно ли вообще создавать своего агента?

Коротко: Часто нет. В обоих инструментах уже есть встроенные агенты, и заметная часть задач закрывается ими: в Claude Code это Explore, Plan и general-purpose, в Codex - default, worker и explorer. Свой понадобится там, где под твой повод встроенного не нашлось. Пока такого повода нет, дешевле обойтись готовыми.

В Claude Code встроенные агенты работают по умолчанию. Explore ищет по файлам и умеет только читать: документация указывает на его наборе инструментов read-only tools; Write and Edit are denied - правка и запись ему запрещены. Plan собирает контекст для режима планирования, тоже без записи. General-purpose берётся за задачи, где нужно и поискать, и поменять.

У Codex набор свой, и документация перечисляет его дословно: default - универсальный запасной агент, worker - исполнитель под правки и починку, explorer - чтение и разбор кода. Там же сказано, что свой агент с именем встроенного перекрывает встроенный, так что имя explorer лучше не занимать по случайности.

Критерий, по которому стоит решать, звучит просто. Создать ИИ-агента имеет смысл тогда, когда ты раз за разом заводишь одного и того же исполнителя с одной и той же инструкцией. Пока ты этого за собой не замечаешь, встроенных хватает.

Заодно разведу соседние сущности, которые постоянно путают с агентом. Скилл - это навык, папка с инструкцией, которую инструмент подхватывает по описанию. CLAUDE.md и AGENTS.md - общие правила проекта. Про последний документация OpenAI говорит прямо: Codex reads AGENTS.md files before doing any work - Codex читает эти файлы до начала любой работы. То есть правила проекта действуют всегда, а агент подключается под повод. Сам формат AGENTS.md описан на отдельной странице, ссылка в источниках.

Во что обходится свой агент?

Коротко: Создать ИИ-агента ничего не стоит. Расходы начинаются, когда он работает. В Claude Code субагент шлёт собственные запросы, и они расходуют тот же лимит, что и основная переписка. В Codex сценарии с субагентами прямым текстом названы более расходными, чем работа одним агентом. Цен и лимитов по тарифам я здесь не привожу.

Документация Claude Code про субагента говорит дословно: It also sends its own requests, which count toward the same usage limits as your main conversation. По-русски: субагент отправляет собственные запросы, и они идут в тот же лимит, что и основная переписка.

OpenAI формулирует похоже: Because each subagent does its own model and tool work, subagent workflows consume more tokens than comparable single-agent runs. По-русски: поскольку каждый субагент выполняет собственную работу с моделью и инструментами, такие сценарии расходуют больше токенов, чем сопоставимый запуск одним агентом.

Практический вывод без цифр: экономия от агента приходит только с того момента, когда он снимает с тебя повторяющееся объяснение. Один разовый вопрос дешевле задать напрямую. Конкретные цены и границы тарифов я в этот раз не сверял и не привожу - страницы тарифов меняются чаще статей.

Пять ошибок, на которых теряют вечер

Коротко: Почти все пять - про несовпадение ожиданий с устройством инструмента: чужой формат файла, слабое описание, ожидание, что агент помнит переписку, попытка дать ему всё сразу и отказ после первого неудачного запуска. На этих же пяти спотыкаются и те, кто пробует создать ИИ-агента не в первый раз.

1. Взять формат из чужого руководства. Markdown-файл в папке агентов Codex и TOML-файл в папке Claude Code не сработают. Формат смотри по своему инструменту: Claude Code - markdown с YAML-шапкой, Codex - TOML.
2. Описать должность вместо повода. Формулировка Помощник по документации называет должность и задачу к агенту не приводит. Рабочее описание называет повод: Звать, когда нужно сверить текст с документацией.
3. Ждать, что агент помнит разговор. Он приходит пустым: получает только свой системный промпт и базовые сведения об окружении. Всё нужное для задачи должно быть в файле либо в самой формулировке задачи.
4. Запихнуть в одного агента всё. Описания грузятся в контекст постоянно, а размытая роль срабатывает реже точной. Держи одного агента под один повод.
5. Бросить после первого запуска. Первая версия описания почти никогда не попадает. Нормальный цикл: позвал, посмотрел на строку делегирования, поправил description, позвал снова.

Что дальше

Коротко: Начни с одного узкого агента для той задачи, которую повторяешь чаще всего, проверь строку делегирования и поправь описание. Первая формулировка почти никогда не попадает с первого раза, и это нормальный ход работы. Дальше - углубление по своему инструменту: механизм агентов Claude Code и разбор того, что агент Codex успевает за один круг.

Порядок на ближайший вечер выглядит так. Создать ИИ-агента под свою задачу можно в четыре шага:

1. Выбери одну задачу, которую объяснял инструменту больше трёх раз.
2. Заведи под неё файл в домашней папке инструмента: ~/.claude/agents/ или ~/.codex/agents/.
3. Позови агента по имени и посмотри, появилась ли строка делегирования.
4. Поправь описание и позови снова.

Что читать дальше:

• Агенты Claude Code - разбор механизма и всех полей файла у одного инструмента.
• Агент Codex - что он успевает сделать за один круг и где останавливается.
• Скиллы Claude Code - соседняя сущность, которую чаще всего путают с агентом.
• Локальный ИИ-агент - если хочется, чтобы модель работала на твоём железе.
• Что такое Codex - если инструмент пока незнакомый.

И последнее. Файл агента переносится между машинами и проектами обычным копированием, поэтому один раз написанный агент служит долго и его стоит сохранить. Готовые файлы, которые я собрал под свои задачи, лежат в базе знаний ClaudeBase - их можно положить к себе в папку агентов и позвать в тот же вечер. Пять таких файлов открыты без оплаты: юрист, финансист, ресёрч и ещё два агента - на них удобно посмотреть, как готовый агент устроен изнутри.