Внешний кодовый агент
Как подключить исполнителя, который работает в GitHub Actions и открывает pull request — workflow, секреты, список репозиториев, токен, манифест, запуск, одобрение и типовые отказы.
Внешний кодовый агент на живом репозитории не проверялся: сценарий собран по
коду и тестам версии 0.9.2, но целиком, от сообщения до PR, его никто не
прогонял. Работа агента через шлюз колыбели (Anthropic-совместимый
/v1/messages, ANTHROPIC_BASE_URL) не подтверждена: в примере ниже агент
ходит в Anthropic по собственному ANTHROPIC_API_KEY. Первые запуски делайте
на тестовом репозитории.
Лид команды поручает задачу исполнителю с внешним исполнением. Колыбель не
вызывает для него модель, а после вашего одобрения запускает в репозитории
GitHub Actions workflow; агент работает в ветке cradle/<id задачи> и открывает
pull request, колыбель проверяет его по CI. Сливает PR только человек.
1. Положите workflow в репозиторий
Файл .github/workflows/cradle-task.yml (имя фиксировано: колыбель запускает
именно его через workflow_dispatch с входами task_id, prompt и
base_branch). Рабочая часть образца:
name: Cradle task
# Cradle finds the run by the task id in its title.
run-name: cradle task ${{ inputs.task_id }}
on:
workflow_dispatch:
inputs:
task_id:
description: Cradle task id; the branch is cradle/<task_id>
required: true
type: string
prompt:
description: What the agent has to do
required: true
type: string
base_branch:
description: Branch the pull request goes into
required: true
type: string
default: main
permissions:
contents: write
pull-requests: write
jobs:
agent:
runs-on: ubuntu-latest
timeout-minutes: 30
env:
TASK_ID: ${{ inputs.task_id }}
BASE_BRANCH: ${{ inputs.base_branch }}
GH_TOKEN: ${{ secrets.CRADLE_GITHUB_TOKEN }}
steps:
- name: Check out the base branch
uses: actions/checkout@v4
with:
ref: ${{ inputs.base_branch }}
fetch-depth: 0
token: ${{ secrets.CRADLE_GITHUB_TOKEN }}
- name: Create the branch cradle/<task_id>, or carry on in it
run: |
git config user.name "cradle-agent"
git config user.email "cradle-agent@users.noreply.github.com"
if git ls-remote --exit-code --heads origin "cradle/${TASK_ID}" > /dev/null; then
# Cradle sent the task back (failed checks): work in the branch of the open pull request, do not start a new one.
git fetch origin "cradle/${TASK_ID}"
git switch -C "cradle/${TASK_ID}" "origin/cradle/${TASK_ID}"
else
git switch -c "cradle/${TASK_ID}"
fi
echo "START_SHA=$(git rev-parse HEAD)" >> "$GITHUB_ENV"
- name: Run the agent
uses: anthropics/claude-code-action@v1
with:
prompt: ${{ inputs.prompt }}
github_token: ${{ secrets.CRADLE_GITHUB_TOKEN }}
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: --max-turns 30
- name: Commit what is left, push the branch and open the pull request
run: |
# The action may leave its edits uncommitted: commit them, if there are any.
git add -A
if ! git diff --cached --quiet; then
git commit -m "Cradle task ${TASK_ID}"
fi
# The branch is where it was before the agent: there is nothing new to put into a pull request.
if [ "$(git rev-parse HEAD)" = "${START_SHA}" ]; then
echo "::error::агент не внёс изменений: в ветке cradle/${TASK_ID} нет новых коммитов"
exit 1
fi
git push origin "HEAD:refs/heads/cradle/${TASK_ID}"
# A return pushes to the branch of the pull request that is already open.
if [ "$(gh pr list --head "cradle/${TASK_ID}" --state open --json number --jq length)" = "0" ]; then
gh pr create --head "cradle/${TASK_ID}" --base "${BASE_BRANCH}" \
--title "Cradle task ${TASK_ID}" \
--body "Opened by the external executor of Cradle for task ${TASK_ID}."
fiНазвание запуска (run-name) содержит id задачи — по нему колыбель находит
запуск. Последний шаг коммитит правки, которые действие оставило в рабочем
дереве; если ветка не отличается от базовой, шаг падает с текстом «агент не внёс
изменений», и PR не открывается.
Как проверить. Вкладка Actions репозитория показывает workflow «Cradle task» с кнопкой «Run workflow».
Если нет. Workflow не виден — файл не в базовой ветке или путь другой.
2. Секреты репозитория и права токенов
В настройках репозитория (Secrets → Actions) задайте:
CRADLE_GITHUB_TOKEN— токен GitHub App или PAT с правом создавать ветки и PR (contents: write,pull-requests: write), без права слияния. НеGITHUB_TOKEN: коммиты и PR, сделанные им, не запускают CI.ANTHROPIC_API_KEY— ключ для агента.
Защиту базовой ветки (обязательное ревью, запрет прямого push) включите на стороне GitHub.
Не давайте токенам право менять файлы workflow (workflows у PAT,
Workflows у GitHub App): иначе агент сможет ослабить проверки CI в своём PR.
Отдельный токен понадобится колыбели (шаг 4): она вызывает GitHub API —
POST /repos/<репозиторий>/actions/workflows/cradle-task.yml/dispatches, а также
читает запуски workflow, pull request'ы (/pulls) и проверки коммита
(/commits/<sha>/check-runs, /commits/<sha>/status). Выдайте ему права,
достаточные для этих вызовов, и никаких лишних.
3. Создайте команду с внешним исполнителем
Исполнитель описывается полем execution манифеста cradle.team/v1
(Манифест команды); модель для него не
вызывается, репозиторий и базовая ветка заданы в самом поле. Сохраните манифест, подставив свой репозиторий:
{
"schema": "cradle.team/v1",
"name": "code-team",
"title": "Команда разработки",
"captain": {
"id": "dispatcher",
"title": "Диспетчер",
"prompt": "Ты — диспетчер команды разработки. Принимаешь входящую задачу и передаёшь её лиду tech-lead. Код не пишешь.",
"requirement": "general"
},
"checker": {
"id": "checker",
"title": "Проверяющий",
"prompt": "Ты — проверяющий. Сверяешь pull request исполнителя с постановкой и результатом CI. Ничего не сливаешь: PR сливает человек.",
"requirement": "general",
"onReject": "return-to-lead"
},
"leads": [
{
"id": "tech-lead",
"title": "Техлид",
"prompt": "Ты — техлид. Формулируешь задачу как чёткое поручение (контекст, что сделать, критерии приёмки, чего не трогать) и передаёшь внешнему исполнителю code-agent. Merge и push в основную ветку запрещены: PR сливает только человек.",
"requirement": "reasoning",
"sources": ["api"],
"members": [
{
"id": "code-agent",
"title": "Кодовый агент",
"prompt": "Внешний кодовый агент (Claude Code в GitHub Actions). Работает в ветке cradle/<задача> и открывает pull request.",
"category": "coding",
"execution": {
"kind": "external",
"repository": "your-org/your-repo",
"baseBranch": "main"
}
}
]
}
]
}Лид принимает сообщения только из HTTP API ("sources": ["api"]). Импортируйте
манифест на странице любой команды: Импорт → вставьте JSON → Проверить →
Создать команду (Команда). Для лида и Checker нужны
модели (Ключи и модели); если лид и Checker работают на
облачных моделях, переключите контур: cradle teams update code-team --contour cloud.
Как проверить. План показывает "valid":true; в ответе есть предупреждение
repository_not_allowed — это нормально до шага 4; после создания на канвасе
команды четыре агента, у «Кодовый агент» репозиторий.
Если нет. missing.models блокирует применение — зарегистрируйте
недостающие модели; ошибка с путём JSON Pointer — поправьте поле.
4. Разрешите репозиторий и задайте токен
Это действия администратора организации (скоуп org:admin: ключ admin:* или
человек с ролью owner или admin); ни экрана в консоли, ни команды CLI для них
нет, поэтому даны вызовы POST /api/v1/rpc/teams:setCodeRepositories и
POST /api/v1/rpc/teams:setCodeToken.
В манифест ни список, ни токен не входят. Команда должна уже существовать.
Разрешённые репозитории команды: аргументы — slug команды и список owner/name.
curl -s -X POST http://127.0.0.1:31416/api/v1/rpc/teams:setCodeRepositories \
-H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"args":["code-team",["your-org/your-repo"]]}'Токен GitHub команды; null вместо токена удаляет его:
curl -s -X POST http://127.0.0.1:31416/api/v1/rpc/teams:setCodeToken \
-H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"args":["code-team","<github-token>"]}'Токен (8–500 символов) хранится зашифрованным и нигде не возвращается; на команду
одна запись, повторный вызов заменяет её. Вместо slug можно передать null:
общий токен колыбели, его задаёт только оператор с доступом ко всем командам.
Как проверить. Ответы {"result":{"ok":true,"slug":"code-team","repositories":["your-org/your-repo"]}}
и {"result":{"ok":true,"hasToken":true}}.
Если нет. the cradle cannot encrypt secrets on this host: the token is not stored — у сервера нет ключа шифрования (CRADLE_SECRET_KEY или записываемый
каталог данных для secret.key); invalid input: … — токен короче 8 символов
или slug неверного вида.
5. Запустите задачу и одобрите её
Отправьте команде сообщение через HTTP API ключом этой команды (Каналы):
curl -sS -X POST http://127.0.0.1:31416/api/v1/messages \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"text":"Add an Installation section to the README","chatId":"task-1","mode":"async"}'Если лид выбрал поручить задачу исполнителю code-agent, в «Ждут решения»
появляется тикет с причиной tool_approval: колыбель просит разрешить запуск
code.dispatch. Каждый запуск ждёт человека. Одобрите его (Ждут решения,
раздел «Одобрение вызова инструмента»); отклонение завершает задачу ошибкой.
Как проверить. После одобрения в разговоре (страница Разговоры) —
сообщение «Задача отправлена исполнителю «Кодовый агент». Когда он откроет PR, я
напишу.»; в Actions репозитория идёт запуск cradle task <id задачи>; ответы бота по этому
чату можно забрать вызовом GET /api/v1/messages/task-1.
Если нет. Тикета нет — лид ответил сам или позвал человека (посмотрите причину удержания); сообщение «Не получилось: …» — причина из таблицы ниже.
6. Что происходит дальше и что видно
Колыбель раз в 2 минуты ищет PR из ветки cradle/<id задачи>:
| Что в разговоре | Что произошло |
|---|---|
Исполнитель открыл PR: <ссылка>. Идёт проверка. | PR найден, задача in_review |
PR прошёл проверки: <ссылка>. Слияние — за человеком. | PR из cradle/<id> в базовую ветку разрешённого репозитория не слит, а все проверки завершены успешно (success, neutral, skipped): задача done |
| «CI в PR красный (…). Жду решения оператора: вернуть задачу исполнителю.» | первая красная проверка: в «Ждут решения» тикет tool_approval — одобрение запускает агента снова в той же ветке |
| «Задача возвращена исполнителю …» | возврат одобрен |
| «Не получилось: …» | задача failed |
Если после возвращения проверки снова красные, задача failed, а оператору
приходит тикет task_ci_failed со ссылкой на PR и перечнем упавших проверок.
Сроки (поля settings.codeRunner в app-state.json каталога данных): опрос
pollMinutes — 2 минуты; ожидание PR после отправки timeoutMinutes — 60;
ожидание незавершённых проверок checksTimeoutMinutes — 60. Если у PR за 10
минут нет ни одной проверки, задача failed («нет CI»).
7. Типовые отказы
Причину колыбель пишет в разговор строкой «Не получилось: …»:
| Сообщение | Причина | Что делать |
|---|---|---|
repository <репо> is not in the code repositories of team <slug>: an organization admin must allow it (teams:setCodeRepositories) | репозиторий не разрешён команде | шаг 4 |
no GitHub token: add a "github" key to the provider credentials of the team … | у команды нет токена | teams:setCodeToken, шаг 4 |
agent "<имя>" is not an external executor | у агента нет execution | шаг 3 |
GitHub refused workflow_dispatch of cradle-task.yml in <репо>: HTTP <код> … | нет файла workflow в базовой ветке, самой ветки или прав у токена | шаги 1–2 |
запуск workflow завершился с результатом «failure», PR нет: <ссылка> | запуск workflow упал | откройте ссылку на запуск и разберите его журнал |
запуск workflow не найден и PR нет за N мин после отправки или PR не появился за N мин после отправки | workflow не стартовал или не открыл PR | журнал Actions, шаг 1 |
в репозитории нет CI: за 10 мин у PR не появилось ни одной проверки | в репозитории нет проверок для PR | настроить CI |
проверки PR красные и после возвращения: … | CI красный дважды | разобрать PR вручную |
Ждут решения
Что происходит с сообщением, когда оно ждёт человека, причины удержания, одобрение ответа и одобрение вызова инструмента.
Обзор архитектуры
Как Cradle устроен как хост-независимое ядро с одной точкой входа — headless-сервером cradle-server и веб-консолью — и как сообщение проходит от начала до конца.