เป้าหมาย
เขียนโปรแกรมที่มี agent ตัวหลัก (orchestrator) แจกงานให้ agent ย่อย (workers) ที่มีสิทธิ์และโมเดลของตัวเอง คุมงบ ตรวจว่าใครถูกเรียก และรู้ว่าเมื่อไรควรย้ายไป Managed Agents ให้ Anthropic โฮสต์ให้
หลักการ
Orchestrator-worker
orchestrator (โมเดลใหญ่ คิดแผน รวมผล)
├─ worker A (โมเดลเล็ก, tool แคบ, งานเดียว)
├─ worker B
└─ worker C → ส่งกลับเฉพาะสรุป → orchestrator รวม/ตรวจ/ตอบ- ใน Agent SDK, worker คือ subagent ที่นิยามใน
agentsของ options (แบบเดียวกับไฟล์.claude/agents/ในบท 6d-08 แต่เขียนในโค้ด) - orchestrator ต้องมี tool
AgentในallowedToolsถึงจะแจกงานได้ - ข้อความที่มาจากใน subagent มี
parent_tool_use_id→ แยก log ของแต่ละ worker ได้
เลือกที่โฮสต์
| Agent SDK (บทนี้) | Managed Agents (beta) | |
|---|---|---|
| loop + sandbox | เราโฮสต์เอง | Anthropic โฮสต์ |
| หลาย agent | agents + tool Agent ซ้อนได้ 3 ชั้น |
ตั้ง multiagent ใน agent: subagent ได้ 1 ชั้น ลูกพร้อมกันสูงสุด 25 · workflow ได้ 64 thread พร้อมกัน, 1,000 agent ต่อการรัน |
| งบ | maxBudgetUsd / max_budget_usd |
budget ของ session (หยุดชั่วคราวเมื่อครบ) |
| เหมาะกับ | ระบบภายใน, CI, งานที่ต้องคุมทุกจังหวะ | agent ที่ต้องรันนาน รันตามเวลา และไม่อยากดูแลเซิร์ฟเวอร์ |
ตั้งค่า ⚙️
| option (TS / Python) | ทำอะไร | แนะนำเริ่มต้น |
|---|---|---|
agents / agents= |
นิยาม worker: description, prompt (บังคับ) + tools, model, maxTurns, effort, permissionMode ฯลฯ |
worker งานค้น/สรุปใช้ model: "haiku" และ tool อ่านอย่างเดียว |
allowedTools / allowed_tools |
ต้องมี "Agent" ให้ orchestrator แจกงานได้ |
["Read","Glob","Grep","Agent"] |
disallowedTools / disallowed_tools |
เอา tool ออกจริง (allowed อย่างเดียวไม่ได้กัน — บท 6d-07) | ตัด Edit, Write, Bash ถ้าเป็นงานอ่าน |
permissionMode |
"dontAsk" = อะไรที่ไม่อนุญาตถูกปฏิเสธทันที |
"dontAsk" สำหรับงานไม่มีคนเฝ้า |
maxTurns, maxBudgetUsd / max_turns, max_budget_usd |
เพดานเทิร์นและเงิน (ค่าประมาณฝั่ง client) จบด้วย error_max_budget_usd |
15 เทิร์น, $1 ขณะทดลอง |
env |
ส่ง env เช่น CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH: "1" (ห้าม worker สร้าง worker ต่อ), CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS |
depth 1 ขณะเริ่มต้น |
| อ่านผล | result.modelUsage แยกต้นทุนตามโมเดล |
log ทุกครั้ง |
ลองเลย 🧪
ทดลอง A — orchestrator + 2 workers (JavaScript, ทดสอบแล้ว) ต้องมี Node 18+ และ login Claude Code แล้ว (หรือตั้ง ANTHROPIC_API_KEY)
mkdir sdk-lab && cd sdk-lab && npm init -y >/dev/null
npm install @anthropic-ai/claude-agent-sdk
# ดาวน์โหลด orchestrator.mjs ด้านบนมาไว้ในโฟลเดอร์นี้
node orchestrator.mjs /path/to/your/repo→ ผลที่เราได้ (repo ทดลองบท 7d): สรุป 8 บรรทัด และ
{ subtype: 'success', turns: 1, cost: 0.33, subagents: [ 'doc-scout', 'test-scout' ] }
claude-haiku-5-5 0.004
claude-opus-5-5 0.325→ อ่านผล: worker ทั้งสองถูกเรียกจริง และต้นทุนเกือบทั้งหมดอยู่ที่ orchestrator — ถ้าอยากประหยัดต่อ ให้ลดโมเดลของ orchestrator (model: "sonnet" ใน options) ไม่ใช่ worker
ทดลอง B — แบบ Python (ต้อง Python 3.10+ และ pip install claude-agent-sdk) โครงเดียวกัน:
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
options = ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
disallowed_tools=["Edit", "Write", "Bash"],
permission_mode="dontAsk",
max_turns=15,
max_budget_usd=1.0,
agents={
"doc-scout": AgentDefinition(
description="หาเอกสารสำคัญของโปรเจกต์และสรุปสั้นๆ อ่านอย่างเดียว",
prompt="หาไฟล์เอกสารสำคัญ สรุปแต่ละไฟล์ 1 บรรทัด ไม่เกิน 5 ไฟล์",
tools=["Read", "Glob", "Grep"],
model="haiku",
),
},
)→ ⚠️ ตัวอย่าง Python มาจากเอกสาร ยังไม่ได้รันในคอร์สนี้
ทดลอง C — ทำให้ worker ตรวจกันเอง เพิ่ม worker ตัวที่สาม fact-checker ที่รับข้อสรุปของสองตัวแรกแล้วตรวจกับไฟล์จริง แก้ prompt ของ orchestrator ให้ "เรียก fact-checker หลัง worker ทั้งสองเสร็จ แล้วตัดข้อที่ตรวจไม่ผ่าน"
ถ้าพัง
| อาการ | สาเหตุที่พบบ่อย |
|---|---|
ไม่มี worker ถูกเรียก (subagents: []) |
ไม่มี "Agent" ใน allowedTools หรือ description ของ worker ไม่ตรงงาน → สั่งชื่อ worker ตรงๆ ใน prompt |
| worker ถูกปฏิเสธ tool | disallowedTools/allowlist ของ session คุม worker ด้วย |
| ชนงบเร็ว | orchestrator ใช้โมเดลใหญ่และอ่านไฟล์เอง → สั่งให้ "มอบหมายการอ่านให้ worker" |
-p/SDK ไม่มี agent teams |
ถูกต้อง: teams ใช้ได้เฉพาะ interactive (บท 8d-02) |
ข้อดี / ข้อเสีย
| ✅ ข้อดี | ❌ ข้อเสีย |
|---|---|
| คุมทุกอย่างในโค้ด: สิทธิ์ โมเดล งบ log ต่อ worker | เราดูแล deployment, sandbox, secret, การอัปเดต SDK เอง |
| worker โมเดลเล็กถูกมาก | orchestrator โมเดลใหญ่ยังเป็นต้นทุนหลัก |
| ทดสอบและใส่ eval ได้แบบโค้ดปกติ (บท 6d-05) | หลาย worker = debug ยากขึ้น ต้องแยก log ด้วย parent_tool_use_id |
ไม่ควรใช้เมื่อ: งานที่ workflow (บท 8d-03) หรือ subagent ใน Claude Code ทำได้อยู่แล้ว — เขียนระบบเองเมื่อต้องฝังในผลิตภัณฑ์หรือ pipeline ของบริษัทเท่านั้น
ทางเลือกที่ง่ายกว่า: claude -p + --agents '{...}' ในสคริปต์ shell (บท 6d-08 ทดลอง C) ได้ orchestrator-worker แบบเดียวกันโดยไม่ต้องเขียนโปรแกรม
สังเกตอะไร
- ต้นทุนส่วนใหญ่อยู่ที่ "ผู้คิด" ไม่ใช่ "ผู้ทำ" — เลือกโมเดลของ orchestrator ให้ดีที่สุดเท่าที่งานต้องการ แล้วให้ worker เป็นรุ่นเล็ก
- worker ที่ tool แคบและงานเดียว ทดสอบและเปลี่ยนตัวได้ง่ายเหมือนฟังก์ชัน
สรุปจำง่าย
Orchestrator คิดและรวม, worker ทำงานเดียวด้วยโมเดลเล็กและสิทธิ์แคบ — ใส่
Agentใน allowedTools, ตั้งงบ, และอ่านmodelUsageทุกครั้ง