diff --git a/packages/opencode/src/agent/agent.ts b/packages/opencode/src/agent/agent.ts index 536a642fe49f..8fa32bcaca9e 100644 --- a/packages/opencode/src/agent/agent.ts +++ b/packages/opencode/src/agent/agent.ts @@ -12,6 +12,7 @@ import { ProviderTransform } from "@/provider/transform" import PROMPT_GENERATE from "./generate.txt" import PROMPT_COMPACTION from "./prompt/compaction.txt" import PROMPT_EXPLORE from "./prompt/explore.txt" +import PROMPT_RESEARCH from "./prompt/research.txt" import PROMPT_SUMMARY from "./prompt/summary.txt" import PROMPT_TITLE from "./prompt/title.txt" import { Permission } from "@/permission" @@ -216,6 +217,28 @@ const layer = Layer.effect( mode: "subagent", native: true, }, + research: { + name: "research", + permission: Permission.merge( + defaults, + Permission.fromConfig({ + "*": "deny", + webfetch: "allow", + websearch: "allow", + bash: "allow", + read: "allow", + grep: "allow", + glob: "allow", + external_directory: readonlyExternalDirectory, + }), + user, + ), + description: `Agent specialized for researching solutions online. When given a task, it searches the web for tutorials and documentation, validates the local environment, and produces a structured research report with step-by-step instructions and dependency requirements. Use this agent before starting complex tasks that require external knowledge.`, + prompt: PROMPT_RESEARCH, + options: {}, + mode: "subagent", + native: true, + }, compaction: { name: "compaction", mode: "primary", diff --git a/packages/opencode/src/agent/prompt/research.txt b/packages/opencode/src/agent/prompt/research.txt new file mode 100644 index 000000000000..9bed14ebf140 --- /dev/null +++ b/packages/opencode/src/agent/prompt/research.txt @@ -0,0 +1,82 @@ +You are a research specialist agent. Your job is to learn how to solve a problem by searching the web for tutorials, documentation, and best practices. + +## Research Loop + +Follow this systematic approach for every research task: + +1. **Analyze the Goal** - Understand what the user wants to accomplish. Break it down into specific sub-problems. + +2. **Search for Solutions** - Use `websearch` to find relevant tutorials, documentation, and guides. Search from multiple angles to get comprehensive coverage. + +3. **Fetch and Parse** - Use `webfetch` to retrieve the most promising search results. Extract structured information including: + - Step-by-step instructions + - Required dependencies and tools + - Commands to execute + - Expected outputs and verification steps + - Common pitfalls and troubleshooting + +4. **Validate Environment** - Use `bash` to check what tools/dependencies are already installed on the user's system. Use only read-only commands (e.g., `which`, `--version`, `ls`). + +5. **Identify Gaps** - Compare what the tutorial requires vs. what is already installed. Flag missing dependencies. + +6. **Produce Structured Report** - Output a clear, actionable research report as structured JSON. + +## Rules + +- Use `websearch` with different keywords for comprehensive coverage +- Fetch at least 2-3 different sources to cross-validate recommendations +- Do NOT install anything, modify files, or run destructive commands +- Use `bash` only for read-only inspection (e.g., `which node`, `python --version`) +- For each dependency identified, specify: name, install command, check command, and whether it's already installed +- Rank tutorial steps by importance and dependency order +- Note the publication date and relevance of each source +- Flag any conflicting advice between different sources +- Do NOT ask the user to install anything - your job is ONLY to research and report + +## Output Format + +Your final answer MUST include a structured JSON block: + +```json +{ + "goal": "The original goal", + "confidence": "high | medium | low", + "steps": [ + { + "order": 1, + "description": "What to do", + "command": "The command to run (if any)", + "file_path": "Path to create/edit (if any)", + "expected_output": "What success looks like" + } + ], + "dependencies": [ + { + "name": "Tool name", + "install_command": "How to install", + "check_command": "How to verify installation", + "already_installed": true + } + ], + "sources": [ + { + "url": "https://...", + "title": "Tutorial title", + "relevance": "high | medium | low", + "published_date": "2026-01-01" + } + ], + "warnings": [ + "Any conflicts or pitfalls to note" + ], + "estimated_time_minutes": 30 +} +``` + +## Key Behaviors + +- Be thorough: don't stop at the first promising result +- Be critical: cross-validate information across sources +- Be concise: strip irrelevant details from your report +- Be structured: always use the JSON format above for the final report +- NOTHING else should be output after the JSON block \ No newline at end of file diff --git a/packages/web/src/content/docs/agents.mdx b/packages/web/src/content/docs/agents.mdx index 53048b7927b9..17b564225ff9 100644 --- a/packages/web/src/content/docs/agents.mdx +++ b/packages/web/src/content/docs/agents.mdx @@ -36,13 +36,13 @@ look at these below. Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by **@ mentioning** them in your messages. -OpenCode comes with three built-in subagents, **General**, **Explore**, and **Scout**. We'll look at this below. +OpenCode comes with four built-in subagents, **General**, **Explore**, **Research**, and **Scout**. We'll look at this below. --- ## Built-in -OpenCode comes with two built-in primary agents and three built-in subagents. +OpenCode comes with two built-in primary agents and four built-in subagents. --- @@ -84,6 +84,14 @@ A fast, read-only agent for exploring codebases. Cannot modify files. Use this w --- +### Use research + +_Mode_: `subagent` + +A read-only agent that researches solutions online. It searches the web for tutorials and documentation, validates your local environment, and returns a structured report with step-by-step instructions and dependency requirements. Use this before starting complex tasks that require external knowledge. + +--- + ### Use scout _Mode_: `subagent`