Русский
Документация
Агенты

Agents

Настройка и использование специализированных agents.

Agents — это специализированные AI-ассистенты, которые можно настроить для конкретных задач и рабочих процессов. Они позволяют создавать целенаправленные инструменты с пользовательскими промптами, моделями и доступом к инструментам.

Совет: Используйте agent plan для анализа кода и просмотра предложений без внесения изменений в код.

Вы можете переключаться между agents во время сессии или вызывать их с помощью упоминания @.

Типы

В OpenCode есть два типа agents: primary agents и subagents.

Primary agents

Primary agents — это основные ассистенты, с которыми вы взаимодействуете напрямую. Вы можете переключаться между ними с помощью клавиши Tab или настроенной комбинации switch_agent. Эти agents ведут вашу основную беседу. Доступ к инструментам настраивается через разрешения — например, Build имеет все инструменты включёнными, а Plan ограничен.

Совет: Вы можете использовать клавишу Tab для переключения между primary agents во время сессии.

OpenCode поставляется с двумя встроенными primary agents: Build и Plan. Рассмотрим их ниже.

Subagents

Subagents — это специализированные ассистенты, которых primary agents могут вызывать для конкретных задач. Вы также можете вызвать их вручную, упомянув через @ в своих сообщениях.

OpenCode поставляется с двумя встроенными subagents: General и Explore. Рассмотрим их ниже.

Встроенные

OpenCode поставляется с двумя встроенными primary agents и двумя встроенными subagents.

Использование build

Режим: primary

Build — это стандартный primary agent со всеми включёнными инструментами. Это стандартный agent для разработки, где вам нужен полный доступ к файловым операциям и системным командам.

Использование plan

Режим: primary

Ограниченный agent, предназначенный для планирования и анализа. Мы используем систему разрешений, чтобы дать вам больше контроля и предотвратить непреднамеренные изменения. По умолчанию все следующие параметры установлены в ask:

  • file edits: Все записи, патчи и редактирования
  • bash: Все команды bash

Этот agent полезен, когда вы хотите, чтобы LLM анализировал код, предлагал изменения или создавал планы без фактических модификаций вашей кодовой базы.

Использование general

Режим: subagent

Agent общего назначения для исследования сложных вопросов и выполнения многошаговых задач. Имеет полный доступ к инструментам (кроме todo), поэтому может вносить изменения в файлы при необходимости. Используйте для параллельного выполнения нескольких единиц работы.

Использование explore

Режим: subagent

Быстрый agent только для чтения для исследования кодовых баз. Не может изменять файлы. Используйте, когда нужно быстро найти файлы по шаблонам, искать ключевые слова в коде или отвечать на вопросы о кодовой базе.

Использование compaction

Режим: primary

Скрытый системный agent, который сжимает длинный контекст в меньшее резюме. Запускается автоматически при необходимости и не выбирается в интерфейсе.

Использование title

Режим: primary

Скрытый системный agent, который генерирует короткие заголовки сессий. Запускается автоматически и не выбирается в интерфейсе.

Использование summary

Режим: primary

Скрытый системный agent, который создаёт резюме сессий. Запускается автоматически и не выбирается в интерфейсе.

Использование

  • Для primary agents используйте клавишу Tab для переключения между ними во время сессии. Вы также можете использовать настроенную комбинацию switch_agent.

  • Subagents можно вызывать:

    • Автоматически primary agents для специализированных задач на основе их описаний.

    • Вручную, упомянув через @ subagent в вашем сообщении. Например:

      @general help me search for this function

  • Навигация между сессиями: Когда subagents создают свои собственные дочерние сессии, вы можете перемещаться между родительской сессией и всеми дочерними сессиями, используя:

    • <Leader>+Right (или настроенную комбинацию session_child_cycle) для перехода вперёд: родитель → дочерний1 → дочерний2 → … → родитель
    • <Leader>+Left (или настроенную комбинацию session_child_cycle_reverse) для перехода назад: родитель ← дочерний1 ← дочерний2 ← … ← родитель

    Это позволяет легко переключаться между основной беседой и специализированной работой subagent.

Настройка

Вы можете настроить встроенные agents или создать свои собственные через конфигурацию. Agents можно настроить двумя способами:

JSON

Настройте agents в вашем файле конфигурации opencode.json:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

Вы также можете определять agents с помощью markdown-файлов. Разместите их в:

  • Глобально: ~/.config/opencode/agents/
  • Для проекта: .opencode/agents/
~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
 
You are in code review mode. Focus on:
 
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations
 
Provide constructive feedback without making direct changes.

Имя markdown-файла становится именем agent. Например, review.md создаёт agent review.

Параметры

Рассмотрим эти параметры конфигурации подробнее.

Description

Используйте параметр description для краткого описания того, что делает agent и когда его использовать.

opencode.json
{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Это обязательный параметр конфигурации.

Temperature

Управляйте случайностью и креативностью ответов LLM с помощью настройки temperature.

Более низкие значения делают ответы более сфокусированными и детерминированными, а более высокие значения увеличивают креативность и вариативность.

opencode.json
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Значения temperature обычно варьируются от 0.0 до 1.0:

  • 0.0-0.2: Очень сфокусированные и детерминированные ответы, идеально для анализа кода и планирования
  • 0.3-0.5: Сбалансированные ответы с некоторой креативностью, хорошо для общих задач разработки
  • 0.6-1.0: Более креативные и разнообразные ответы, полезно для мозгового штурма и исследования
opencode.json
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Если temperature не указана, OpenCode использует значения по умолчанию для конкретной модели; обычно 0 для большинства моделей, 0.55 для моделей Qwen.

Max steps

Управляйте максимальным количеством агентных итераций, которые agent может выполнить, прежде чем будет вынужден отвечать только текстом. Это позволяет пользователям, желающим контролировать расходы, установить лимит на агентные действия.

Если это не установлено, agent будет продолжать итерации, пока модель не решит остановиться или пользователь не прервёт сессию.

opencode.json
{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

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

Внимание: Устаревшее поле maxSteps deprecated. Используйте steps вместо него.

Disable

Установите в true для отключения agent.

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Укажите пользовательский файл системного промпта для этого agent с помощью настройки prompt. Файл промпта должен содержать инструкции, специфичные для назначения agent.

opencode.json
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Этот путь относителен к расположению файла конфигурации. Поэтому это работает как для глобальной конфигурации OpenCode, так и для конфигурации конкретного проекта.

Model

Используйте настройку model для переопределения модели для этого agent. Полезно для использования разных моделей, оптимизированных для разных задач. Например, более быстрая модель для планирования, более мощная модель для реализации.

Совет: Если вы не укажете модель, primary agents используют глобально настроенную модель, а subagents будут использовать модель primary agent, который вызвал subagent.

opencode.json
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

ID модели в вашей конфигурации OpenCode использует формат provider/model-id. Например, если вы используете OpenCode Zen, вы бы использовали opencode/gpt-5.1-codex для GPT 5.1 Codex.

Tools

Управляйте тем, какие инструменты доступны в этом agent с помощью настройки tools. Вы можете включить или отключить конкретные инструменты, установив их в true или false.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Примечание: Конфигурация конкретного agent переопределяет глобальную конфигурацию.

Вы также можете использовать подстановочные знаки для управления несколькими инструментами одновременно. Например, чтобы отключить все инструменты от MCP-сервера:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

Узнайте больше об инструментах.

Permissions

Вы можете настроить разрешения для управления тем, какие действия может выполнять agent. В настоящее время разрешения для инструментов edit, bash и webfetch можно настроить на:

  • "ask" — Запрашивать одобрение перед запуском инструмента
  • "allow" — Разрешить все операции без одобрения
  • "deny" — Отключить инструмент
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Вы можете переопределить эти разрешения для каждого agent.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Вы также можете устанавливать разрешения в Markdown agents.

~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---
 
Only analyze code and suggest changes.

Вы можете устанавливать разрешения для конкретных команд bash.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

Это может принимать glob-шаблон.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

И вы также можете использовать подстановочный знак * для управления разрешениями для всех команд. Поскольку последнее совпадающее правило имеет приоритет, поместите подстановочный знак * первым, а конкретные правила после.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Узнайте больше о разрешениях.

Mode

Управляйте режимом agent с помощью настройки mode. Параметр mode используется для определения того, как agent может использоваться.

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

Параметр mode может быть установлен в primary, subagent или all. Если mode не указан, по умолчанию используется all.

Hidden

Скройте subagent из меню автодополнения @ с помощью hidden: true. Полезно для внутренних subagents, которые должны вызываться только программно другими agents через инструмент Task.

opencode.json
{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Это влияет только на видимость пользователя в меню автодополнения. Скрытые agents всё ещё могут быть вызваны моделью через инструмент Task, если разрешения позволяют.

Примечание: Применяется только к agents с mode: subagent.

Task permissions

Управляйте тем, какие subagents agent может вызывать через инструмент Task с помощью permission.task. Использует glob-шаблоны для гибкого сопоставления.

opencode.json
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Когда установлено в deny, subagent полностью удаляется из описания инструмента Task, поэтому модель не будет пытаться его вызвать.

Совет: Правила оцениваются по порядку, и последнее совпадающее правило побеждает. В примере выше orchestrator-planner соответствует как * (deny), так и orchestrator-* (allow), но поскольку orchestrator-* идёт после *, результат — allow.

Совет: Пользователи всегда могут вызвать любой subagent напрямую через меню автодополнения @, даже если разрешения task agent запретили бы это.

Color

Настройте визуальное оформление agent в интерфейсе с помощью параметра color. Это влияет на то, как agent отображается в интерфейсе.

Используйте допустимый hex-цвет (например, #FF5733) или цвет темы: primary, secondary, accent, success, warning, error, info.

opencode.json
{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

Управляйте разнообразием ответов с помощью параметра top_p. Альтернатива temperature для управления случайностью.

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Значения варьируются от 0.0 до 1.0. Более низкие значения более сфокусированы, более высокие значения более разнообразны.

Additional

Любые другие параметры, которые вы укажете в конфигурации agent, будут переданы напрямую провайдеру как параметры модели. Это позволяет использовать специфичные для провайдера функции и параметры.

Например, с моделями рассуждения OpenAI вы можете контролировать усилие рассуждения:

opencode.json
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Эти дополнительные параметры специфичны для модели и провайдера. Проверьте документацию вашего провайдера для доступных параметров.

Совет: Запустите opencode models, чтобы увидеть список доступных моделей.

Создание agents

Вы можете создать новые agents с помощью следующей команды:

opencode agent create

Эта интерактивная команда:

  • Спросит, где сохранить agent: глобально или для конкретного проекта.
  • Описание того, что должен делать agent.
  • Сгенерирует соответствующий системный промпт и идентификатор.
  • Позволит выбрать, к каким инструментам agent может получить доступ.
  • Наконец, создаст markdown-файл с конфигурацией agent.

Варианты использования

Вот некоторые распространённые варианты использования для разных agents.

  • Build agent: Полная разработка со всеми включёнными инструментами
  • Plan agent: Анализ и планирование без внесения изменений
  • Review agent: Ревью кода с доступом только для чтения плюс инструменты документации
  • Debug agent: Сфокусирован на расследовании с включёнными bash и инструментами чтения
  • Docs agent: Написание документации с файловыми операциями, но без системных команд

Примеры

Вот несколько примеров agents, которые могут быть вам полезны.

Совет: У вас есть agent, которым вы хотели бы поделиться? Отправьте PR (opens in a new tab).

Documentation agent

~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---
 
You are a technical writer. Create clear, comprehensive documentation.
 
Focus on:
 
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Security auditor

~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---
 
You are a security expert. Focus on identifying potential security issues.
 
Look for:
 
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues
ПравилаМодели