บทที่ 3: Agents & Subagents¶
3.1 Agent คืออะไรกันแน่¶
Agent = 4 อย่างรวมกันเป็นโปรไฟล์เดียว
ไม่ใช่ "โหมด" หรือ "คำสั่ง" — มันคือ ตัวตน ที่กำหนดว่าใครคิด ใช้โมเดลไหน และแตะอะไรได้บ้าง
3.2 Agent ที่มีให้จริงบนเครื่องนี้¶
ผลจริง (สรุป):
| id | mode | hidden | จำนวนกฎ | หน้าที่ |
|---|---|---|---|---|
build |
primary | ❌ | 33 | agent เริ่มต้น ทำงานเต็มรูปแบบ |
plan |
primary | ❌ | 35 | สำรวจ/วางแผน ห้ามแก้ไฟล์โปรเจกต์ |
explore |
subagent | ❌ | 44 | ค้นหา/อ่านโค้ด ไม่แก้อะไร (deny-all + allow เฉพาะอ่าน) |
general |
subagent | ❌ | 34 | งานวิจัยหลายขั้น ห้ามถาม ห้ามเรียก subagent ต่อ |
compaction |
primary | ✅ | 32 | งานเบื้องหลัง (บีบ context) |
title |
primary | ✅ | 33 | ตั้งชื่อ session |
summary |
primary | ✅ | 33 | สรุป session |
อ่านตัวเลขนี้ให้เป็น: build มี 33 กฎ ไม่ใช่เพราะ built-in เยอะ แต่เพราะ กฎของคุณต่อท้ายเข้าไป — ถ้าเปิดดูจะเห็น .env โผล่ซ้ำ 2 รอบ:
[ { "action": "*", "resource": "*", "effect": "allow" }, // base
{ "action": "read", "resource": "*.env", "effect": "ask" }, // base
...
{ "action": "read", "resource": "*.env", "effect": "ask" }, // ← ของคุณ (บทที่ 2)
{ "action": "shell", "resource": "sudo *", "effect": "deny" } // ← ของคุณ
]
นี่คือหลัก "permission rules append" จาก docs: global → agent → (กฎของ client/harness) เรียงต่อกัน แล้วใช้ last match wins — ดังนั้นกฎของ agent มีสิทธิ์ refine กฎ global ได้ แต่ ลบกฎ global ไม่ได้
3.3 Modes: ที่อยู่ของ agent¶
| Mode | รันที่ไหน | ใช้เมื่อ |
|---|---|---|
primary |
session หลัก (คนคุยด้วย) | ค่าเริ่มต้นของ agent ใหม่ |
subagent |
child session ผ่าน tool subagent |
งานที่อยากแยก context |
all |
ได้ทั้งสองแบบ | agent อเนกประสงค์ |
ข้อควรรู้: default_agent ไม่เปลี่ยน agent ของ session ที่มีอยู่แล้ว และ model ของ session ก็เก็บแยก — เลือก agent ไม่เท่ากับเปลี่ยนโมเดล
3.4 Subagent ทำงานอย่างไร (สำคัญที่สุดของบทนี้)¶
Parent session ──► subagent tool ──► Child session (context ใหม่ทั้งหมด)
▲ │
└────────── report เมื่อ child idle ◄───┘
4 คุณสมบัติที่ต้องจำ:
- Fresh context — child ไม่เห็นประวัติสนทนาของ parent ต้องส่ง context ไปให้ครบใน prompt
- Background เสมอ — parent ไม่บล็อกรอ แต่ได้ report เมื่อ child ว่าง และได้อีกครั้งถ้ามีงานรอบใหม่
- สิทธิ์แยกกัน — child ใช้ permission ของตัวเอง ไม่ใช่ subset ของ parent (สำคัญมาก: subagent ไม่ได้ "อ่อนกว่า" โดยอัตโนมัติ)
- ใครเรียกใครได้ ถูกคุมที่ parent — ด้วย action
subagent:
{
"agents": {
"orchestrator": {
"permissions": [
{ "action": "subagent", "resource": "*", "effect": "deny" },
{ "action": "subagent", "resource": "reviewer", "effect": "allow" }
]
}
}
}
general ถูกตั้งมาแบบนี้อยู่แล้ว (ห้ามเรียก subagent ต่อ) — กันการระเบิดเป็นต้นไม้
3.5 สร้าง agent เอง: Markdown คือวิธีที่อ่านง่ายที่สุด¶
<!-- ~/.config/opencode/agents/reviewer.md -->
---
description: Reviews changes for correctness and regressions
mode: subagent
model: opencode/big-pickle
permissions:
- action: edit
resource: "*"
effect: deny
- action: shell
resource: "*"
effect: deny
---
Review the current changes. List findings in severity order with file and line references.
Do not modify files.
- frontmatter = config, body =
systemprompt - วางที่
~/.config/opencode/agents/(global) หรือ.opencode/agents/(โปรเจกต์) - path ซ้อนกลายเป็น ID:
.opencode/agents/team/reviewer.md→team/reviewer - ทางเลือก: นิยามใน
opencode.jsoncภายใต้agents(ใช้เมื่ออยากให้ทุกอย่างอยู่ในไฟล์เดียว)
3.6 Options ที่มีผลจริง¶
| Field | ค่า | ใช้ทำอะไร |
|---|---|---|
description |
string | จำเป็นสำหรับ subagent — โมเดลใช้เลือกว่าจะเรียกตัวไหน |
mode |
primary/subagent/all |
ที่อยู่ |
model |
provider/model#variant |
child ไม่ตั้ง = ใช้โมเดลของ parent |
system |
string | แทน base prompt ของ provider (instruction อื่นยังถูกเพิ่ม) |
permissions |
rules | ordered, last wins |
steps |
number | เพดานจำนวน step ของโมเดล แล้วบังคับสรุปเป็นข้อความ |
hidden |
bool | ซ่อนจาก listing — ไม่ใช่ security |
color |
#ff6b6b |
สีใน UI |
disabled |
bool | ปิด agent นั้น ณ จุดนั้นของ config |
request |
headers/body | ⚠️ V2 เก็บไว้แต่ ยังไม่ส่งจริง |
3.7 กับดักที่ต้องระวัง¶
hidden: true≠ ปลอดภัย — มันแค่ซ่อนจากรายการ ต้องใช้permissionsคุมพฤติกรรม- V1 fields เลิกใช้ —
permission,tools,temperature,maxSteps,disable,promptอย่าเขียนใน V2 ให้ใช้permissions,steps,disabled,system - ทับ built-in ด้วย ID เดียวกัน —
agents.build.permissionsจะ ต่อท้าย กฎเดิม ไม่ใช่แทนที่ planไม่ได้แก้อะไรไม่ได้เลย — มันเขียนไฟล์ plan ใต้~/.opencode/planได้ และ shell ยังถูกคุมด้วย permissionexplore44 กฎ เพราะสร้างจาก deny-all แล้ว allow เฉพาะ read/glob/grep/shell/webfetch — อ่าน.envยัง ask
3.8 แบบฝึกหัด 3 ข้อ¶
# 1) เทียบสิทธิ์ plan กับ explore แบบเห็นชัด ๆ
opencode debug agents | python3 -c '
import json,sys
for a in json.load(sys.stdin):
if a["id"] in ("plan","explore"):
print("==",a["id"],len(a["permissions"]))
for r in a["permissions"][-4:]: print(" ",r["action"],r["resource"],"->",r["effect"])
'
# 2) ลองใช้ agent ที่มีอยู่กับงานจริง (ไม่ต้องมีไฟล์ใหม่)
cd /tmp/opencode/config-lab && opencode run --agent plan 'List the config files here and explain the precedence. Do not edit anything.'
# 3) ดูว่า id/mode ที่เราจะสร้างชนกับของเดิมไหม
ls ~/.config/opencode/agents/ 2>/dev/null || echo "(ยังไม่มีโฟลเดอร์ agents)"