สร้างเอเจนต์อัตโนมัติด้วย Claude Code SDK: คู่มือปฏิบัติสำหรับนักพัฒนา

สร้างเอเจนต์อัตโนมัติด้วย Claude Code SDK: คู่มือปฏิบัติสำหรับนักพัฒนา

Claude Code SDK — หรือชื่อทางการคือ Agent SDK — คือไลบรารี Python และ TypeScript ที่ให้คุณควบคุมเอนจินเอเจนต์เต็มรูปแบบของ Claude Code แบบเป็นโปรแกรมได้: ไม่ต้องใช้เทอร์มินัล ไม่ต้องมีมนุษย์นั่งหน้าคีย์บอร์ด แค่แอปพลิเคชันของคุณเรียกฟังก์ชัน query() แบบ async แล้วรับสตรีมทุกขั้นตอนการทำงานของเอเจนต์กลับมา ถ้าคุณเคยใช้ Claude Code แบบโต้ตอบมาก่อน SDK จะให้ลูปการทำงาน อ่านไฟล์ / แก้ไขโค้ด / รันคำสั่ง แบบเดียวกันนั้น ในรูปแบบไลบรารีที่ประกอบเข้าด้วยกันได้ ซึ่งคุณสามารถฝังลงใน CI pipeline, บอทรีวิวโค้ด, ระบบจัดการมัลติเอเจนต์ หรือบริการแบ็กเอนด์ใดก็ได้

Agent SDK คืออะไร — และทำไมมันถึงมีอยู่

Claude Code เป็นที่รู้จักดีในฐานะเครื่องมือเทอร์มินัล คุณพิมพ์พรอมป์ เอเจนต์จะวิเคราะห์โค้ดเบสของคุณ เรียกใช้ทูลที่มีอยู่ในตัว (Read, Edit, Bash, Grep และอื่น ๆ) แล้วเขียนผลลัพธ์กลับมาให้คุณ แต่ในวินาทีที่คุณต้องการทำให้ลูปนั้นเป็นระบบอัตโนมัติ — เช่น สั่งให้รีวิวทุก pull request, แยกงานไปยังซับเอเจนต์เฉพาะทางหลายตัว หรือสร้างผลิตภัณฑ์ต่อยอดจากมัน — CLI แบบโต้ตอบจะไม่ใช่การแยกส่วน (abstraction) ที่เหมาะสมอีกต่อไป คุณต้องการไลบรารี

Agent SDK เข้ามาเติมช่องว่างนี้ ตามเอกสารทางการของ Anthropic ระบุว่ามันเปิดให้ใช้ "ทูล ลูปเอเจนต์ และการจัดการคอนเท็กซ์แบบเดียวกันที่ขับเคลื่อน Claude Code ในรูปแบบที่เขียนโปรแกรมได้ด้วย Python และ TypeScript" นี่ไม่ใช่ภาษาโฆษณา แต่เป็นสถาปัตยกรรมตามตัวอักษรจริง ๆ SDK จะสั่งรันไบนารีของ Claude Code CLI เป็นซับโปรเซสที่ถูกจัดการ สื่อสารกับมันผ่าน stdio และแสดงผลทุกอย่างออกมาเป็นสตรีมแบบ async ของอ็อบเจ็กต์ข้อความที่มีชนิดกำหนดไว้ ซึ่งโค้ดของคุณสามารถอ่านและตอบสนองได้

ความแตกต่างนี้สำคัญด้วยหลายเหตุผล:

เอนจินเดียวกัน อินเทอร์เฟซต่างกัน เมื่อคุณเปลี่ยนจาก CLI มาใช้ SDK คุณไม่ได้ย้ายไปใช้เครื่องมือที่ด้อยหรือเรียบง่ายกว่า SDK สืบทอดทุกความสามารถของ CLI มาทั้งหมด — การเชื่อมต่อ MCP server, วงจร hooks, ไฟล์ skill, ความจำ CLAUDE.md, การมอบงานให้ซับเอเจนต์ และรายการทูลทั้งหมด

SDK ทำการเรียกใช้ทูลให้คุณ หากคุณใช้ Anthropic Client SDK (แพ็กเกจ anthropic Python/JS ระดับล่าง) และต้องการให้ Claude เรียกใช้ทูล คุณจะต้องเขียนลูปทูลเองทั้งหมด: เรียก API ตรวจจับการตอบสนองที่เป็นการใช้ทูล เรียกทูลนั้น ส่งผลลัพธ์กลับไป ทำซ้ำจนกว่า Claude จะหยุด แต่ Agent SDK ย่อลูปทั้งหมดนี้ให้เหลือแค่ async for message in query(...) เพียงบรรทัดเดียว — Claude จะจัดการว่าจะเรียกทูลไหน รันมันภายในซับโปรเซสของตัวเอง และวนลูปต่อไปจนกว่างานจะเสร็จ คุณแค่รับสตรีมนั้นไปใช้

ออกแบบมาให้ไม่ต้องมีคนคอยกด (headless) พรอมป์การขออนุญาตของ CLI — "อนุญาตให้รันคำสั่ง bash นี้หรือไม่?" — จะบล็อกรอการตอบจากมนุษย์ SDK แทนที่สิ่งนี้ด้วยออปชัน permissionMode และชุดโหมดการอนุญาต — เช่น acceptEdits เพื่ออนุมัติการแก้ไขไฟล์อัตโนมัติ และ bypassPermissions เพื่อรันทุกอย่างโดยไม่ต้องขออนุญาตในสภาพแวดล้อม CI แบบแซนด์บ็อกซ์ — พร้อมทั้ง callback การอนุมัติแบบเป็นโปรแกรมสำหรับโฟลว์แบบกำหนดเอง ชื่อโหมดที่แน่นอนและพฤติกรรมของมันถูกบันทึกไว้ในเอกสารอ้างอิง SDK ของ Anthropic (ตรวจสอบรายการล่าสุดที่นั่น) แต่ผลลัพธ์ก็เหมือนกัน: ระบบอัตโนมัติของคุณจะไม่มีทางหยุดค้างรอการกดปุ่มอีกต่อไป

เอนจิน Claude Code เดียวกัน แต่มีสองอินเทอร์เฟซ: CLI แบบโต้ตอบสำหรับงานที่ต้องมีมนุษย์อยู่ในลูป และ Agent SDK สำหรับระบบอัตโนมัติแบบเป็นโปรแกรมที่ไม่ต้องมีคนคอยดู ซึ่งแอปพลิเคชันของคุณควบคุมพรอมป์เอง และโหมดการอนุญาตจะเข้ามาแทนไดอะล็อกขออนุมัติ

การติดตั้ง SDK

Anthropic เผยแพร่แพ็กเกจไว้สองตัว:

• TypeScript: @anthropic-ai/claude-agent-sdk (npm)
• Python: claude-agent-sdk (pip; ต้องใช้ Python 3.10 ขึ้นไป)

แพ็กเกจ TypeScript มีไบนารี Claude Code แบบเนทีฟสำหรับแพลตฟอร์มของคุณรวมอยู่ในตัว จึงไม่จำเป็นต้องติดตั้ง CLI แยกต่างหาก การยืนยันตัวตนทำผ่านตัวแปรสภาพแวดล้อม ANTHROPIC_API_KEY ที่ได้จาก Anthropic Console SDK ยังรองรับ Amazon Bedrock, Google Vertex AI และ Microsoft Azure AI Foundry — ดูรูปแบบตัวแปรสภาพแวดล้อมที่เกี่ยวข้องได้จากเอกสารของ Anthropic

แนวคิดหลัก

การเข้าใจแนวคิดสี่ข้อนี้ครอบคลุมการใช้งาน SDK ในโลกจริงส่วนใหญ่

1. ฟังก์ชัน query() และสตรีมข้อความแบบ Async

ทุกการโต้ตอบกับ SDK เริ่มต้นด้วย query() คุณส่งสตริง prompt และอ็อบเจ็กต์ options เข้าไป แล้วจะได้ตัววนซ้ำ (iterator) แบบ async ที่ปล่อยอ็อบเจ็กต์ข้อความที่มีชนิดกำหนดไว้ ขณะที่เอเจนต์กำลังทำงาน ลูปจะสิ้นสุดเมื่อเอเจนต์ทำงานเสร็จหรือเจอข้อผิดพลาด

ข้อความที่คุณได้รับมีดังนี้:

• AssistantMessage — ข้อความการให้เหตุผลของ Claude และคำอธิบายการเรียกใช้ทูล
• ToolResultMessage — ผลลัพธ์ของการรันทูลแต่ละครั้ง
• ResultMessage — ผลลัพธ์สุดท้าย พร้อมฟิลด์ subtype ที่บอกว่าสำเร็จหรือล้มเหลว
• SystemMessage — เหตุการณ์วงจรชีวิตของเซสชัน (subtype init จะมี session_id)

ในโค้ดที่ใช้งานจริงส่วนใหญ่ คุณจะกรองหา ResultMessage เพื่อดึงผลลัพธ์สุดท้าย และอาจบันทึกบล็อก AssistantMessage ไว้เพื่อดูว่าเอเจนต์ทำอะไรไปบ้าง

2. ทูลและ allowedTools

รายการทูลที่มีในตัวของ SDK สอดคล้องตรงกับความสามารถของ Claude Code:

ออปชัน allowedTools จะอนุมัติล่วงหน้าให้กับส่วนหนึ่งของทูลเหล่านี้ ซึ่งเท่ากับให้สิทธิ์เอเจนต์เรียกใช้ได้โดยไม่ต้องผ่านการตรวจสอบเพิ่มเติมใด ๆ เอเจนต์ตรวจสอบแบบอ่านอย่างเดียวอาจระบุแค่ ["Read", "Glob", "Grep"] ในขณะที่ระบบอัตโนมัติเต็มรูปแบบอาจรวม ["Read", "Edit", "Bash", "Glob", "Grep"]

3. โหมดการอนุญาต (Permission Modes)

โหมดการอนุญาตควบคุมสิ่งที่จะเกิดขึ้นเมื่อเอเจนต์ต้องการใช้ทูลที่ไม่ได้ถูกอนุมัติล่วงหน้าใน allowedTools:

• acceptEdits — อนุมัติการแก้ไขไฟล์และการทำงานกับไฟล์ระบบทั่วไปโดยอัตโนมัติ แต่จะขออนุญาตสำหรับทุกอย่างอื่น เหมาะสำหรับเวิร์กโฟลว์การพัฒนาที่เชื่อถือได้
• dontAsk — ปฏิเสธทุกอย่างที่ไม่อยู่ใน allowedTools โดยไม่ต้องแจ้งเตือน เหมาะสำหรับเอเจนต์แบบ headless ที่ถูกจำกัดสิทธิ์อย่างเข้มงวด
• bypassPermissions — รันทุกทูลโดยไม่ผ่านการตรวจสอบเลย ใช้เฉพาะภายในสภาพแวดล้อมแซนด์บ็อกซ์เท่านั้น

SDK ยังเปิดให้ใช้ callback การอนุมัติแบบเป็นโปรแกรม เพื่อให้คุณสามารถสร้างตรรกะการอนุมัติแบบกำหนดเองได้เต็มรูปแบบ และรายชื่อโหมดที่มีอยู่อาจเพิ่มขึ้นเรื่อย ๆ ในอนาคต — ควรตรวจสอบเอกสารอ้างอิง SDK ของ Anthropic เพื่อดูรายการที่เป็นทางการล่าสุด และพฤติกรรมที่แน่นอนของแต่ละโหมด ในสภาพแวดล้อม CI คุณจะเกือบทุกครั้งใช้การกำหนดค่าที่จำกัดขอบเขตอย่างเข้มงวดแบบ deny-by-default หรือใช้ bypassPermissions ภายในคอนเทนเนอร์แซนด์บ็อกซ์ที่คุณควบคุมเอง

4. เซสชัน การเรียกกลับ (Resumption) และคอนเท็กซ์

การเรียก query() แต่ละครั้งจะสร้าง (หรือเรียกกลับมาใช้) เซสชันหนึ่ง session_id ของเซสชันนั้นจะมาถึงใน SystemMessage แรกที่มี subtype === "init" คุณสามารถบันทึกไว้และส่งเป็น resume: sessionId ในการเรียกครั้งต่อไป เพื่อดำเนินการต่อจากจุดที่บทสนทนาหยุดไว้พอดี — การอ่านไฟล์เดิม ประวัติการให้เหตุผลเดิม และหน้าต่างคอนเท็กซ์เดิม

นี่คือวิธีสร้างเอเจนต์แบบหลายเทิร์น: การเรียก query() ครั้งแรกวิเคราะห์โมดูลหนึ่ง บันทึก session_id แล้วการเรียก query() ครั้งที่สอง (พร้อม resume) สามารถอ้างถึง "มัน" หรือ "ไฟล์ที่คุณอ่านไปเมื่อกี้" ได้โดยไม่ต้องอธิบายซ้ำ บทถอดความของเซสชันจะถูกเขียนไว้ในดิสก์ในเครื่องโดยค่าเริ่มต้น สำหรับการใช้งานจริงคุณสามารถเชื่อมต่อ adapter SessionStore ที่ใช้ S3, Redis หรือ Postgres รองรับ เพื่อให้เซสชันคงอยู่ได้แม้คอนเทนเนอร์รีสตาร์ท

รูปแบบการสร้างที่ 1: บอทรีวิวโค้ดใน CI

นี่คือกรณีใช้งานคลาสสิกของ "ระบบอัตโนมัติแบบ headless" ทุกครั้งที่มี pull request งาน CI job จะเช็คเอาต์แบรนช์นั้น รันเอเจนต์ที่อ่านไฟล์ที่ถูกเปลี่ยนแปลง และโพสต์ความเห็นรีวิว

โฟลว์การทำงาน:

1. เหตุการณ์ PR กระตุ้นเวิร์กโฟลว์ GitHub Actions (หรือ GitLab CI job)
2. runner เช็คเอาต์แบรนช์และรันสคริปต์รีวิวของคุณ
3. สคริปต์ของคุณเรียก query() ด้วยพรอมป์การรีวิว allowedTools: ["Read", "Glob", "Grep", "Bash"] และ permissionMode: "dontAsk"
4. Claude อ่าน diff ค้นหารูปแบบ และให้เหตุผลจากสิ่งที่พบ
5. ResultMessage มีข้อความรีวิว สคริปต์ของคุณจะโพสต์ข้อความนั้นไปยัง PR ผ่าน GitHub API

การเลือกออกแบบที่สำคัญคือการใช้ dontAsk ร่วมกับรายการทูลแบบอ่านอย่างเดียว เอเจนต์จะไม่สามารถเขียนไฟล์หรือเรียกเครือข่ายเกินกว่าที่ทูลอนุญาตไว้ ดังนั้น CI job ของคุณจะไม่มีทางเผลอ merge commit หรือเรียก API ภายนอกไปเอง ขีดจำกัด maxTurns (ตั้งไว้ใน options) จะจำกัดความลึกของเอเจนต์ เพื่อไม่ให้ลูปที่วนไม่หยุดกินโควตาไปเปล่า ๆ

สำหรับสถาปัตยกรรมของโฟลว์นี้แบบเป็นภาพประกอบ ดูไดอะแกรมด้านล่าง

ไปป์ไลน์รีวิวโค้ดที่เป็นระบบอัตโนมัติเต็มรูปแบบ เอเจนต์ SDK รันอยู่ภายในคอนเทนเนอร์ CI ด้วยรายการทูลแบบอ่านอย่างเดียว ผลการตรวจพบจะสตรีมกลับมาเป็น ResultMessage และโค้ดของคุณจะโพสต์มันเป็นความเห็นบน GitHub PR เอเจนต์จะไม่เขียนไฟล์ และไม่ออกจากคอนเทนเนอร์เลย

คุณสามารถขยายรูปแบบนี้ได้ด้วย hooks — ฟีเจอร์ของ SDK ที่กล่าวถึงในบทความ เจาะลึก Claude Code hooks ของเรา — เพื่อบันทึกการเรียกทูลทุกครั้งลงไฟล์ตรวจสอบ (audit file) ปิดกั้นเส้นทางไฟล์บางอย่างไม่ให้ถูกอ่าน หรือส่งข้อมูล telemetry แบบมีโครงสร้างควบคู่ไปกับการรีวิว

รูปแบบการสร้างที่ 2: เชนของทูลแบบมัลติเอเจนต์

ออปชัน agents ของ SDK ให้คุณกำหนดซับเอเจนต์ที่มีชื่อได้ โดยแต่ละตัวมี system prompt รายการทูล และสิทธิ์ของตัวเอง เอเจนต์หลักของคุณจะมอบงานให้กับพวกมันผ่านทูล Agent ที่มีในตัว ข้อความของซับเอเจนต์จะมีฟิลด์ parent_tool_use_id เพื่อให้คุณสามารถตรวจสอบได้ว่าผลลัพธ์แต่ละส่วนมาจากการมอบงานครั้งใด

ตัวอย่างที่ใช้ได้จริง: เชนเอเจนต์ตรวจสอบความปลอดภัย โดยซับเอเจนต์ code-scanner ค้นหาช่องโหว่ที่อาจเกิดขึ้นด้วย Grep และ Glob ซับเอเจนต์ dependency-checker รัน Bash เพื่อตรวจสอบข้อมูลเมทาดาต้าของแพ็กเกจของคุณ และเอเจนต์ผู้ประสานงานจะสังเคราะห์รายงานทั้งสองให้เป็นการตรวจสอบเดียวที่รวมกัน ซับเอเจนต์แต่ละตัวมีสิทธิ์การใช้ทูลเพียงเท่าที่จำเป็นต่อหน้าที่ของตน จำกัดผลกระทบหากซับเอเจนต์ตัวใดตัวหนึ่งสร้างคำสั่งที่เป็นอันตรายขึ้นมาจากการ hallucinate

เชนมัลติเอเจนต์ทำงานได้ดีกับงานที่แยกส่วนได้เป็นธรรมชาติ: หนึ่งเอเจนต์ต่อหนึ่งเรื่อง แต่ละตัวมีรายการทูลที่จำกัด ควบคุมโดยผู้ประสานงานที่ต้องการเพียง Read และ Agent เท่านั้น สำหรับมุมมองที่กว้างขึ้นว่าสถาปัตยกรรมมัลติเอเจนต์ทำงานร่วมกับฟีเจอร์ของ Claude Code อย่างความจำ CLAUDE.md และไฟล์ skill ได้อย่างไร ดูคู่มือ harness engineering ของเรา

รูปแบบการสร้างที่ 3: ไปป์ไลน์ระบบอัตโนมัติแบบ Headless

นอกเหนือจากการรีวิวโค้ด SDK ยังโดดเด่นในงานอัตโนมัติที่เกิดขึ้นซ้ำ ๆ ทุกชนิด ซึ่งเอเจนต์เป็นเพียงขั้นตอนหนึ่งในไปป์ไลน์ที่ใหญ่กว่า:

การตรวจสอบ dependency รายคืน cron job เรียก query() ด้วยพรอมป์ให้ตรวจหาแพ็กเกจที่ล้าสมัย รัน security scanner และสร้างรายงานที่มีโครงสร้าง ทูล Bash รัน npm audit หรือ pip check; Read ตรวจดูไฟล์ lock ResultMessage จะถูกส่งไปยังการแจ้งเตือนใน Slack

การแปลภาษาและ i18n เมื่อ PR ถูก merge เมื่อ PR ถูก merge webhook จะกระตุ้นเอเจนต์ที่อ่านไฟล์สตริงที่เปลี่ยนแปลงด้วย Glob และ Read สร้างเวอร์ชันที่แปลแล้วด้วย Write และเปิด PR ใหม่ผ่าน Bash (โดยรัน gh pr create)

การตรวจจับความผิดปกติในล็อก ป้อนล็อกล่าสุดเข้าไปในพรอมป์ query() เอเจนต์จะอ่านไฟล์คอนเท็กซ์เพิ่มเติมหากจำเป็น ให้เหตุผลจากล็อก และแสดงผลการตรวจพบที่มีโครงสร้าง ไม่จำเป็นต้องเขียนไฟล์ใด ๆ รายการทูลแบบอ่านอย่างเดียวก็เพียงพอแล้ว

การซิงค์เอกสาร หลังจาก PR ถูก merge เอเจนต์จะอ่านไฟล์ต้นทางที่อัปเดตแล้วและเขียนหน้าเอกสารที่เกี่ยวข้องใหม่ จากนั้น commit การเปลี่ยนแปลง permissionMode: "acceptEdits" จัดการการเขียนไฟล์โดยไม่ต้องขออนุญาต

จุดร่วมของทั้งหมดนี้คือ: query() เข้ามาแทนที่การเชื่อมต่อ LLM แบบสั่งทำเฉพาะกิจ คุณไม่ต้องเขียนลูปทูล ไม่ต้องจัดการหน้าต่างคอนเท็กซ์ด้วยมือ หรือแยกวิเคราะห์ผลลัพธ์จากโมเดลเพื่อตัดสินใจว่าจะรันอะไรต่อ เอเจนต์จัดการการประสานงานให้เอง คุณเพียงแค่ให้พรอมป์และรับผลลัพธ์ไปใช้

ตัวอย่างประกอบ: เอเจนต์แก้บั๊ก

quickstart ทางการแสดงรูปแบบนี้ได้อย่างชัดเจน (โค้ดด้านล่างเป็นไปตาม API ที่บันทึกไว้ — ตรวจสอบไวยากรณ์ที่แน่นอนในเอกสาร quickstart ของ Anthropic):

Python เพื่อประกอบความเข้าใจ (ตรวจสอบ API ที่แน่นอนในเอกสารทางการ):

# Illustrative — confirm exact import paths and option names in official docs
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def run_bug_fixer(file_path: str):
    async for message in query(
        prompt=f"Review {file_path} for bugs that would cause crashes. Fix any issues.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"Completed: {message.subtype}")

asyncio.run(run_bug_fixer("src/utils.py"))

TypeScript เพื่อประกอบความเข้าใจ (ตรวจสอบ API ที่แน่นอนในเอกสารทางการ):

// Illustrative — confirm exact import paths and option names in official docs
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review src/utils.ts for crash-causing bugs and fix them.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  }
  if (message.type === "result") console.log("Done:", message.subtype);
}

สิ่งที่เกิดขึ้นเมื่อรันโค้ดนี้: Claude จะอ่าน utils.py (หรือ .ts) โดยใช้ทูล Read ให้เหตุผลจากโค้ด ระบุกรณี edge case จากนั้นเรียก Edit เพื่อแทรกการจัดการแบบป้องกันความผิดพลาด คุณจะเห็นการให้เหตุผลและการเรียกทูลไหลผ่านมาในรูปของอ็อบเจ็กต์ AssistantMessage และ ResultMessage สุดท้ายจะแสดงว่าเสร็จสมบูรณ์ ลูปเอเจนต์ทั้งหมด — รวมถึงการอ่านไฟล์ใหม่อีกครั้งเพื่อยืนยันการแก้ไข — ถูกจัดการโดย SDK ทั้งหมด

นี่คือสิ่งที่ทำให้ SDK แตกต่างจากการเรียก Anthropic models API โดยตรง: คุณไม่ต้องสร้างชั้นการรันทูลขึ้นมาเอง Claude จะตัดสินใจว่าจะเรียก Read เมื่อไหร่ เรียกมัน รับเนื้อหาไฟล์กลับมา และให้เหตุผลต่อไป ลูปนี้ทำงานได้อย่างอิสระด้วยตัวเอง

สิทธิ์การใช้งาน แซนด์บ็อกซ์ และความปลอดภัยในการใช้งานจริง

การรันเอเจนต์อัตโนมัติในระบบจริงต้องคิดอย่างรอบคอบว่าพวกมันสามารถแตะต้องอะไรได้บ้าง SDK มีการควบคุมแบบเป็นชั้น ๆ หลายชั้น

การจำกัดขอบเขตทูล (Tool scoping) คือแนวป้องกันชั้นแรก ถ้าเอเจนต์ไม่จำเป็นต้องใช้ Bash ก็ไม่ต้องรวมมันไว้ใน allowedTools เอเจนต์ที่มีเพียง ["Read", "Glob", "Grep"] จะไม่สามารถแก้ไขไฟล์ รันคำสั่งเชลล์ หรือเรียกเครือข่ายได้ ไม่ว่าพรอมป์ของมันจะบอกอะไรก็ตาม

โหมดการอนุญาต เป็นแนวป้องกันชั้นที่สอง dontAsk ทำให้ทุกอย่างที่อยู่นอก allowedTools ถูกปฏิเสธอย่างเงียบ ๆ โดยไม่ต้องแจ้งเตือน สิ่งนี้สำคัญมากในสภาพแวดล้อมแบบ headless — พรอมป์ที่ค้างรอการตอบจากผู้ใช้จะทำให้ไปป์ไลน์ของคุณหยุดชะงัก

ออปชัน cwd จำกัดขอบเขตการเข้าถึงไฟล์ระบบของเอเจนต์ให้อยู่ในไดเรกทอรีที่กำหนดไว้เท่านั้น ในสภาพแวดล้อมแบบ multi-tenant ให้ส่งไดเรกทอรีการทำงานเฉพาะแต่ละเซสชัน เพื่อไม่ให้เอเจนต์จาก tenant ต่างกันสามารถอ่านไฟล์ของกันและกันได้

การแยก tenant ต้องใช้ขั้นตอนเพิ่มเติม: ตั้ง settingSources: [] เพื่อไม่ให้การตั้งค่าไฟล์ระบบรั่วไหลข้าม tenant ตั้ง CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 เพื่อป้องกัน auto-memory ไม่ให้โหลดขึ้นมา และกำหนด CLAUDE_CONFIG_DIR ไปยังพาธเฉพาะของแต่ละ tenant สิ่งเหล่านี้ถูกบันทึกไว้อย่างละเอียดในคู่มือการโฮสต์ของ Anthropic

การทำแซนด์บ็อกซ์แบบคอนเทนเนอร์ คือเปลือกชั้นนอกสุด สำหรับเอเจนต์ในระบบจริงที่ต้องใช้สิทธิ์ Bash ให้รัน SDK ภายในคอนเทนเนอร์ที่จำกัดการเชื่อมต่อเครือข่ายขาออกให้เหลือแค่โดเมนที่คุณอนุญาตไว้อย่างชัดเจน ผู้ให้บริการอย่าง Modal, E2B, Cloudflare Sandboxes, Fly Machines และ Vercel Sandbox ถูกกล่าวถึงในเอกสารของ Anthropic ว่าเป็นตัวเลือกสำหรับการติดตั้ง SDK แบบแซนด์บ็อกซ์

maxTurns จำกัดจำนวนรอบการไปกลับของการใช้ทูล ควบคุมทั้งค่าใช้จ่ายและลูปที่วนไม่หยุด ตั้งค่านี้ตามความซับซ้อนที่คาดไว้ของงานคุณ — การรีวิวไฟล์แบบง่ายอาจต้องใช้ 5–10 เทิร์น ส่วนการปรับโครงสร้างไฟล์หลายไฟล์ที่ซับซ้อนอาจต้องใช้ 30–50 เทิร์น

สำหรับทีมที่สร้าง hooks และโฟลว์การอนุญาตในระบบจริง คู่มือ Claude Code hooks ของเราครอบคลุมวงจรของ hook PreToolUse และ PostToolUse อย่างละเอียด รวมถึงวิธีเขียน callback ของ hook ที่บล็อก แปลง หรือบันทึกการเรียกทูลก่อนที่มันจะถูกรัน

MCP: การเชื่อมต่อเอเจนต์กับระบบภายนอก

SDK รองรับ Model Context Protocol (MCP) เต็มรูปแบบ ซึ่งให้คุณเชื่อมต่อเอเจนต์กับระบบภายนอกใดก็ได้ที่เปิด MCP server ไว้: ฐานข้อมูล, การทำงานอัตโนมัติของเบราว์เซอร์, Jira, Slack, GitHub และ server ที่ชุมชนสร้างขึ้นอีกหลายร้อยตัว

คุณกำหนดค่า MCP server ในออปชัน mcpServers — แต่ละรายการระบุคำสั่งที่จะรันและอาร์กิวเมนต์ที่เป็นตัวเลือก SDK จะเริ่มเซิร์ฟเวอร์เหล่านั้นเป็นซับโปรเซส และเอเจนต์สามารถเรียกทูลของพวกมันได้เหมือนกับที่เรียกทูลในตัว นี่คือวิธีที่คุณให้เอเจนต์รีวิวโค้ดสามารถเข้าถึงระบบติดตามปัญหา (issue tracker) ของคุณ หรือเชื่อมต่อเอเจนต์เอกสารกับฐานความรู้ของบริษัทคุณ

โมเดลการอนุญาตก็ใช้กับการเรียกทูลของ MCP ด้วยเช่นกัน — allowedTools สามารถรวมชื่อทูลของ MCP ได้ และ permissionMode ก็จะควบคุมสิ่งที่เกิดขึ้นกับทูลที่ไม่ได้ระบุไว้

ข้อควรระวังและปัญหาที่พบบ่อย

เซสชันจำกัดอยู่ในซับโปรเซสโดยค่าเริ่มต้น บทถอดความของเซสชันจะอยู่บนดิสก์ในเครื่องภายใต้ ~/.claude/projects/ ในการติดตั้งแบบคอนเทนเนอร์หรือแบบขยายแนวนอน หมายความว่าสถานะเซสชันจะสูญหายเมื่อรีสตาร์ทหรือถูกย้ายไปยังโหนดอื่น ใช้ adapter SessionStore สำหรับเซสชันใดก็ตามที่คุณต้องการเรียกกลับข้ามคอนเทนเนอร์

โมเดลซับโปรเซสมีผลต่อการใช้หน่วยความจำ เซสชันที่กำลังรันแต่ละอันคือซับโปรเซสที่แยกกัน การรันห้าสิบเซสชันพร้อมกันหมายความว่ามีโปรเซส Claude Code ห้าสิบตัว คำแนะนำทางการอยู่ที่ประมาณ 1 GiB RAM ต่อเอเจนต์เป็นจุดเริ่มต้น แต่การใช้หน่วยความจำในโลกจริงขึ้นอยู่กับความยาวของเซสชันและการทำงานของทูล กำหนดขนาดคอนเทนเนอร์ของคุณให้เหมาะสมและตั้ง maxTurns เพื่อจำกัดความลึกของเซสชัน

การขยายไปยังซับเอเจนต์จำนวนมากอาจเจอ rate limit ถ้าผู้ประสานงานของคุณมอบงานให้ซับเอเจนต์ยี่สิบตัวพร้อมกัน คุณมีแนวโน้มจะเจอ rate limit ของ API ของ Anthropic แบ่งการขยายที่กว้างออกเป็นแบทช์ และเพิ่มการหน่วงเวลาเล็กน้อยระหว่างการส่งงานแต่ละครั้ง

bypassPermissions ต้องใช้แซนด์บ็อกซ์จริง โหมดนี้ข้ามการตรวจสอบสิทธิ์ทั้งหมด มันถูกออกแบบมาสำหรับสภาพแวดล้อมที่ถูกควบคุมเต็มรูปแบบอย่างคอนเทนเนอร์ CI ที่คุณเป็นเจ้าของบริบทการรันทั้งหมด การใช้มันบนเครื่องของนักพัฒนา — ที่เอเจนต์มีสิทธิ์เข้าถึง SSH key, ข้อมูลรับรองคลาวด์ และพาธไฟล์ระบบใด ๆ ก็ตาม — เป็นความเสี่ยงด้านความปลอดภัย

TypeScript SDK มีไบนารี Claude Code รวมอยู่ในตัว; Python ไม่ต้องมีแยกต่างหาก แต่ทั้งสอง SDK ระบุเวอร์ชัน CLI ที่ตายตัวไว้ เมื่อคุณอัปเกรดแพ็กเกจ SDK คุณก็อัปเกรด CLI ที่อยู่ภายในไปด้วย ตรวจสอบ changelog ก่อนการอัปเกรดแบบไมเนอร์ — การเปลี่ยนแปลงพฤติกรรมแบบ breaking จะถูกประกาศไว้ที่นั่น

ข้อความพรอมป์และอินพุตของทูลจะไม่ถูกรวมอยู่ใน OTEL export โดยค่าเริ่มต้น นี่คือพฤติกรรมด้านความเป็นส่วนตัวที่ตั้งใจไว้ ถ้าคุณต้องการการติดตามระดับพรอมป์เพื่อการดีบัก คุณต้องเปิดใช้อย่างชัดเจนผ่านตัวแปรสภาพแวดล้อมที่บันทึกไว้ในคู่มือ observability ของ Anthropic

SDK เวอร์ชันเก่าอาจไม่รองรับโมเดลใหม่กว่า เอกสารของ Anthropic ระบุว่าโมเดลล่าสุดอาจต้องใช้ SDK เวอร์ชันล่าสุด เนื่องจากมีการเปลี่ยนแปลงใน thinking-parameter API ดังนั้น SDK เวอร์ชันล้าสมัยอาจใช้งานไม่ได้กับโมเดลใหม่ ควรตรวจสอบ changelog เสมอและระบุเวอร์ชันที่รู้ว่าใช้ได้ผลดีไว้เมื่อจะเริ่มใช้โมเดลใหม่

SDK กับ CLI: คุณต้องการอันไหน?

สำหรับนักพัฒนาส่วนใหญ่ คำตอบคือทั้งสองอย่าง — และนั่นเป็นสิ่งที่ถูกออกแบบมาให้เป็นแบบนั้น

CLI แบบโต้ตอบเป็นเครื่องมือที่เหมาะกับการพัฒนาในแต่ละวัน: การสำรวจโค้ดเบสที่ไม่คุ้นเคย การไล่แก้บั๊กที่ซับซ้อนแบบโต้ตอบ หรือการทำ refactor แบบครั้งเดียว SDK เป็นเครื่องมือที่เหมาะกับอะไรก็ตามที่ต้องรันโดยไม่มีมนุษย์อยู่ด้วย: CI, งานตามกำหนดเวลา, ฟีเจอร์ของแอปพลิเคชัน และไปป์ไลน์มัลติเอเจนต์

SDK และ CLI ไม่ได้เป็นผลิตภัณฑ์ที่แข่งกัน เวิร์กโฟลว์ที่คุณพัฒนาแบบโต้ตอบด้วย CLI สามารถแปลงไปเป็นระบบอัตโนมัติของ SDK ได้โดยตรง — ทูลเดียวกัน แนวคิดการอนุญาตเดียวกัน ความจำ CLAUDE.md และระบบ skill เดียวกัน เวิร์กโฟลว์รีวิวที่คุณต้นแบบด้วย claude ในเทอร์มินัลวันนี้ อาจกลายเป็นบอท CI ที่ขับเคลื่อนด้วย SDK ในวันพรุ่งนี้

สำหรับทีมที่ใช้เวอร์ชันเว็บของ Claude Code (ครอบคลุมในคู่มือ Claude Code บนเว็บของเรา) SDK เปิดโอกาสให้ผสมผสานเซสชันเว็บกับการจัดวางแบบเป็นโปรแกรม — เริ่มงานที่ใช้เวลานานจากเว็บ แล้วเชื่อมต่อกับมันแบบเป็นโปรแกรมจากแบ็กเอนด์ของคุณในภายหลัง

คำถามที่พบบ่อย

Claude Code SDK (Agent SDK) คืออะไรกันแน่? มันคือไลบรารี Python (claude-agent-sdk) และ TypeScript (@anthropic-ai/claude-agent-sdk) ที่เปิดให้ใช้เอนจินเอเจนต์เต็มรูปแบบของ Claude Code — ทูล สิทธิ์ การจัดการเซสชัน ซับเอเจนต์ MCP — เป็น async API ที่เขียนโปรแกรมได้ คุณเรียก query() ส่งพรอมป์และออปชัน แล้วรับสตรีมการทำงานของเอเจนต์กลับมาเป็นอ็อบเจ็กต์ข้อความที่มีชนิดกำหนดไว้

ผมต้องติดตั้ง Claude Code ก่อนถึงจะใช้ SDK ได้ไหม? สำหรับ TypeScript SDK ไม่จำเป็น — แพ็กเกจมีไบนารี Claude Code แบบเนทีฟรวมอยู่แล้ว สำหรับ Python SDK แพ็กเกจ claude-agent-sdk จัดการ dependency นี้ให้ คุณยังจำเป็นต้องมี Anthropic API key จาก Anthropic Console

ผมสามารถใช้ SDK กับโมเดลอื่นที่ไม่ใช่ Claude บน API ของ Anthropic ได้ไหม? ได้ SDK รองรับ Amazon Bedrock, Google Vertex AI, Microsoft Azure AI Foundry และ Claude Platform บน AWS ผ่านตัวแปรสภาพแวดล้อม คุณยังสามารถส่งคำขอผ่านพร็อกซีที่กำหนดเองได้ด้วยการตั้งค่า ANTHROPIC_BASE_URL

ผมจะใช้ SDK ใน GitHub Actions workflow ได้อย่างไร? เพิ่ม ANTHROPIC_API_KEY ของคุณเป็น GitHub Actions secret เช็คเอาต์แบรนช์ PR ในเวิร์กโฟลว์ของคุณ ติดตั้งแพ็กเกจ SDK และรันสคริปต์เอเจนต์ของคุณ ใช้ permissionMode: "dontAsk" ร่วมกับรายการ allowedTools แบบอ่านอย่างเดียว เพื่อไม่ให้เอเจนต์แก้ไขไฟล์ในสภาพแวดล้อม CI ของคุณ เอกสารของ Anthropic ยังครอบคลุมการรวมเข้ากับ GitHub Actions แบบเฉพาะทาง ซึ่งทำให้การรีวิว PR และการแบ่งประเภทปัญหาเป็นระบบอัตโนมัติได้โดยไม่ต้องเขียนโค้ด SDK เอง

Agent SDK แตกต่างจาก Managed Agents อย่างไร? Agent SDK คือไลบรารีที่รันลูปเอเจนต์ภายในโปรเซสและโครงสร้างพื้นฐานของคุณเอง Managed Agents คือ REST API แบบโฮสต์ ที่ Anthropic เป็นผู้รันเอเจนต์และแซนด์บ็อกซ์ให้ — คุณส่งเหตุการณ์และรับผลลัพธ์แบบสตรีมกลับมา SDK เหมาะกว่าสำหรับการทำต้นแบบในเครื่องและเอเจนต์ที่ทำงานตรงบนไฟล์ระบบของคุณ ส่วน Managed Agents เหมาะกว่าสำหรับการใช้งานจริงเมื่อคุณไม่ต้องการดูแลโครงสร้างพื้นฐานคอนเทนเนอร์เอง

ผมจะจำกัดสิ่งที่เอเจนต์เข้าถึงได้อย่างไร? ใช้ allowedTools เพื่อจำกัดว่าทูลใดใช้ได้ permissionMode: "dontAsk" เพื่อปฏิเสธทุกอย่างที่อยู่นอกรายการนั้น และ cwd เพื่อจำกัดขอบเขตการเข้าถึงไฟล์ระบบให้อยู่ในไดเรกทอรีที่กำหนด สำหรับการติดตั้งแบบ multi-tenant ให้ตั้ง settingSources: [] และ CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 เพิ่มเติมด้วย

SDK รองรับผลลัพธ์แบบสตรีมมิงไหม? รองรับ — ตัววนซ้ำแบบ async จาก query() สตรีมข้อความในเวลาจริง ถ้าคุณไม่ต้องการผลลัพธ์แบบสด (สำหรับงานพื้นหลังหรือไปป์ไลน์ CI ที่คุณสนใจแค่ผลลัพธ์สุดท้าย) เอกสารของ Anthropic อธิบายถึงโหมด single-turn ที่รวบรวมข้อความทั้งหมดก่อนที่จะส่งกลับ ดูStreaming vs. single-turn mode ในเอกสารทางการ

ผมสามารถรันเอเจนต์หลายตัวพร้อมกันได้ไหม? ได้ การเรียก query() แต่ละครั้งจะสร้างซับโปรเซสที่เป็นอิสระจากกัน คุณสามารถรัน N เซสชันพร้อมกันได้ — แต่แต่ละตัวเป็นโปรเซสแยกกัน ดังนั้นจัดสรรหน่วยความจำให้เหมาะสมและคำนึงถึง rate limit ของ API สำหรับการขยายซับเอเจนต์พร้อมกันจากผู้ประสานงานตัวเดียว ให้แบ่งการส่งงานเป็นแบทช์เพื่อหลีกเลี่ยงการเจอ rate limit

เกิดอะไรขึ้นถ้าเซสชันล่มระหว่างงาน? โดยค่าเริ่มต้น บทถอดความของเซสชันจะอยู่ในเครื่องของคอนเทนเนอร์และสูญหายเมื่อรีสตาร์ท เพื่อให้อยู่รอดผ่านการรีสตาร์ทได้ ให้กำหนดค่า adapter SessionStore (S3, Redis หรือ Postgres) และส่งไว้ใน options จากนั้นคุณจะสามารถเรียกกลับเซสชันด้วย session_id บนคอนเทนเนอร์ใหม่ได้

รันเอเจนต์โดยไม่ต้องตั้งค่าในเครื่อง

คุณค่าของ SDK คือการทำให้เป็นระบบอัตโนมัติ — แต่การจะทำให้ระบบอัตโนมัตินั้นทำงานได้ ต้องมีโครงสร้างพื้นฐานจริง: รันไทม์ Python หรือ Node, API key, กลยุทธ์คอนเทนเนอร์, การตัดสินใจเรื่องแซนด์บ็อกซ์ และเวลาที่ใช้ในการวางแผนสิทธิ์การใช้งานก่อนการดีพลอยจริงครั้งแรกของคุณ

สำหรับนักพัฒนาที่ต้องการทดลองไอเดียเอเจนต์โดยไม่มีค่าใช้จ่ายในการตั้งค่าเหล่านั้น Happycapy รันเอเจนต์แบบ Claude Code-style ตรงในเบราว์เซอร์ ไม่ต้องติดตั้งในเครื่อง ไม่ต้องจัดการซับโปรเซส และไม่ต้องจัดหาคอนเทนเนอร์ คุณแค่นำพรอมป์มา Happycapy จะจัดการสภาพแวดล้อมการรันให้ — พร้อมเข้าถึงโมเดลมากกว่า 150 ตัวและแซนด์บ็อกซ์คลาวด์ที่ปลอดภัย มันเป็นเส้นทางที่รวดเร็วสำหรับการทำต้นแบบพฤติกรรมเอเจนต์ที่คุณจะนำไปใช้งานจริงด้วย SDK ในภายหลัง

เริ่มใช้งานฟรีที่ happycapy.ai

คู่มือที่เกี่ยวข้อง

• Claude Code Hooks: The Power-User Guide to Automating Your Agent
• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• What Is Harness Engineering? Building Reliable AI Agent Harnesses (2026)