ระดับ 8d · บทที่ 5/6

สร้างระบบหลาย agent เองด้วย Agent SDK — orchestrator-worker และ Managed Agents

⏱ 35 นาทีลองในClaude ↗
ข้อมูลบางส่วนอาจเปลี่ยน — ตรวจสอบก่อนใช้

บทนี้มีข้อมูลที่เปลี่ยนบ่อย (ฟีเจอร์ ราคา ชื่อเมนู) ตรวจกับเว็บทางการก่อนนำไปใช้

📎 ไฟล์ตัวอย่างสำหรับบทนี้

เป้าหมาย

เขียนโปรแกรมที่มี 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 ทุกครั้ง