Агенты
Описывайте субагентов в Markdown с frontmatter в том же формате, что у ваших существующих файлов агентов, и передавайте им работу с чистым контекстом.
Субагент — это отдельный агент, которому основной агент может передать задачу. Он начинает с чистого контекста, выполняет работу со своими инструментами и инструкциями и возвращает отчёт. В основной разговор попадает только вывод, а не каждый файл, который прочитал субагент.
Используйте субагентов для:
- Исследования по многим файлам, когда вам нужен только ответ.
- Независимой параллельной работы. Агент может запустить несколько субагентов за один шаг.
- Специализированных ролей со своим промптом, инструментами и моделью: ревьюер, автор тестов, проверяющий документацию.
Определение агента
Субагент — это Markdown-файл. Frontmatter настраивает его, а тело файла — его системный промпт.
---
name: reviewer
description: Reviews a diff for correctness bugs. Use after making non-trivial changes, before reporting the work as done.
tools: Read, Grep, Glob, Bash(git diff *), Bash(git log *)
model: anthropic:claude-opus-5-5
effort: high
---
You review code changes for correctness. You never edit files.
1. Run `git diff` to see the changes.
2. For each change, read enough surrounding code to understand it.
3. Report bugs first, most severe first, each with file:line and a concrete failure scenario.
4. Then list simplifications, briefly.
If you find nothing wrong, say so plainly. Don't invent issues.Где хранятся агенты
| Область | Каталоги |
|---|---|
| Проект | .cusp/agents/, .claude/agents/ |
| Пользователь | ~/.cusp/agents/, ~/.claude/agents/ |
Агенты проекта переопределяют одноимённых агентов пользователя, а .cusp/ переопределяет .claude/ на том же уровне. О файлах, которые нельзя использовать, Cusp сообщает с указанием причины; молча они никогда не пропускаются.
Frontmatter
| Поле | Тип | Значение |
|---|---|---|
name | string | Обязательное. Тип агента, используется в вызовах Agent(…) и в правилах |
description | string | Обязательное. Когда основному агенту стоит его использовать |
tools | list | Инструменты, которые ему доступны. Если не указано, наследуются инструменты основного агента |
disallowedTools | list | Инструменты, которые ему запрещены |
model | string | Модель для запуска — в виде provider:model или просто id. Если не указано, наследуется |
effort | string | low, medium, high, xhigh или max |
permissionMode | string | default, acceptEdits, plan, auto, dontAsk или bypassPermissions |
maxTurns | number | Остановиться после этого числа ходов модели |
isolation | worktree | Работать в собственном git worktree. Обязательно для агентов, которые записывают файлы |
background | boolean | По умолчанию запускаться асинхронно |
skills | list | Навыки для предварительной загрузки |
mcpServers | list | MCP-серверы, которые он может использовать: имена настроенных серверов или встроенные определения |
hooks | object | Хуки, активные во время его работы. Хук Stop здесь становится SubagentStop |
memory | user, project или local | Область постоянного каталога памяти агента, где он может хранить заметки между запусками |
omitClaudeMd | boolean | Полностью пропустить файлы инструкций, чтобы агент работал «с чистого листа» |
initialPrompt | string | Первое сообщение, которое отправляется автоматически при запуске |
color | string | Цвет отображения: red, blue, green, yellow, purple, orange, pink или cyan |
tools принимает строку через запятую или список YAML. Элементами могут быть правила, например Bash(git diff *), чтобы ограничить инструмент конкретными вариантами использования.
Как их использует основной агент
Основной агент вызывает инструмент Agent:
| Параметр | Значение |
|---|---|
description | Короткая подпись, которая показывается в интерфейсе |
prompt | Полное описание задачи. Субагент не видит ваш разговор, поэтому описание должно быть самодостаточным |
subagent_type | Какого агента использовать. По умолчанию general-purpose |
model | Переопределить модель агента для этого вызова |
run_in_background | Вернуть управление сразу; основной агент получит уведомление, когда субагент закончит |
isolation | worktree, чтобы выделить ему собственный git worktree |
name | Имя, по которому к нему можно будет обратиться позже через SendMessage |
Основной агент остаётся единственным, кто пишет в вашу рабочую копию. Субагент, которому нужно записывать файлы, должен работать с isolation: worktree, чтобы его изменения оставались отдельно, пока вы их не сольёте.
Можно попросить конкретного агента в запросе («проверь это агентом reviewer»), а обычно агент сам выбирает подходящего по описаниям.
Как написать хорошее описание
Описание определяет, когда агент будет использоваться. Пишите его как указание основному агенту:
- Хорошо: «Reviews a diff for correctness bugs. Use after making non-trivial changes, before reporting the work as done.»
- Слабо: «Code review expert.»
Разрешения
Субагенты работают под тем же движком разрешений, что и основной агент. Их вызовы инструментов проверяются по вашим правилам, а запросы появляются там же. Какие агенты можно запускать, задаётся правилами вроде Agent(reviewer) в allow или deny.
Отчёт субагента приходит основному агенту как информация, а не как ваши указания. Он не может выдать новые разрешения ни себе, ни основному агенту.
Обмен сообщениями между агентами
Агенты могут общаться друг с другом через SendMessage, обращаясь по имени, handle или id сессии, и находить друг друга через ListAgents. Это работает между субагентами и между отдельными сессиями, запущенными на одном демоне (daemon). Сообщения видны в журнале сессии.
Модели для субагентов
Субагент может работать на другой модели, чем основной агент, даже от другого провайдера. Типичные варианты:
- Быстрая и недорогая модель для широкого поиска и сводок.
- Другая frontier-модель в роли ревьюера, чтобы второе семейство моделей проверяло работу первого.
- Та же модель с более высоким уровнем рассуждений для самой сложной подзадачи.