path: root/packages/web/src/content/docs/ja/agents.mdx

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

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

:::tip
プラン エージェントを使用すると、コードを変更せずにコードを分析し、提案を確認できます。
:::
You can switch between agents during a session or invoke them with the `@` mention.

---

## 種類

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

---

### 主要エージェント

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

:::tip
**Tab** キーを使用して、セッション中にプライマリ エージェントを切り替えることができます。
:::
OpenCode には、**Build** と **Plan** という 2 つの組み込みプライマリ エージェントが付属しています。これらについて以下で説明します。

---

### サブエージェント

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

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

---

## 内蔵

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

---

### ビルドを使用する

_モード_: `primary`

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

---

### 利用プラン

_モード_: `primary`

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

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

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

---

### 一般的な使用

_モード_: `subagent`

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

---

### 探索を使用する

_モード_: `subagent`

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

---

### 圧縮を使用する

_モード_: `primary`

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

---

### タイトルを使用する

_モード_: `primary`

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

---

### 使用概要

_モード_: `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
      }
    }
  }
}
```

[tools](/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"
    }
  }
}
```

---

### トップ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
```