05 - Агенты
Создайте Markdown-файл для добавления повторно используемого агента. Этот пример добавляет только для чтения рецензента, которого основной агент может запускать для проверки кода:
---
description: Reviews changes for correctness and regressions
mode: subagent
model: anthropic/claude-sonnet-5-5#high
permissions:
- action: edit
resource: "*"
effect: deny
- action: shell
resource: "*"
effect: deny
---
Review the current changes. List findings in severity order with file and line references.
Попросите ваш основной агент использовать его:
Use the reviewer subagent to review my current changes.
Агент объединяет системный запрос, предпочтение модели, разрешения и отображение деталей в именованный профиль помощника.
Расположения
Сохраняйте Markdown-агентов глобально для всех проектов или внутри проекта:
~/.config/opencode/agents/<name>.md .opencode/agents/<name>.md
OpenCode обнаруживает проектные директории .opencode от текущей директории до корня проекта. Вложенный путь становится частью ID агента:
.opencode/agents/team/reviewer.md → team/reviewer
Форматы
Markdown
Frontmatter принимает те же поля, что и запись конфигурации agents. Тело Markdown становится системным запросом агента system:
--- description: Explains code without changing it mode: subagent --- Explain the relevant code with short examples. Do not edit files.
Поля frontmatter V1 устарели. См. Файлы агентов для того, как читаются файлы, которые всё ещё их используют.
JSONC
Определите агентов под agents в любом файле конфигурации OpenCode:
{
"$schema": "https://opencode.ai/config.json",
"agents": {
"reviewer": {
"description": "Reviews current changes",
"mode": "subagent",
"system": "Report findings in severity order.",
"permissions": [
{ "action": "edit", "resource": "*", "effect": "deny" },
],
},
},
}
Выбор
Установите основной агент, используемый, когда сессия не выбрала его:
{
"$schema": "https://opencode.ai/config.json",
"default_agent": "writer",
"agents": {
"writer": { "mode": "primary" },
},
}
Выбранный по умолчанию должен существовать, быть видимым и поддерживать использование primary. В противном случае OpenCode использует build, затем первого видимого агента с возможностью primary. Изменение этой настройки не заменяет агента, сохранённого в существующей сессии.
Режимы
Установите mode в зависимости от того, где должен работать агент:
{
"agents": {
"reviewer": { "mode": "subagent" },
},
}
|
Режим |
Поведение |
|---|---|
|
primary |
Запускается как основной агент для сессии. Это значение по умолчанию для нового пользовательского агента. |
|
subagent |
Запускается только в дочерней сессии через инструмент subagent. |
|
all |
Запускается либо как основной агент, либо как подагент. |
Подагенты запускаются со свежим контекстом в foreground или фоновых дочерних сессиях. Разрешения subagent родительского агента контролируют, каких агентов он может запускать; дочерний использует свои собственные настроенные разрешения.
{
"agents": {
"orchestrator": {
"permissions": [
{ "action": "subagent", "resource": "*", "effect": "deny" },
{ "action": "subagent", "resource": "reviewer", "effect": "allow" },
],
},
},
}
Встроенные
OpenCode включает этих видимых агентов:
|
Агент |
Режим |
Назначение |
|---|---|---|
|
Build (build) |
primary |
Агент программирования по умолчанию. Инструменты и доступ вне рабочей области разрешены по умолчанию; чтение конфиденциальных файлов окружения запрашивает одобрение. |
|
Plan (plan) |
primary |
Исследует и планирует без редактирования обычных проектных файлов. Может писать файлам планов OpenCode по запросу, а команды оболочки остаются под контролем разрешений. |
|
General (general) |
subagent |
Обрабатывает исследования и многошаговую работу с широким доступом к инструментам, но не может запускать больше подагентов. |
|
Explore (explore) |
subagent |
Ищет и читает код или веб-источники без редактирования файлов. |
Переопределите встроенный, используя тот же ID:
{
"agents": {
"build": {
"permissions": [
{ "action": "shell", "resource": "git push *", "effect": "ask" },
],
},
},
}
Скрытые агенты compaction, title и summary выполняют обслуживание и не могут быть выбраны напрямую. В V2 нет встроенного агента scout.
Объединение
Определения агентов объединяются в порядке конфигурации. Поздние скалярные значения заменяют ранние, карты запросов объединяются по ключу, а правила разрешений добавляются:
{
"permissions": [
{ "action": "shell", "resource": "*", "effect": "ask" },
],
"agents": {
"build": {
"permissions": [
{ "action": "shell", "resource": "git status", "effect": "allow" },
],
},
},
}
Глобальные permissions применяются перед правилами, специфичными для агента, поэтому поздние правила агента могут их уточнять.
Параметры
Описание
description объясняет назначение агента. Добавьте его к подагентам, потому что OpenCode показывает его модели, выбирающей, какого агента запустить:
description: Reviews database migrations for safety
Режим
mode принимает primary, subagent или all. При отсутствии для нового пользовательского агента по умолчанию primary:
mode: all
Модель
model использует провайдер/модель с необязательным #variant:
model: anthropic/claude-sonnet-5-5#high
JSON-конфигурация также принимает расширенную форму:
{
"agents": {
"reviewer": {
"model": {
"providerID": "anthropic",
"model": "claude-sonnet-5-5",
"variant": "high",
},
},
},
}
- Подагент использует свою настроенную модель или наследует модель родительской сессии, когда ничего не настроено.
- Сессия хранит свою выбранную модель отдельно. Выбор основного агента по ID не изменяет эту модель.
Система
system устанавливает системный запрос агента. Непустое значение заменяет базовый запрос провайдера для этого агента:
{
"agents": {
"reviewer": { "system": "Review only. Do not modify files." },
},
}
Проектные инструкции, навыки, ссылки и другие источники инструкций всё ещё добавляются. В Markdown-агенте поместите этот текст в тело документа вместо поля frontmatter system.
Разрешения
permissions — упорядоченный список правил сопоставления:
{
"agents": {
"reviewer": {
"permissions": [
{ "action": "*", "resource": "*", "effect": "deny" },
{ "action": "read", "resource": "src/**", "effect": "allow" },
],
},
},
}
|
Поле |
Значение |
|---|---|
|
action |
Инструмент или действие разрешения. Поддерживаются подстановочные знаки. |
|
resource |
Путь, команда, ID агента или другое значение, сопоставляемое действием. Поддерживаются подстановочные знаки. |
|
effect |
allow, ask или deny. |
Последнее совпадающее правило побеждает, поэтому размещайте широкие правила перед исключениями. Общие действия включают:
|
Действие |
Охватывает |
|---|---|
|
shell |
Команды оболочки |
|
edit |
Инструменты редактирования, записи и патча |
|
subagent |
Дочерние агенты |
|
read, glob, grep |
Локальные инструменты обнаружения |
|
webfetch, websearch |
Веб-инструменты |
|
skill |
Загрузка навыков |
Для ресурсов read, edit и external_directory OpenCode расширяет ~ и $HOME:
{ "action": "read", "resource": "~/notes/**", "effect": "allow" }
Ресурсы оболочки остаются сырым текстом команды и не расширяют эти значения.
Шаги
steps устанавливает положительное максимальное количество шагов модели:
steps: 8
На последнем шаге OpenCode удаляет инструменты, и просит модель обобщить текст. Новый ввод пользователя сбрасывает разрешение.
Скрытый
hidden удаляет агента из обычных списков, интерактивного обнаружения и каталога подагентов:
hidden: true
Это контролирует видимость, а не безопасность. Используйте разрешения для ограничения поведения.
Цвет
color устанавливает цвет UI агента с помощью шестизначного шестнадцатеричного значения:
color: "#ff6b6b"
Отключённый
disabled удаляет встроенный или пользовательский агент в точке загрузки конфигурации:
{
"agents": {
"plan": { "disabled": true },
},
}
Запрос
request принимает наложения заголовков и тела JSON для каждого агента:
{
"agents": {
"reviewer": {
"request": {
"headers": { "x-agent": "reviewer" },
"body": { "temperature": 0.1 },
},
},
},
}
Не используйте устаревшие поля верхнего уровня, такие как temperature, top_p, prompt, permission, tools, disable или maxSteps в новой конфигурации агента V2.