Home>Concepts>Agent

Agent

A specialized AI assistant configured for specific tasks and workflows.

What it is

An agent is an autonomous AI assistant that can reason, plan, and use tools to accomplish goals. It's not a chatbot — it's a configured entity with permissions, tools, a system prompt, and a model.

Agent = Configuration + Identity

Model Prompt Permissions Tools
↓
Read files Edit code Run commands Search code

What it is in real OpenCode terms

In OpenCode, an agent is a named configuration. Every interaction happens through an agent. Two categories:

Built-in Primary Agents

Build Default Full access — reads, writes, runs commands, invokes subagents
Plan Read-only Analysis only — can read files but cannot edit or run commands

Built-in Subagents

General Full tools Explore Read-only Scout Read-only

Switch primary agents with Tab. Invoke subagents with @name.

Why it exists

Without agents, you would have one generic AI assistant doing everything — coding, debugging, researching, planning — with the same permissions and the same prompt. This leads to:

  • Accidental file edits when you only wanted analysis
  • No specialization — the AI doesn't know it should act differently for planning vs. building
  • No way to delegate subtasks to parallel workers

Agents solve this by letting you configure who does the work, what they can do, and how they should approach it. A Plan agent won't accidentally overwrite your code. A Scout agent focuses only on external research. Each agent has a clear purpose.

Anatomy / main elements

Every agent configuration includes some or all of these fields:

Field Purpose
description Short text explaining what the agent does. Shown in agent selection.
model The LLM model the agent uses (e.g., anthropic/claude-sonnet-4). Falls back to the global config model if omitted.
prompt System prompt or instructions that define the agent's behavior and personality.
permissions Controls which actions the agent can take: read, edit, bash, task, etc.
mode Set to primary, subagent, or all. Determines how the agent is invoked.
temperature Controls randomness in responses. Lower = more deterministic.
steps Limits how many sequential steps the agent can take before pausing.

Where it lives

Agent configurations can live in two places:

Project-level (per-repo):
.opencode/agents/my-agent.md

User-level (global):
~/.config/opencode/agents/my-agent.md

They can also be defined inline in your opencode.json config file:

{
  "agent": {
    "my-agent": {
      "description": "A custom agent for refactoring",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4",
      "prompt": "You are a refactoring specialist.",
      "permissions": {
        "edit": true,
        "bash": false
      }
    }
  }
}

Or as a Markdown file with YAML frontmatter:

.opencode/agents/refactor.md 
---
name: refactor
description: A refactoring specialist
mode: primary
model: anthropic/claude-sonnet-4
---

You are a refactoring specialist. Your job is to improve code
quality without changing behavior. Focus on:
- Removing duplication
- Improving naming
- Simplifying control flow
- Applying SOLID principles

How to create one

  1. Decide if this should be a primary agent (you interact with it directly) or a subagent (other agents invoke it).
  2. Create a Markdown file in .opencode/agents/ named after your agent (e.g., reviewer.md).
  3. Add YAML frontmatter with at minimum name, description, and mode.
  4. Write the system prompt in the body of the Markdown file.
  5. Restart OpenCode or reload config. The agent appears in the agent selector (for primary agents) or becomes available to @ mention (for subagents).
Tip: Start by copying an existing built-in agent's behavior. Create a primary agent modeled on Build, then restrict its permissions or adjust its prompt.

Minimal example

Create a read-only reviewer agent that can only read files and suggest changes:

---
name: reviewer
description: Read-only code reviewer that suggests improvements
mode: primary
permissions:
  read: true
  edit: false
  bash: false
---

You are a code reviewer. You can read the codebase but never
modify it. For each file you examine, output:

1. Issues found (bugs, anti-patterns, security concerns)
2. Suggested improvements with specific code snippets
3. A severity rating: critical / warning / nit

Be concise. Prioritize real problems over style preferences.

Save this as .opencode/agents/reviewer.md. After reloading, press Tab to switch to the reviewer agent. It will be able to read your code but will refuse any edit or shell commands.

Related concepts

Subagent Skill

Common confusion

Agent vs. Model: An agent is not a model. The model is the LLM powering the agent (e.g., Claude, GPT). The agent is the full configuration — prompt, permissions, tools, and model combined. Two agents can use the same model but behave completely differently.
Primary vs. Subagent: A primary agent is what you interact with directly via the CLI. A subagent is what primary agents (or you, via @) delegate work to. You cannot switch to a subagent with Tab — subagents run in their own child sessions.
Agent vs. Skill: An agent is an autonomous entity with its own session and tools. A skill is a reusable instruction set that gets injected into whatever agent loads it. An agent uses skills; it is not a skill.