Agent Configuration Guide

When you master Agent configuration and usage, you can upgrade from "conversational programming" to "orchestrated development". This article will detail Opencode's Agent system.

What is an Agent?

In Opencode, an Agent is an AI unit with specific roles and capabilities. Different Agents excel at different tasks:

Some excel at architecture design
Some excel at quick search
Some excel at documentation writing
Some excel at frontend development

Through proper configuration and orchestration of Agents, you can make an AI team collaborate like a real team.

Built-in Agents

Opencode includes multiple professional Agents:

Agent Name	Role	Specialties	Recommended Model
plan	Planner	Task breakdown, solution design	Claude Opus
build	Executor	Code implementation, file modification	Claude Sonnet
architect	Architect	System design, technology selection	GPT-5.2
explorer	Explorer	Code search, structure analysis	Gemini Flash
documenter	Documentation Expert	Documentation writing, comment generation	Claude Sonnet
reviewer	Reviewer	Code review, security checks	Claude Opus

How to Use Agents?

Method 1: Direct @ Mention

Directly @ Agent name in conversation:

Have @architect design a user authentication system architecture

Have @explorer find all API call code

Have @reviewer review this PR's security

Method 2: Switch Default Agent

Run /agents command and select the Agent you want to use.

Method 3: Specify in Configuration

Set default Agent in opencode.json:

{
  "default_agent": "plan"
}

Agent Collaboration Example

Scenario: Developing New Feature

Suppose you want to develop a payment feature:

1. @architect design payment system architecture
2. @explorer search existing payment-related code
3. @plan create implementation plan based on architecture
4. @build implement code according to plan
5. @reviewer review code security and performance

Custom Agents

You can create your own Agents. Add to opencode.json:

{
  "agent": {
    "frontend-expert": {
      "description": "Frontend development expert, proficient in React and Vue",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a senior frontend engineer, proficient in React, Vue, TypeScript, and modern CSS.",
      "tools": {
        "read": true,
        "write": true,
        "edit": true,
        "bash": "ask"
      }
    },
    
    "security-auditor": {
      "description": "Security audit expert",
      "model": "anthropic/claude-opus-4-5",
      "prompt": "You are a security audit expert focusing on finding security vulnerabilities, performance issues, and potential bugs.",
      "tools": {
        "read": true,
        "write": false,
        "edit": false,
        "bash": "deny"
      }
    }
  }
}

Agent Configuration Options

Option	Type	Description
`description`	string	Agent description
`model`	string	AI model to use
`prompt`	string	System prompt defining Agent role and behavior
`temperature`	number	0-1, controls output randomness
`tools`	object	Tool permission configuration

Agent Division Strategies

Strategy 1: Division by Task Type

{
  "agent": {
    "quick-fix": {
      "description": "Quick fix for small issues",
      "model": "deepseek/deepseek-coder",
      "prompt": "You focus on quickly fixing simple bugs and small issues."
    },
    "complex-task": {
      "description": "Handle complex tasks",
      "model": "anthropic/claude-opus-4-5",
      "prompt": "You handle complex architecture design and refactoring tasks."
    }
  }
}

Strategy 2: Division by Tech Stack

{
  "agent": {
    "backend-dev": {
      "description": "Backend development",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a backend engineer, proficient in Node.js, Python, and database design."
    },
    "frontend-dev": {
      "description": "Frontend development",
      "model": "openai/gpt-5.2",
      "prompt": "You are a frontend engineer, proficient in React, Vue, and modern CSS."
    }
  }
}

Common Questions

Q: How to view all available Agents?

Run /agents command.

Q: Can I use multiple Agents simultaneously?

Yes. @ multiple Agents in conversation, and they will collaborate to complete tasks.

Yes. All Agents in the same session share conversation history.

Next Steps

Compiled by the OpenCodex community.