Создайте 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.