⚡
OpenCodeDocs

Agents là các trợ lý AI chuyên biệt có thể được cấu hình cho các tác vụ và workflows cụ thể. Chúng cho phép bạn tạo các công cụ tập trung với prompts tùy chỉnh, models, và quyền truy cập tools.

:::tip Sử dụng agent plan để phân tích code và xem xét gợi ý mà không thực hiện bất kỳ thay đổi code nào. :::

Bạn có thể chuyển đổi giữa các agents trong một session hoặc gọi chúng bằng cách mention @.

Các loại

Có hai loại agents trong OpenCode: primary agents và subagents.

Primary agents

Primary agents là các trợ lý chính mà bạn tương tác trực tiếp. Bạn có thể chuyển đổi giữa chúng bằng phím Tab, hoặc keybind switch_agent đã cấu hình. Những agents này xử lý cuộc hội thoại chính của bạn. Quyền truy cập tools được cấu hình qua permissions — ví dụ, Build có tất cả tools được bật trong khi Plan bị giới hạn.

:::tip Bạn có thể sử dụng phím Tab để chuyển đổi giữa các primary agents trong session. :::

OpenCode đi kèm với hai primary agents tích hợp sẵn, Build và Plan. Chúng ta sẽ xem xét chúng bên dưới.

Subagents

Subagents là các trợ lý chuyên biệt mà primary agents có thể gọi cho các tác vụ cụ thể. Bạn cũng có thể gọi thủ công bằng cách @ mention chúng trong tin nhắn.

OpenCode đi kèm với hai subagents tích hợp sẵn, General và Explore. Chúng ta sẽ xem xét bên dưới.

Tích hợp sẵn

OpenCode đi kèm với hai primary agents tích hợp sẵn và hai subagents tích hợp sẵn.

Build

Mode: primary

Build là primary agent mặc định với tất cả tools được bật. Đây là agent tiêu chuẩn cho công việc development khi bạn cần quyền truy cập đầy đủ vào các thao tác file và lệnh hệ thống.

Plan

Mode: primary

Một agent bị giới hạn được thiết kế cho lập kế hoạch và phân tích. Chúng tôi sử dụng hệ thống permission để cho bạn nhiều quyền kiểm soát hơn và ngăn chặn các thay đổi không mong muốn. Mặc định, tất cả các mục sau được đặt thành ask:

  • file edits: Tất cả ghi, patch, và chỉnh sửa
  • bash: Tất cả lệnh bash

Agent này hữu ích khi bạn muốn LLM phân tích code, đề xuất thay đổi, hoặc tạo kế hoạch mà không thực hiện bất kỳ sửa đổi thực tế nào vào codebase.

General

Mode: subagent

Một agent đa năng để nghiên cứu các câu hỏi phức tạp và thực thi các tác vụ nhiều bước. Có quyền truy cập đầy đủ tools (ngoại trừ todo), nên có thể thực hiện thay đổi file khi cần. Sử dụng để chạy nhiều đơn vị công việc song song.

Explore

Mode: subagent

Một agent nhanh, chỉ-đọc để khám phá codebases. Không thể sửa đổi files. Sử dụng khi bạn cần tìm kiếm nhanh files theo patterns, tìm kiếm code theo keywords, hoặc trả lời câu hỏi về codebase.

Cách sử dụng

  1. Với primary agents, sử dụng phím Tab để chuyển đổi giữa chúng trong session. Bạn cũng có thể sử dụng keybind switch_agent đã cấu hình.

  2. Subagents có thể được gọi:

    • Tự động bởi primary agents cho các tác vụ chuyên biệt dựa trên descriptions của chúng.

    • Thủ công bằng cách @ mention một subagent trong tin nhắn. Ví dụ:

      @general help me search for this function

  3. Điều hướng giữa các sessions: Khi subagents tạo các child sessions riêng, bạn có thể điều hướng giữa parent session và tất cả child sessions bằng:

    • <Leader>+Right (hoặc keybind session_child_cycle đã cấu hình) để chuyển tiếp qua parent → child1 → child2 → ... → parent
    • <Leader>+Left (hoặc keybind session_child_cycle_reverse đã cấu hình) để chuyển ngược qua parent ← child1 ← child2 ← ... ← parent

    Điều này cho phép bạn chuyển đổi liền mạch giữa cuộc hội thoại chính và công việc subagent chuyên biệt.

Cấu hình

Bạn có thể tùy chỉnh các agents tích hợp sẵn hoặc tạo agents riêng qua cấu hình. Agents có thể được cấu hình theo hai cách:

JSON

Cấu hình agents trong file config 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

Bạn cũng có thể định nghĩa agents sử dụng các file markdown. Đặt chúng vào:

  • Global: ~/.config/opencode/agents/
  • Per-project: .opencode/agents/
---
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.

Tên file markdown trở thành tên agent. Ví dụ, review.md tạo agent review.

Các tùy chọn

Hãy xem xét các tùy chọn cấu hình này chi tiết.

Description

Sử dụng tùy chọn description để cung cấp mô tả ngắn gọn về agent làm gì và khi nào sử dụng.

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

Đây là tùy chọn cấu hình bắt buộc.

Temperature

Kiểm soát độ ngẫu nhiên và sáng tạo của responses từ LLM với config temperature.

Giá trị thấp hơn làm responses tập trung và xác định hơn, trong khi giá trị cao hơn tăng sáng tạo và biến đổi.

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Giá trị temperature thường nằm trong khoảng 0.0 đến 1.0:

  • 0.0-0.2: Responses rất tập trung và xác định, lý tưởng cho phân tích code và lập kế hoạch
  • 0.3-0.5: Responses cân bằng với một chút sáng tạo, tốt cho các tác vụ development chung
  • 0.6-1.0: Responses sáng tạo và đa dạng hơn, hữu ích cho brainstorming và khám phá
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Nếu không chỉ định temperature, OpenCode sử dụng giá trị mặc định theo model; thường là 0 cho hầu hết models, 0.55 cho models Qwen.

Max steps

Kiểm soát số lượng iterations agentic tối đa mà agent có thể thực hiện trước khi bị buộc phải respond chỉ bằng text. Điều này cho phép người dùng muốn kiểm soát chi phí đặt giới hạn cho các agentic actions.

Nếu không được đặt, agent sẽ tiếp tục iterate cho đến khi model chọn dừng hoặc người dùng interrupt session.

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

Khi đạt giới hạn, agent nhận một system prompt đặc biệt chỉ dẫn nó respond với tóm tắt công việc và các tác vụ còn lại được đề xuất.

Disable

Đặt thành true để vô hiệu hóa agent.

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Chỉ định file system prompt tùy chỉnh cho agent với config prompt. File prompt nên chứa các hướng dẫn cụ thể cho mục đích của agent.

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

Đường dẫn này tương đối với vị trí file config. Vì vậy nó hoạt động cho cả config OpenCode global và config project cụ thể.

Model

Sử dụng config model để ghi đè model cho agent này. Hữu ích để sử dụng các models khác nhau được tối ưu cho các tác vụ khác nhau. Ví dụ, model nhanh hơn cho planning, model mạnh hơn cho implementation.

:::tip Nếu bạn không chỉ định model, primary agents sử dụng model được cấu hình globally trong khi subagents sẽ sử dụng model của primary agent đã gọi subagent. :::

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

Model ID trong config OpenCode sử dụng định dạng provider/model-id. Ví dụ, nếu bạn sử dụng OpenCode Zen, bạn sẽ dùng opencode/gpt-5.1-codex cho GPT 5.1 Codex.

Tools

Kiểm soát tools nào có sẵn trong agent với config tools. Bạn có thể bật hoặc tắt các tools cụ thể bằng cách đặt chúng thành true hoặc false.

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

:::note Config agent-specific ghi đè config global. :::

Bạn cũng có thể sử dụng wildcards để kiểm soát nhiều tools cùng lúc. Ví dụ, để tắt tất cả tools từ MCP server:

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

Tìm hiểu thêm về tools.

Permissions

Bạn có thể cấu hình permissions để quản lý actions mà agent có thể thực hiện. Hiện tại, permissions cho tools edit, bash, và webfetch có thể được cấu hình thành:

  • "ask" — Yêu cầu phê duyệt trước khi chạy tool
  • "allow" — Cho phép tất cả operations không cần phê duyệt
  • "deny" — Vô hiệu hóa tool
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Bạn có thể ghi đè các permissions này theo từng agent.

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

Bạn cũng có thể đặt permissions trong Markdown agents.

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

Bạn có thể đặt permissions cho các lệnh bash cụ thể.

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

Có thể sử dụng glob pattern.

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

Và bạn cũng có thể sử dụng wildcard * để quản lý permissions cho tất cả commands. Vì rule khớp cuối cùng được ưu tiên, đặt wildcard * trước và các rules cụ thể sau.

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

Tìm hiểu thêm về permissions.

Mode

Kiểm soát mode của agent với config mode. Tùy chọn mode được sử dụng để xác định cách agent có thể được sử dụng.

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

Tùy chọn mode có thể được đặt thành primary, subagent, hoặc all. Nếu không chỉ định mode, mặc định là all.

Hidden

Ẩn subagent khỏi menu autocomplete @ với hidden: true. Hữu ích cho các subagents nội bộ chỉ nên được gọi programmatically bởi các agents khác qua Task tool.

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

Điều này chỉ ảnh hưởng đến visibility của user trong menu autocomplete. Hidden agents vẫn có thể được gọi bởi model qua Task tool nếu permissions cho phép.

:::note Chỉ áp dụng cho agents có mode: subagent. :::

Task permissions

Kiểm soát subagents nào mà agent có thể gọi qua Task tool với permission.task. Sử dụng glob patterns để matching linh hoạt.

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

Khi đặt thành deny, subagent bị loại bỏ hoàn toàn khỏi Task tool description, nên model sẽ không cố gắng gọi nó.

:::tip Rules được đánh giá theo thứ tự, và rule khớp cuối cùng thắng. Trong ví dụ trên, orchestrator-planner khớp cả * (deny) và orchestrator-* (allow), nhưng vì orchestrator-* đến sau *, kết quả là allow. :::

:::tip Users luôn có thể gọi bất kỳ subagent nào trực tiếp qua menu autocomplete @, ngay cả khi task permissions của agent sẽ deny nó. :::

Additional

Bất kỳ tùy chọn nào khác bạn chỉ định trong agent configuration sẽ được truyền trực tiếp đến provider như model options. Điều này cho phép bạn sử dụng các tính năng và parameters cụ thể của provider.

Ví dụ, với reasoning models của OpenAI, bạn có thể kiểm soát reasoning effort:

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

Các tùy chọn bổ sung này là cụ thể cho model và provider. Kiểm tra documentation của provider để biết các parameters có sẵn.

:::tip Chạy opencode models để xem danh sách các models có sẵn. :::

Tạo agents

Bạn có thể tạo agents mới sử dụng lệnh sau:

opencode agent create

Lệnh interactive này sẽ:

  1. Hỏi nơi lưu agent; global hoặc project-specific.
  2. Mô tả về agent nên làm gì.
  3. Tạo system prompt và identifier phù hợp.
  4. Cho phép bạn chọn tools nào agent có thể truy cập.
  5. Cuối cùng, tạo file markdown với agent configuration.

Các use cases

Dưới đây là một số use cases phổ biến cho các agents khác nhau.

  • Build agent: Công việc development đầy đủ với tất cả tools được bật
  • Plan agent: Phân tích và lập kế hoạch mà không thực hiện thay đổi
  • Review agent: Code review với quyền truy cập chỉ-đọc cộng với documentation tools
  • Debug agent: Tập trung vào điều tra với bash và read tools được bật
  • Docs agent: Viết documentation với file operations nhưng không có system commands

Ví dụ

Dưới đây là một số agent mẫu mà bạn có thể thấy hữu ích.

:::tip Bạn có agent muốn chia sẻ? Gửi PR. :::

Documentation agent

---
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

Security auditor

---
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