Агент-исследователь: что это и как создать его в OpenCode

Что такое агент-исследователь

Агент-исследователь — это субагент только на чтение, чья единственная задача — собрать факты и вернуть их отчётом со ссылками на источники. Он читает код и документы, ищет в вебе, сравнивает источники и останавливается. Он не правит файлы, не запускает сборки и ничего не решает. Родительская сессия задаёт один вопрос, продолжает работать, пока ребёнок трудится, и получает компактный ответ, где каждое утверждение снабжено источником: ссылкой file:line или URL.

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

Когда он нужен

К исследователю стоит идти в четырёх случаях:

Когда ответы должны приходить из одного фиксированного корпуса, а не из странствий по источникам, используйте RAG: исследователь бродит, RAG отвечает из одного индекса. Разделение моделей следует обычной тройке: быстрые справки — на бесплатной модели OpenCode, ежедневные исследования — на Luna, сложные вопросы с несколькими переходами — на Opus.

Создать файл агента

Проектные агенты лежат в .opencode/agents/; вложенный путь становится id. Минимальное место в демо-проекте из Скелета реального проекта:

my-app/ ├── opencode.jsonc ├── .opencode/agents/ │ ├── researcher.md │ └── team/orchestrator.md ├── .opencode/commands/ │ └── research.md └── .opencode/skills/

Полный файл, frontmatter плюс тело системного промпта:

--- description: Gathers facts from code and docs, returns a sourced report mode: subagent model: opencode/gpt-6-luna steps: 10 permissions: - action: edit resource: "*" effect: deny - action: shell resource: "*" effect: deny - action: webfetch resource: "*" effect: allow - action: websearch resource: "*" effect: allow --- Research the question with tools, never from memory. Prefer repo sources first, then official docs, then the open web. End every claim with a source: file:line or URL. If two sources disagree, show both and say which is newer. Answer in three sections: Findings, Gaps, Next steps. Stop when the budget is spent or the question is answered.

Заметки по полям:

Права для исследования

Основные инструменты чтения — read, glob, grep — остаются доступными, потому что их ничто не запрещает; всё, что меняет мир, запрещено явно. Правила упорядочены, и побеждает последнее совпадение:

Системный промпт, который работает

Четыре правила выдерживают встречу с настоящими задачами: ссылка в каждом утверждении, репозиторий раньше веба, расхождение источников показывают, а не сглаживают, и фиксированный ответ из трёх разделов. Разделы значат больше, чем кажется: Findings заставляет сжать, Gaps даёт родителю повод доверять молчанию, Next steps превращает отчёт в следующий промпт, а не в тупик. Один вопрос за запуск: исследователь, которого попросили о трёх вещах, вернёт три полуотчёта.

Как его запускать

Попросите родителя обычными словами:

Use the researcher subagent to map how retries are configured in this repo and in the official docs

Родитель остаётся рабочим, пока ребёнок трудится, а отчёт приходит в родительскую сессию. Для повторяемой точки входа закрепите его в файле команды .opencode/commands/research.md:

--- description: Research one question with the read-only researcher agent: researcher model: opencode/gpt-6-luna subagent: true --- Research: $ARGUMENTS Return Findings, Gaps, Next steps with a source on every claim.

Запускайте как /research how webhooks are signed in the billing service. Модель команды важнее модели агента, а та важнее модели сессии, поэтому явное указание всегда побеждает.

Формат отчёта

Зафиксируйте скелет, и отчёты станут сравнимы между запусками и моделями:

Findings - Retries live in src/http/client.py:88 (backoff, 5 attempts). - The docs pin the same default: https://example.com/api#retries Gaps - Jitter policy is undocumented; client.py:102 shows a constant. Next steps - Ask the analyst to measure the real retry rate from prod logs.

Внешние URL остаются настоящими ссылками с rel="nofollow", когда отчёт вставляют в статью или в задачу. Отчёт без раздела Gaps — красный флаг: исследователь либо остановился рано, либо выдумывает уверенность.

Замеры

Пять фиксированных вопросов с проверяемым результатом, прогоняемых при каждом изменении промпта или модели:

Последний случай — самый важный: агент, который признаёт пустой результат, ценнее того, кто заполняет молчание правдоподобной ссылкой.

Ограничения и режимы отказа

Автор статьи: Клавдия Кондакова