本文へスキップ
種類

エージェント

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

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

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

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

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

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

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

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

モード: primary

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

モード: primary

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

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

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

モード: subagent

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

モード: subagent

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

モード: subagent

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

モード: primary

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

モード: primary

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

モード: primary

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

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

  2. サブエージェントは次のように呼び出すことができます。

    • プライマリエージェントによって、説明に基づいて特殊なタスクを 自動的に 実行されます。

    • メッセージ内でサブエージェントを @ メンションすることで手動で実行できます。例えば。

      @general help me search for this function

  3. セッション間のナビゲーション: サブエージェントが独自の子セッションを作成する場合、以下を使用して親セッションとすべての子セッションの間を移動できます。

    • <Leader>+Right (または設定した session_child_cycle キーバインド) で、親 → 子 1 → 子 2 → … → 親と順に循環します。
    • <Leader>+Left (または設定した session_child_cycle_reverse キーバインド) で、親 ← 子 1 ← 子 2 ← … ← 親を逆方向に循環します。

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

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

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

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-5-5",
      "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-5-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

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

  • グローバル: ~/.config/opencode/agents/
  • プロジェクトごと: .opencode/agents/
~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-5-5
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 オプションを使用して、エージェントの機能とそれをいつ使用するかについての簡単な説明を提供します。

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

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

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

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

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: より創造的で多様な応答。ブレーンストーミングや探索に役立ちます。
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 です。

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

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

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

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

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

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

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

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

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

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

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

OpenCode 設定内のモデル ID は、provider/model-id という形式を使用します。たとえば、OpenCode Models を使用している場合、GPT-6.1 Sol には opencode/gpt-6.1-sol を使用します。

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

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

MCP サーバーからすべてのツールを無効にするには、次のようにします。

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

ツール について詳しくはこちらをご覧ください。

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

  • "ask" — ツールを実行する前に承認を求めるプロンプトを表示する
  • "allow" — 承認なしですべての操作を許可する
  • "deny" — ツールを無効にする
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

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

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

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

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

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

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

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

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

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

権限について詳しくはこちらをご覧ください。

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

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

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

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

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

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

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

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

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

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

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

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

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

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

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

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

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

opencode.json
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-6.1-sol",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

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

新しいエージェントを作成するには、プロジェクト用は .opencode/agents/、グローバル用は ~/.config/opencode/agents/ に Markdown ファイルを追加します。ファイル名がエージェント名になり、フロントマターで説明、モード、モデル、権限を設定します。ファイル形式については、上記の Markdown を参照してください。

opencode agent list を実行すると、OpenCode が読み込んだエージェントを一覧表示できます。

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

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

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

~/.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

~/.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