ИИ-агенты

С помощью Semaphore UI вы можете запускать ИИ-агентов для программирования: Claude Code и Codex. Шаблон агента запускает инструмент командной строки агента в каталоге репозитория и передаёт ему промпт. Агент работает самостоятельно — отвечать на его вопросы некому — и пишет о том, что делает, в лог задачи.

примечание

Шаблоны ИИ-агентов доступны начиная с Semaphore 2.21.

Используйте шаблон агента для работы, которую иначе вы описали бы коллеге: проверить последний коммит, найти и исправить падающий тест, обновить зависимость и открыть pull request. Как и любой другой шаблон, его можно запустить вручную, по расписанию, через интеграцию или из рабочего процесса.

Прежде чем начать

Инструмент командной строки агента установлен на машине, которая выполняет задачи: на сервере Semaphore или на раннере.

Приложение Идентификатор Команда Установка
Claude Code Agent claude claude npm install -g @anthropic-ai/claude-code
Codex Agent codex codex npm install -g @openai/codex

Semaphore включает приложение, если при запуске находит его команду в PATH. Администратор также может включить его и задать путь к исполняемому файлу на странице Applications.
Ключ API провайдера модели, см. Ключ API.
Репозиторий, в котором работает агент, добавленный в раздел Repositories.

Приложение	Идентификатор	Команда	Установка
Claude Code Agent	`claude`	`claude`	`npm install -g @anthropic-ai/claude-code`
Codex Agent	`codex`	`codex`	`npm install -g @openai/codex`

Создание шаблона

Перейдите в раздел Task Templates, нажмите New Template, а затем Claude Code Agent или Codex Agent.

Меню New Template с пунктами Claude Code Agent и Codex Agent

Настройте шаблон.

Редактор шаблона Claude Code Agent

Шаблон позволяет задать следующие параметры:

Поле	Описание
Repository	Репозиторий, в котором работает агент. Semaphore клонирует или обновляет его перед задачей, как и для любого другого шаблона.
Subdirectory path	Необязательно. Каталог репозитория, в котором запускается агент. Если не задан, агент запускается в корне репозитория.
MCP servers	Необязательно. Инвентарь MCP с серверами, инструменты которых агент может вызывать, см. MCP-серверы.
Variable Groups	Переменные и секреты для агента: ключ API, значения для выражений в промпте, переменные окружения процесса агента.
Prompt	Инструкция, с которой запускается агент, см. Промпт.
CLI args	Дополнительные аргументы команды агента, см. Аргументы CLI.
Survey Variables	Вопросы, которые задаются при запуске задачи. Ответы можно подставить в промпт.
Флажок Prompt	В разделе Claude Code prompts или Codex prompts. Позволяет тому, кто запускает задачу, заменить промпт, см. Промпт задачи.

Нажмите Save, затем запустите шаблон кнопкой Run.

Ключ API

Агент берёт ключ API из переменной окружения. Добавьте ключ в группу переменных шаблона как секретную переменную окружения:

Приложение	Переменная	Также принимается
Claude Code Agent	`ANTHROPIC_API_KEY`	`CLAUDE_CODE_OAUTH_TOKEN`
Codex Agent	`OPENAI_API_KEY`	`CODEX_API_KEY`

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

Если ни одна из переменных не задана, в логе задачи будет указано, какую из них добавить, после чего сам агент завершится со своей ошибкой:

No API key for claude: add ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as a secret of the template's Variable Group

Промпт

Промпт — это то, что вы ввели бы в агент: обычный текст любой нужной длины. Он передаётся агенту через стандартный ввод, поэтому не появляется в списке процессов.

Промпт обязателен, если только флажок Prompt не позволяет задаче передать собственный.

Выражения в промпте

Промпт шаблона может использовать значения из групп переменных шаблона. Напишите выражение в двойных фигурных скобках, как в GitHub Actions, и Semaphore заменит его при запуске задачи:

Выражение	Значение
`${{ vars.extra.NAME }}`	Дополнительная переменная (extra) группы переменных.
`${{ vars.env.NAME }}`	Переменная окружения группы переменных.
`${{ secrets.extra.NAME }}`	Секретная дополнительная переменная группы переменных.
`${{ secrets.env.NAME }}`	Секретная переменная окружения группы переменных.

Find the flaky tests in services/api and fix them.
Open a pull request against ${{ vars.extra.base_branch }} and post its link
to ${{ vars.env.TRACKER_URL }} with the token ${{ secrets.env.TRACKER_TOKEN }}.

Правила:

Survey-переменные — это дополнительные переменные: ответ на survey-переменную version — это ${{ vars.extra.version }}, а на секретную — ${{ secrets.extra.NAME }}. Survey-переменная, которая передаётся как переменная окружения, находится в env. Survey-переменная, оставленная без ответа, даёт пустую строку.
Несуществующая переменная приводит к ошибке задачи ещё до запуска агента, с сообщением, в котором названо выражение. Semaphore не запускает агента с пробелом в промпте.
Выражение с ошибкой отклоняется при сохранении шаблона: в ${{ secrets.TOKEN }} нет ни extra, ни env.
Остальные выражения остаются как есть. Semaphore принадлежат только vars.… и secrets.…, поэтому в промпте можно попросить агента написать workflow, содержащий ${{ github.sha }}. Чтобы оставить выражение vars или secrets текстом, поставьте перед ним ещё один знак доллара: $${{ secrets.env.NAME }}.
Значение подставляется как есть. Строка используется в том виде, в каком записана, список или объект — в виде JSON. Подставленное значение повторно на выражения не проверяется.
Секрет, подставленный в промпт, маскируется в логе задачи везде, где агент его повторяет.

внимание

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

Промпт задачи

Если флажок Prompt включён, форма задачи показывает промпт шаблона и позволяет изменить его для одного запуска. Расписание, интеграция или шаг рабочего процесса могут точно так же хранить собственный промпт. Через API передавайте его в параметрах задачи:

{
  "template_id": 12,
  "params": {
    "prompt": "Review the changes of the last release and list the risky ones."
  }
}

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

MCP-серверы

Агент может вызывать инструменты удалённых серверов MCP: трекера задач, поиска по документации, вашего собственного сервиса. Серверы хранятся в инвентаре типа MCP Inventory, и один инвентарь подходит для шаблонов и Claude Code, и Codex.

Перейдите в раздел Inventory, нажмите New Inventory, а затем MCP Inventory.
Добавьте серверы и нажмите Save.
Выберите инвентарь в поле MCP servers шаблона.

Форма инвентаря MCP с тремя серверами

Поле	Описание
Переключатель	Выключенный сервер остаётся в списке, но агенту не передаётся.
Name	Имя, под которым агент знает сервер: до 64 букв, цифр, `-` и `_`. Оно отображается в логе задачи перед названием инструмента.
URL	Адрес `http` или `https` сервера, который работает по MCP через HTTP или SSE. Имя пользователя или пароль в URL не принимаются.
Token	Необязательно. Агент отправляет его в заголовке `Authorization` как bearer-токен.

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

Инструменты выбранных серверов разрешены заранее, поскольку подтверждать вызов некому. Агент получает именно эти серверы: MCP-серверы, настроенные для пользователя, от имени которого работает Semaphore, не используются.

Аргументы CLI

CLI args добавляются к команде агента после аргументов, которые Semaphore задаёт сам. Вводите каждый токен отдельным аргументом:

["--model", "claude-sonnet-5-5"]

Используйте их для того, что предлагает командная строка самого агента: модель, лимиты, разрешения. Агент работает без присмотра, поэтому инструмент, который запросил бы подтверждение, вместо этого отклоняется; какие инструменты агент может использовать без запроса, задаётся его аргументами. Параметры вашей версии см. в справочнике по CLI Claude Code и справочнике по CLI Codex.

Если в разделе Prompts включён флажок CLI args, задача может добавить собственные аргументы.

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

Как запускается агент

Semaphore запускает агента в каталоге репозитория или в его подкаталоге Subdirectory path, передавая промпт через стандартный ввод:

Приложение	Команда
Claude Code Agent	`claude -p --output-format=stream-json --verbose --include-partial-messages --mcp-config=<file> --strict-mcp-config --no-session-persistence [--allowedTools=mcp__<server>__*,…] <CLI args>`
Codex Agent	`codex exec --json --skip-git-repo-check <CLI args> -`

У каждой задачи свой каталог конфигурации агента (CLAUDE_CONFIG_DIR, CODEX_HOME), который создаётся для задачи и удаляется после неё. Настройки, учётные данные и MCP-серверы пользователя, от имени которого работает Semaphore, к агенту не попадают, а переменная из группы переменных не может перенаправить этот каталог.
Между задачами ничего не сохраняется: каждый запуск — это новая сессия агента. То, что должно пережить запуск, должно оказаться в репозитории: коммит, pull request, файл.
Агент читает файлы инструкций репозитория, которые его инструмент командной строки сам читает в рабочем каталоге, например CLAUDE.md или AGENTS.md.
На раннерах Docker и Kubernetes агент работает в контейнере, поэтому образ исполнителя должен содержать команду claude или codex.

Лог задачи

Лог задачи показывает работу агента по мере её выполнения:

Лог задачи Claude Code: модель, вызовы инструментов, субагент, итоговая сводка

Текст агента, строка за строкой. Codex выводит сообщение, когда оно готово целиком.
Вызовы инструментов, каждый в одной строке: состояние, MCP-сервер и инструмент, аргументы. Щёлкните по строке, чтобы увидеть аргументы и результат. Неудачный вызов раскрыт сразу.
Субагенты: строки субагента помечены его именем.
Первая строка запуска Claude Code называет модель и MCP-серверы; те, что не подключились, выделены красным.
Сводка в конце: число ходов, длительность, токены и стоимость — в той мере, в какой агент о них сообщает.

Raw log показывает тот же лог обычным текстом.

Безопасность

Агент выполняет команды. В пределах разрешений, которые даёт ему его инструмент командной строки, агент может читать и изменять каталог репозитория, запускать программы от имени пользователя, выполняющего задачи, и вызывать инструменты своих MCP-серверов. Давайте шаблону агента такой доступ, какой вы дали бы скрипту, написанному кем-то другим: репозиторий и токены с самыми узкими правами, достаточными для работы, и отдельный раннер для работы, которую вы хотите изолировать от сервера.
Промпт и всё, что читает агент, отправляется провайдеру модели: файлы репозитория, вывод команд, результаты инструментов.
Репозиторий может давать агенту указания. Текст в файлах, которые читает агент, в issue или в результате инструмента может изменить то, что делает агент. Не направляйте агента с мощными токенами на содержимое, которое вы не контролируете.
Токены и секреты маскируются в логе задачи: токены MCP-серверов и секреты, подставленные в промпт, заменяются на ********.
Использовать переменные и секреты может только промпт, сохранённый в шаблоне, см. Промпт задачи.

Прежде чем начать​

Создание шаблона​

Ключ API​

Промпт​

Выражения в промпте​

Промпт задачи​

MCP-серверы​

Аргументы CLI​

Как запускается агент​

Лог задачи​

Безопасность​