File size: 23,695 Bytes

0dbc9de

---
title: エージェント
description: 特殊なエージェントを構成して使用します。
---

エージェントは、特定のタスクやワークフロー向けに構成できる特殊な AI アシスタントです。これらを使用すると、カスタムプロンプト、モデル、ツールアクセスを備えた焦点を絞ったツールを作成できます。

:::tip
Plan エージェントを使用すると、コードを変更せずにコードを分析し、提案を確認できます。
:::

セッション中にエージェントを切り替えたり、`@` メンションでエージェントを呼び出したりできます。

---

## 種類

OpenCode には 2 種類のエージェントがあります。プライマリエージェントとサブエージェント。

---

### プライマリエージェント

プライマリエージェントは、直接対話する主要なアシスタントです。 **Tab** キー、または設定した `switch_agent` キーバインドを使用して、それらを切り替えることができます。これらのエージェントが主な会話を処理します。ツールへのアクセスは権限によって構成されます。たとえば、Build ではすべてのツールが有効になっていますが、Plan は制限されています。

:::tip
**Tab** キーを使用して、セッション中にプライマリエージェントを切り替えることができます。
:::

OpenCode には、**Build** と **Plan** という 2 つの組み込みプライマリエージェントが付属しています。これらについて以下で説明します。

---

### サブエージェント

サブエージェントは、プライマリエージェントが特定のタスクのために呼び出すことができる特殊なアシスタントです。メッセージ内で **@ メンション**することで、手動で呼び出すこともできます。

OpenCode には、**General**、**Explore**、**Scout** という 3 つの組み込みサブエージェントが付属しています。これについては以下で見ていきます。

---

## 組み込み

OpenCode には、2 つの組み込みプライマリエージェントと 3 つの組み込みサブエージェントが付属しています。

---

### Build

_モード_: `primary`

Build は、すべてのツールが有効になっている **デフォルト** プライマリエージェントです。これは、ファイル操作やシステムコマンドへの完全なアクセスが必要な開発作業用の標準エージェントです。

---

### Plan

_モード_: `primary`

計画と分析のために設計された制限付きエージェント。より詳細な制御を提供し、意図しない変更を防ぐために、許可システムを使用しています。
デフォルトでは、次のすべてが `ask` に設定されます。

- `file edits`: すべての書き込み、パッチ、および編集
- `bash`: すべての bash コマンド

このエージェントは、コードベースに実際の変更を加えずに LLM にコードの分析、変更の提案、または計画の作成を行わせたい場合に役立ちます。

---

### General

_モード_: `subagent`

複雑な質問を調査し、複数ステップのタスクを実行するための汎用エージェント。完全なツールアクセス権 (todo を除く) があるため、必要に応じてファイルを変更できます。これを使用して、複数の作業単位を並行して実行します。

---

### Explore

_モード_: `subagent`

コードベースを探索するための高速な読み取り専用エージェント。ファイルを変更できません。これは、パターンでファイルをすばやく検索したり、コードでキーワードを検索したり、コードベースに関する質問に答えたりする必要がある場合に使用します。

---

### Scout

_モード_: `subagent`

外部ドキュメントや依存関係の調査を行うための読み取り専用エージェントです。依存関係のリポジトリを OpenCode の管理キャッシュにクローンしたいとき、ライブラリのソースコードを調べたいとき、あるいはワークスペースを変更せずにローカルコードを upstream の実装と突き合わせたいときに使用します。

---

### Compact

_モード_: `primary`

長いコンテキストを小さな要約に圧縮する隠しシステムエージェント。これは必要に応じて自動的に実行され、UI では選択できません。

---

### Title

_モード_: `primary`

短いセッションタイトルを生成する非表示のシステムエージェント。これは自動的に実行され、UI では選択できません。

---

### Summary

_モード_: `primary`

セッション概要を作成する非表示のシステムエージェント。これは自動的に実行され、UI では選択できません。

---

## 使用法

1. プライマリエージェントの場合は、セッション中に **Tab** キーを使用してエージェントを切り替えます。設定した `switch_agent` キーバインドを使用することもできます。

2. サブエージェントは次のように呼び出すことができます。
   - プライマリエージェントによって、説明に基づいて特殊なタスクを **自動的に** 実行されます。
   - メッセージ内でサブエージェントを **@ メンション**することで手動で実行できます。例えば。

     ```txt frame="none"
     @general help me search for this function
     ```

3. **セッション間のナビゲーション**: サブエージェントが独自の子セッションを作成する場合、以下を使用して親セッションとすべての子セッションの間を移動できます。
   - **\<Leader>+Right** (または設定した `session_child_cycle` キーバインド) で、親 → 子 1 → 子 2 → ... → 親と順に循環します。
   - **\<Leader>+Left** (または設定した `session_child_cycle_reverse` キーバインド) で、親 ← 子 1 ← 子 2 ← ... ← 親を逆方向に循環します。

これにより、メインの会話と専門的なサブエージェントの作業をシームレスに切り替えることができます。

---

## 設定

組み込みエージェントをカスタマイズしたり、構成を通じて独自のエージェントを作成したりできます。エージェントは次の 2 つの方法で構成できます。

---

### JSON

`opencode.json` 設定ファイルでエージェントを構成します。

```json title="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

Markdown ファイルを使用してエージェントを定義することもできます。それらを次の場所に置きます。

- グローバル: `~/.config/opencode/agents/`
- プロジェクトごと: `.opencode/agents/`

```markdown title="~/.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 ファイル名がエージェント名になります。たとえば、`review.md` は `review` エージェントを作成します。

---

## オプション

これらの設定オプションを詳しく見てみましょう。

---

### 説明

`description` オプションを使用して、エージェントの機能とそれをいつ使用するかについての簡単な説明を提供します。

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

これは**必須**の設定オプションです。

---

### 温度

`temperature` 設定を使用して、LLM の応答のランダム性と創造性を制御します。

値が低いほど、応答はより集中的かつ決定的になりますが、値が高いほど、創造性と変動性が高まります。

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

通常、温度値の範囲は 0.0 ～ 1.0 です。

- **0.0-0.2**: 非常に焦点が絞られた決定的な応答。コード分析と計画に最適です。
- **0.3-0.5**: 創造性を備えたバランスの取れた応答。一般的な開発タスクに適しています。
- **0.6-1.0**: より創造的で多様な応答。ブレーンストーミングや探索に役立ちます。

```json title="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}"
    }
  }
}
```

温度が指定されていない場合、OpenCode はモデル固有のデフォルトを使用します。通常、ほとんどのモデルでは 0、Qwen モデルでは 0.55 です。

---

### ステップ数

エージェントが強制的にテキストのみで応答するまでに実行できるエージェントの反復の最大数を制御します。これにより、コストを管理したいユーザーは、エージェントのアクションに制限を設定できます。

これが設定されていない場合、エージェントは、モデルが停止を選択するか、ユーザーがセッションを中断するまで反復を続けます。

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

制限に達すると、エージェントは、作業の概要と推奨される残りのタスクを応答するように指示する特別なシステムプロンプトを受け取ります。

:::caution
従来の `maxSteps` フィールドは非推奨になりました。代わりに `steps` を使用してください。
:::

---

### 無効化

エージェントを無効にするには、`true` に設定します。

```json title="opencode.json"
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}
```

---

### プロンプト

`prompt` 設定を使用して、このエージェントのカスタムシステムプロンプトファイルを指定します。プロンプトファイルには、エージェントの目的に固有の指示が含まれている必要があります。

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

このパスは、設定ファイルが配置されている場所に対する相対パスです。したがって、これはグローバルな OpenCode 設定とプロジェクト固有の設定の両方で機能します。

---

### モデル

`model` 設定を使用して、このエージェントのモデルをオーバーライドします。さまざまなタスクに最適化されたさまざまなモデルを使用する場合に役立ちます。たとえば、計画にはより高速なモデルを、実装にはより有能なモデルを使用します。

:::tip
モデルを指定しない場合、プライマリエージェントは [グローバルに設定されたモデル](/docs/config#models) を使用し、サブエージェントはサブエージェントを呼び出したプライマリエージェントのモデルを使用します。
:::

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

OpenCode 設定内のモデル ID は、`provider/model-id` という形式を使用します。たとえば、[OpenCode Zen](/docs/zen) を使用している場合、GPT 5.1 Codex には `opencode/gpt-5.1-codex` を使用します。

---

### ツール

`tools` 設定を使用して、このエージェントで使用できるツールを制御します。特定のツールを `true` または `false` に設定することで、有効または無効にすることができます。

```json title="opencode.json" {3-6,9-12}
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}
```

:::note
エージェント固有の設定はグローバル設定をオーバーライドします。
:::
MCP サーバーからすべてのツールを無効にするには、次のようにします。

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

[ツール](/docs/tools) について詳しくはこちらをご覧ください。

---

### 権限

権限を設定して、エージェントが実行できるアクションを管理できます。現在、`edit`、`bash`、および `webfetch` ツールの権限は次のように構成できます。

- `"ask"` — ツールを実行する前に承認を求めるプロンプトを表示する
- `"allow"` — 承認なしですべての操作を許可する
- `"deny"` — ツールを無効にする

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}
```

これらの権限はエージェントごとにオーバーライドできます。

```json title="opencode.json" {3-5,8-10}
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}
```

Markdown エージェントで権限を設定することもできます。

```markdown title="~/.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 コマンドに対するアクセス許可を設定できます。

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

これにはグロブパターンを使用できます。

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

また、`*` ワイルドカードを使用して、すべてのコマンドの権限を管理することもできます。
最後に一致したルールが優先されるため、`*` ワイルドカードを最初に置き、特定のルールを後に置きます。

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

[権限](/docs/permissions)について詳しくはこちらをご覧ください。

---

### モード

`mode` 設定を使用してエージェントのモードを制御します。 `mode` オプションは、エージェントの使用方法を決定するために使用されます。

```json title="opencode.json"
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}
```

`mode` オプションは、`primary`、`subagent`、または `all` に設定できます。 `mode` が指定されていない場合、デフォルトは `all` になります。

---

### 非表示

`@` を使用して、`hidden: true` オートコンプリートメニューからサブエージェントを非表示にします。他のエージェントによってタスクツールを介してプログラム的にのみ呼び出す必要がある内部サブエージェントに役立ちます。

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

これは、オートコンプリートメニューでのユーザーの表示にのみ影響します。権限が許可されていれば、非表示のエージェントをタスクツール経由でモデルから呼び出すことができます。

:::note
`mode: subagent` エージェントにのみ適用されます。
:::

---

### タスクの権限

`permission.task` を使用して、エージェントがタスクツール経由でどのサブエージェントを呼び出すことができるかを制御します。柔軟なマッチングのためにグロブパターンを使用します。

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

`deny` に設定すると、サブエージェントはタスクツールの説明から完全に削除されるため、モデルはそれを呼び出そうとしません。

:::tip
ルールは順番に評価され、**最後に一致したルールが優先されます**。上記の例では、`orchestrator-planner` は `*` (拒否) と `orchestrator-*` (許可) の両方に一致しますが、`orchestrator-*` は `*` の後に来るため、結果は `allow` になります。
:::tip
ユーザーは、エージェントのタスク権限が拒否する場合でも、`@` オートコンプリートメニューを介して、いつでもサブエージェントを直接呼び出すことができます。
:::

---

### 色

`color` オプションを使用して、UI でのエージェントの外観をカスタマイズします。これは、インターフェイスでのエージェントの表示方法に影響します。

有効な 16 進カラー (例: `#FF5733`) またはテーマカラー: `primary`、`secondary`、`accent`、`success`、`warning`、`error`、`info` を使用します。

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

---

### Top P

`top_p` オプションで応答の多様性を制御します。ランダム性を制御するための温度の代替手段。

```json title="opencode.json"
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}
```

値の範囲は 0.0 ～ 1.0 です。値が低いほど集中力が高まり、値が高いほど多様性が高まります。

---

### 追加オプション

エージェント設定で指定したその他のオプションはすべて、モデルオプションとしてプロバイダーに**直接渡されます**。これにより、プロバイダー固有の機能とパラメーターを使用できるようになります。

たとえば、OpenAI の推論モデルを使用すると、推論の労力を制御できます。

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

これらの追加オプションはモデルとプロバイダーに固有です。使用可能なパラメータについては、プロバイダのドキュメントを確認してください。

:::tip
`opencode models` を実行して、利用可能なモデルのリストを表示します。
:::

---

## エージェントの作成

次のコマンドを使用して、新しいエージェントを作成できます。

```bash
opencode agent create
```

この対話型コマンドは次のことを行います。

1. エージェントを保存する場所を尋ねます。グローバルまたはプロジェクト固有。
2. エージェントが行うべきことの説明。
3. 適切なシステムプロンプトと識別子を生成します。
4. エージェントがアクセスできるツールを選択できます。
5. 最後に、エージェント設定を含む Markdown ファイルを作成します。

---

## ユースケース

さまざまなエージェントの一般的な使用例をいくつか示します。

- **ビルドエージェント**: すべてのツールを有効にした完全な開発作業
- **計画エージェント**: 変更を加えずに分析および計画を立てる
- **レビューエージェント**: 読み取り専用アクセスとドキュメントツールを備えたコードレビュー
- **デバッグエージェント**: bash および読み取りツールを有効にして調査に重点を置きます
- **ドキュメントエージェント**: ファイル操作を使用してドキュメントを作成しますが、システムコマンドは使用しません

---

## 例

以下に、役立つと思われるエージェントの例をいくつか示します。

:::tip
共有したいエージェントはいますか? [PR](https://github.com/anomalyco/opencode) を送信します。
:::

---

### ドキュメント作成エージェント

```markdown title="~/.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
```

---

### セキュリティ監査エージェント

```markdown title="~/.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
```