Dax
270 lines
9.5 KiB
Plaintext
270 lines
9.5 KiB
Plaintext
---
|
|
title: "Agents"
|
|
---
|
|
|
|
Agents combine a system prompt, model preference, tool permissions, and display
|
|
metadata into a reusable assistant profile. OpenCode includes agents for common
|
|
workflows, and you can override them or add your own in configuration or
|
|
Markdown files.
|
|
|
|
## Built-in agents
|
|
|
|
| Agent | Mode | Purpose |
|
|
| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **Build** (`build`) | `primary` | Default coding agent. Tools are allowed by default, sensitive environment-file reads ask for approval, and access outside the workspace asks for approval. |
|
|
| **Plan** (`plan`) | `primary` | Planning agent. File edits are denied except for OpenCode plan files. Shell commands are not generally denied. |
|
|
| **General** (`general`) | `subagent` | General-purpose research and multi-step work. It has broad tool access but cannot launch more subagents. |
|
|
| **Explore** (`explore`) | `subagent` | Read-only code and web exploration using `read`, `glob`, `grep`, `webfetch`, and `websearch`. |
|
|
|
|
OpenCode also has hidden `compaction`, `title`, and `summary` system agents.
|
|
They run internal maintenance tasks and are not available for direct use. There is no built-in
|
|
`scout` agent in V2.
|
|
|
|
You can override a built-in agent with an entry of the same ID. Set
|
|
`disabled: true` to remove one.
|
|
|
|
## Default agent
|
|
|
|
Set the primary agent used when a session has not selected one:
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"default_agent": "reviewer",
|
|
}
|
|
```
|
|
|
|
The configured agent must exist, must not have `mode: "subagent"`, and must not
|
|
be hidden. If it is unavailable, OpenCode falls back to `build`, then to the
|
|
first visible agent that can run as a primary agent. This selection does not
|
|
rewrite the agent already stored on an existing session.
|
|
|
|
## Modes
|
|
|
|
An agent's `mode` controls where it can run:
|
|
|
|
| Mode | Behavior |
|
|
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `primary` | Can be selected as the main agent for a session. It cannot be launched as a subagent. This is the default for a custom agent when `mode` is omitted. |
|
|
| `subagent` | Can run in a child session through the `subagent` tool, but cannot be selected as the main agent. |
|
|
| `all` | Can be used either way. |
|
|
|
|
Subagents run in child sessions with fresh context. A primary agent can invoke
|
|
one with the `subagent` tool, either in the foreground or in the background.
|
|
|
|
The parent agent's `subagent` permission controls which agents it may launch.
|
|
The child currently uses its own configured permissions, not a restricted copy
|
|
of the parent's permissions.
|
|
|
|
## Configure agents
|
|
|
|
### Markdown files
|
|
|
|
The recommended file locations are:
|
|
|
|
```text
|
|
~/.config/opencode/agents/<name>.md
|
|
.opencode/agents/<name>.md
|
|
```
|
|
|
|
OpenCode discovers project `.opencode` directories from the current directory
|
|
up to the project root. The path below `agents/` becomes the agent ID, so
|
|
`.opencode/agents/team/reviewer.md` defines `team/reviewer`.
|
|
|
|
Frontmatter uses the same fields as an entry under `agents`. The Markdown body
|
|
becomes `system`:
|
|
|
|
```md title=".opencode/agents/reviewer.md"
|
|
---
|
|
description: Reviews changes without modifying files
|
|
mode: subagent
|
|
model: anthropic/claude-sonnet-4-5#high
|
|
color: "#ff6b6b"
|
|
steps: 8
|
|
permissions:
|
|
- action: edit
|
|
resource: "*"
|
|
effect: deny
|
|
- action: shell
|
|
resource: "*"
|
|
effect: deny
|
|
---
|
|
|
|
Review for correctness, security, regressions, and missing tests.
|
|
List findings in severity order with file and line references.
|
|
```
|
|
|
|
### JSON or JSONC
|
|
|
|
Use the `agents` field in any [OpenCode configuration file](/config):
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"default_agent": "reviewer",
|
|
"agents": {
|
|
"reviewer": {
|
|
"description": "Reviews changes for correctness, security, and missing tests",
|
|
"mode": "all",
|
|
"model": "anthropic/claude-sonnet-4-5#high",
|
|
"system": "Review the current changes. Report findings before any summary.",
|
|
"color": "#ff6b6b",
|
|
"steps": 8,
|
|
"permissions": [
|
|
{ "action": "edit", "resource": "*", "effect": "deny" },
|
|
{ "action": "shell", "resource": "*", "effect": "deny" },
|
|
],
|
|
},
|
|
"build": {
|
|
"permissions": [{ "action": "shell", "resource": "git push *", "effect": "ask" }],
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
Agent definitions merge in configuration order. Later scalar fields replace
|
|
earlier values, request maps merge by key, and permission rules are appended.
|
|
Global `permissions` are applied to every agent before its agent-specific rules,
|
|
so a later agent rule can refine a global rule.
|
|
|
|
## Options
|
|
|
|
### `description`
|
|
|
|
Explains the agent's purpose. It is optional, but strongly recommended for
|
|
subagents because OpenCode includes it in the subagent catalog shown to the
|
|
model.
|
|
|
|
### `mode`
|
|
|
|
Accepts `primary`, `subagent`, or `all`. The default is `all`.
|
|
|
|
### `model`
|
|
|
|
Selects a model using `provider/model` with an optional `#variant`:
|
|
|
|
```jsonc
|
|
{
|
|
"agents": {
|
|
"reviewer": {
|
|
"model": "anthropic/claude-sonnet-4-5#high",
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
The equivalent expanded form is:
|
|
|
|
```jsonc
|
|
{
|
|
"agents": {
|
|
"reviewer": {
|
|
"model": {
|
|
"providerID": "anthropic",
|
|
"model": "claude-sonnet-4-5",
|
|
"variant": "high",
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
This is the preferred model when the agent is activated. A child session uses
|
|
its subagent's configured model, or inherits the parent session's model when
|
|
none is configured. The session's selected model is stored separately;
|
|
creating or switching a primary session with only an agent ID does not itself
|
|
change that session model.
|
|
|
|
### `system`
|
|
|
|
Sets the agent's system prompt. A non-empty value replaces OpenCode's
|
|
provider-specific base prompt for that agent. Project instructions, skills,
|
|
references, and other instruction sources are still added separately.
|
|
|
|
For a Markdown agent, use the document body instead of a `system` frontmatter
|
|
field.
|
|
|
|
### `permissions`
|
|
|
|
Permissions are an ordered array of rules:
|
|
|
|
```jsonc
|
|
{
|
|
"agents": {
|
|
"orchestrator": {
|
|
"permissions": [
|
|
{ "action": "subagent", "resource": "*", "effect": "deny" },
|
|
{ "action": "subagent", "resource": "explore", "effect": "allow" },
|
|
{ "action": "shell", "resource": "git *", "effect": "ask" },
|
|
],
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
Each rule has:
|
|
|
|
| Field | Meaning |
|
|
| ---------- | ---------------------------------------------------------------------------------------------- |
|
|
| `action` | Tool or permission action, with `*` wildcards supported. |
|
|
| `resource` | The path, command, agent ID, or other resource matched by the action. Wildcards are supported. |
|
|
| `effect` | `allow`, `ask`, or `deny`. |
|
|
|
|
The last matching rule wins. Important V2 action names include `shell` for
|
|
shell commands, `edit` for all edit/write/patch tools, and `subagent` for child
|
|
agents. Other tools generally use their tool name, such as `read`, `glob`,
|
|
`grep`, `webfetch`, `websearch`, and `skill`.
|
|
|
|
<Callout type="tip">
|
|
Put broad wildcard rules first and exceptions afterward. For example, deny all subagents first, then allow `explore`.
|
|
</Callout>
|
|
|
|
`~` and `$HOME` are expanded in filesystem resources for `read`, `edit`, and
|
|
`external_directory`. Shell resources are raw command text and are not
|
|
expanded.
|
|
|
|
### `steps`
|
|
|
|
Sets a positive maximum number of model steps. On the final allowed step,
|
|
OpenCode removes tools and asks the model to summarize its work in text. New
|
|
user input resets the allowance.
|
|
|
|
### `hidden`
|
|
|
|
When `true`, removes the agent from normal agent listings, interactive
|
|
discovery, and the subagent catalog advertised to models. It is a visibility
|
|
setting, not a security boundary.
|
|
|
|
### `color`
|
|
|
|
Sets the agent's UI color. Use a six-digit hex color such as `#ff6b6b`.
|
|
|
|
### `disabled`
|
|
|
|
When `true`, removes the agent definition at that point in configuration
|
|
loading. This works for built-in and custom agents.
|
|
|
|
### `request`
|
|
|
|
The V2 schema accepts per-agent request `headers` and JSON `body` overlays:
|
|
|
|
```jsonc
|
|
{
|
|
"agents": {
|
|
"reviewer": {
|
|
"request": {
|
|
"headers": { "x-agent": "reviewer" },
|
|
"body": { "temperature": 0.1 },
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
<Callout type="warning">
|
|
The current V2 session runner preserves these overlays on the agent definition but does not yet apply them to model
|
|
requests. Configure effective request settings on the provider, model, or model variant instead. Do not use legacy
|
|
top-level agent fields such as `temperature`, `top_p`, `prompt`, `permission`, `tools`, `disable`, or `maxSteps` in
|
|
new V2 configuration.
|
|
</Callout>
|