Xây Dựng Agent Tự Động Với Claude Code SDK: Hướng Dẫn Thực Tế Cho Developer

Xây dựng Agent tự động với Claude Code SDK: Hướng dẫn thực tế cho Developer

Claude Code SDK — tên gọi chính thức là Agent SDK — là một thư viện Python và TypeScript cho phép bạn điều khiển toàn bộ engine agentic của Claude Code bằng mã lệnh: không cần terminal, không cần con người ngồi trước bàn phím, chỉ cần ứng dụng của bạn gọi hàm query() không đồng bộ (async) và nhận về từng bước làm việc của agent theo dạng stream. Nếu bạn đã dùng Claude Code theo cách tương tác, SDK mang lại đúng vòng lặp đọc file / sửa code / chạy lệnh đó dưới dạng một thư viện có thể kết hợp, nhúng vào pipeline CI, bot review code, bộ điều phối đa agent (multi-agent orchestrator), hoặc bất kỳ dịch vụ backend nào.

Agent SDK là gì — và tại sao nó tồn tại

Claude Code được biết đến rộng rãi như một công cụ terminal. Bạn nhập một prompt, agent suy luận trên codebase của bạn, gọi các tool có sẵn (Read, Edit, Bash, Grep, và các tool khác), và trả kết quả về cho bạn. Nhưng ngay khi bạn muốn tự động hóa vòng lặp đó — kích hoạt review trên mỗi pull request, phân tán công việc cho nhiều sub-agent chuyên biệt, hoặc xây dựng một sản phẩm dựa trên nó — thì CLI tương tác không còn là abstraction phù hợp. Bạn cần một thư viện.

Agent SDK lấp đầy khoảng trống đó. Theo tài liệu chính thức của Anthropic, nó cung cấp "cùng những tool, agent loop, và context management đang vận hành Claude Code, có thể lập trình bằng Python và TypeScript." Đây không phải ngôn ngữ marketing — đó chính là kiến trúc thực tế. SDK khởi chạy binary CLI của Claude Code như một subprocess được quản lý, giao tiếp với nó qua stdio, và trả về mọi thứ dưới dạng một luồng (stream) bất đồng bộ các message object có kiểu dữ liệu rõ ràng mà code của bạn có thể tiêu thụ và phản hồi.

Sự khác biệt này quan trọng vì vài lý do:

Cùng một engine, giao diện khác nhau. Khi bạn chuyển từ CLI sang SDK, bạn không chuyển sang một công cụ kém hơn hoặc đơn giản hơn. SDK kế thừa mọi khả năng có trong CLI — kết nối MCP server, hooks lifecycle, skill file, bộ nhớ CLAUDE.md, phân công sub-agent, và toàn bộ danh sách tool.

SDK thực hiện việc gọi tool thay cho bạn. Nếu bạn dùng Anthropic Client SDK (gói anthropic Python/JS ở tầng thấp hơn) và muốn Claude gọi tool, bạn phải tự triển khai vòng lặp tool: gọi API, phát hiện phản hồi tool use, thực thi tool, đưa kết quả trở lại, lặp lại đến khi Claude dừng. Agent SDK gói toàn bộ vòng lặp đó vào một câu lệnh duy nhất async for message in query(...) — Claude tự quyết định gọi tool nào, thực thi chúng trong subprocess của nó, và tiếp tục lặp cho đến khi hoàn thành nhiệm vụ. Bạn chỉ cần tiêu thụ stream đó.

Được thiết kế để chạy headless. Các permission prompt của CLI — "cho phép chạy lệnh bash này?" — sẽ chặn để chờ input từ con người. SDK thay thế chúng bằng một tùy chọn permissionMode và một tập các permission mode — ví dụ acceptEdits để tự động chấp thuận các chỉnh sửa file và bypassPermissions để chạy mọi thứ không cần xác nhận trong môi trường CI sandbox — cùng với một callback phê duyệt theo lập trình cho các luồng xử lý tùy chỉnh. Tên chính xác của các mode và hành vi của chúng được ghi trong tài liệu tham khảo SDK của Anthropic (hãy kiểm tra danh sách hiện hành), nhưng hiệu quả vẫn như vậy: quy trình tự động hóa của bạn không bao giờ bị treo để chờ một lần nhấn phím.

Cùng một engine Claude Code, hai giao diện: CLI tương tác cho công việc có con người tham gia, Agent SDK cho tự động hóa lập trình, headless, nơi ứng dụng của bạn kiểm soát prompt và một permission mode thay thế hộp thoại xác nhận.

Cài đặt SDK

Anthropic phát hành hai package:

• TypeScript: @anthropic-ai/claude-agent-sdk (npm)
• Python: claude-agent-sdk (pip; yêu cầu Python 3.10+)

Package TypeScript đóng gói sẵn một binary Claude Code native cho platform của bạn, nên không cần cài CLI riêng. Việc xác thực thực hiện qua biến môi trường ANTHROPIC_API_KEY lấy từ Anthropic Console. SDK cũng hỗ trợ Amazon Bedrock, Google Vertex AI, và Microsoft Azure AI Foundry — xem tài liệu của Anthropic để biết các mẫu biến môi trường liên quan.

Các khái niệm cốt lõi

Hiểu bốn khái niệm sau sẽ bao quát phần lớn cách sử dụng SDK trong thực tế.

1. Hàm query() và luồng message bất đồng bộ

Mọi tương tác với SDK bắt đầu từ query(). Bạn truyền vào một chuỗi prompt và một object options; đổi lại bạn nhận được một iterator bất đồng bộ phát ra các message object có kiểu dữ liệu trong khi agent làm việc. Vòng lặp kết thúc khi agent hoàn tất hoặc gặp lỗi.

Các message bạn nhận được bao gồm:

• AssistantMessage — văn bản suy luận của Claude và mô tả các lần gọi tool
• ToolResultMessage — kết quả của mỗi lần thực thi tool
• ResultMessage — kết quả cuối cùng, với một trường subtype cho biết thành công hay thất bại
• SystemMessage — các sự kiện lifecycle của session (subtype init mang theo session_id)

Trong hầu hết mã sản xuất, bạn lọc theo ResultMessage để lấy output cuối cùng và có thể log các block AssistantMessage để theo dấu những gì agent đã làm.

2. Tool và allowedTools

Danh sách tool có sẵn của SDK ánh xạ trực tiếp tới khả năng của Claude Code:

Tùy chọn allowedTools phê duyệt trước một tập con các tool này, cho phép agent gọi chúng mà không cần thêm bất kỳ lớp kiểm soát nào. Một agent audit chỉ đọc có thể chỉ liệt kê ["Read", "Glob", "Grep"]; một hệ thống tự động hóa đầy đủ có thể bao gồm ["Read", "Edit", "Bash", "Glob", "Grep"].

3. Permission Mode

Permission mode kiểm soát điều gì xảy ra khi agent muốn dùng một tool không được phê duyệt trước trong allowedTools:

• acceptEdits — tự động chấp thuận các chỉnh sửa file và các thao tác filesystem thông thường; hỏi xác nhận cho mọi thứ khác. Phù hợp nhất cho quy trình phát triển đáng tin cậy.
• dontAsk — âm thầm từ chối bất cứ thứ gì không nằm trong allowedTools. Phù hợp nhất cho các agent headless bị khóa chặt.
• bypassPermissions — chạy mọi tool mà không kiểm soát. Chỉ dùng trong môi trường sandbox.

SDK cũng cung cấp một callback phê duyệt theo lập trình để bạn triển khai logic phê duyệt tùy chỉnh hoàn toàn, và danh sách tên mode có thể mở rộng theo thời gian — hãy tham khảo tài liệu SDK của Anthropic để biết danh sách chính thức, hiện hành và hành vi chính xác của từng mode. Trong CI, bạn hầu như luôn sẽ dùng một cấu hình được giới hạn chặt, mặc định từ chối, hoặc bypassPermissions trong một container sandbox mà bạn kiểm soát.

4. Session, Resumption, và Context

Mỗi lần gọi query() tạo (hoặc tiếp tục) một session. session_id của session xuất hiện trong SystemMessage đầu tiên với subtype === "init". Bạn có thể lấy nó và truyền vào resume: sessionId trong lần gọi tiếp theo để tiếp tục chính xác từ nơi cuộc hội thoại đã dừng lại — cùng những lần đọc file, cùng lịch sử suy luận, cùng context window.

Đây là cách bạn xây dựng agent nhiều lượt (multi-turn): một lần gọi query() phân tích một module, lấy session_id, và lần gọi query() thứ hai (với resume) tham chiếu "nó" hoặc "file bạn vừa đọc" mà không cần giải thích lại. Theo mặc định, transcript của session được ghi vào đĩa cục bộ; đối với production, bạn có thể gắn một adapter SessionStore dựa trên S3, Redis, hoặc Postgres để session tồn tại qua các lần khởi động lại container.

Mẫu xây dựng 1: Bot review code trong CI

Đây là trường hợp sử dụng "tự động hóa headless" tiêu biểu. Trên mỗi pull request, một job CI checkout branch, chạy một agent đọc các file đã thay đổi, và đăng một bình luận review.

Luồng xử lý:

1. Sự kiện PR kích hoạt một workflow GitHub Actions (hoặc job GitLab CI).
2. Runner checkout branch và chạy script review của bạn.
3. Script của bạn gọi query() với một prompt review, allowedTools: ["Read", "Glob", "Grep", "Bash"], và permissionMode: "dontAsk".
4. Claude đọc diff, tìm kiếm các pattern, suy luận trên các phát hiện.
5. ResultMessage mang nội dung review; script của bạn đăng nó lên PR qua GitHub API.

Lựa chọn thiết kế quan trọng là dùng dontAsk với danh sách tool chỉ đọc. Agent không thể ghi file hoặc gọi network vượt ngoài những gì các tool cho phép, nên job CI của bạn không thể vô tình merge commit hoặc gọi API bên ngoài. Một giới hạn maxTurns (đặt trong options) giới hạn độ sâu của agent để các vòng lặp chạy vô hạn không tiêu tốn ngân sách.

Xem sơ đồ dưới đây để biết kiến trúc minh họa của luồng này.

Một pipeline review code hoàn toàn tự động. Agent SDK chạy trong một container CI với danh sách tool chỉ đọc; các phát hiện được stream trở lại dưới dạng ResultMessage và code của bạn đăng chúng thành một bình luận PR trên GitHub. Agent không bao giờ ghi file, không bao giờ rời khỏi container.

Bạn có thể mở rộng mẫu này với hooks — một tính năng SDK được đề cập trong bài phân tích sâu về Claude Code hooks của chúng tôi — để log mỗi lần gọi tool vào một file audit, chặn việc đọc một số đường dẫn file cụ thể, hoặc phát ra telemetry có cấu trúc cùng với review.

Mẫu xây dựng 2: Chuỗi công cụ đa agent

Tùy chọn agents của SDK cho phép bạn định nghĩa các sub-agent có tên, mỗi sub-agent có system prompt, danh sách tool, và permission riêng. Agent chính của bạn phân công công việc cho chúng qua tool Agent có sẵn. Các message của sub-agent bao gồm một trường parent_tool_use_id để bạn có thể theo dấu chính xác lần phân công nào tạo ra phần output nào.

Một ví dụ thực tế: một chuỗi agent audit an ninh, trong đó một sub-agent code-scanner tìm các lỗ hổng tiềm ẩn bằng Grep và Glob, một sub-agent dependency-checker chạy Bash để truy vấn metadata package của bạn, và một agent điều phối tổng hợp cả hai báo cáo thành một audit thống nhất. Mỗi sub-agent chỉ có quyền truy cập tool tối thiểu cần cho vai trò của nó, hạn chế phạm vi ảnh hưởng nếu một sub-agent tạo ra một lệnh nguy hiểm do "hallucinate".

Chuỗi đa agent hoạt động tốt cho các nhiệm vụ phân rã một cách tự nhiên: mỗi agent phụ trách một mối quan tâm, mỗi agent có danh sách tool giới hạn chặt, được điều phối bởi một coordinator chỉ cần Read và Agent. Để có góc nhìn rộng hơn về cách các kiến trúc đa agent kết hợp với các tính năng của Claude Code như bộ nhớ CLAUDE.md và skill file, xem hướng dẫn về kỹ thuật harness của chúng tôi.

Mẫu xây dựng 3: Pipeline tự động hóa headless

Ngoài review code, SDK còn tỏa sáng trong mọi quy trình tự động hóa định kỳ, nơi agent là một bước trong một pipeline lớn hơn:

Audit dependency hàng đêm. Một cron job gọi query() với một prompt để kiểm tra các package lỗi thời, chạy các trình quét an ninh, và tạo ra một báo cáo có cấu trúc. Tool Bash chạy npm audit hoặc pip check; Read kiểm tra các lock file. ResultMessage được đưa vào một thông báo Slack.

Dịch thuật và i18n khi merge PR. Khi một PR được merge, một webhook kích hoạt một agent đọc các file chuỗi văn bản đã thay đổi bằng Glob và Read, tạo ra các phiên bản đã dịch bằng Write, và mở một PR mới qua Bash (chạy gh pr create).

Phát hiện bất thường trong log. Đưa output log gần đây vào một prompt query(). Agent đọc thêm các file context nếu cần, suy luận trên log, và phát ra một phát hiện có cấu trúc. Không cần ghi file; một danh sách tool chỉ đọc là đủ.

Đồng bộ tài liệu. Sau khi PR được merge, một agent đọc các file source đã cập nhật và viết lại các trang tài liệu tương ứng, sau đó commit các thay đổi. permissionMode: "acceptEdits" xử lý việc ghi file mà không cần xác nhận.

Điểm chung: query() thay thế một tích hợp LLM tự viết tay. Bạn không cần triển khai vòng lặp tool, tự quản lý context window, hoặc parse output của model để quyết định thực thi gì tiếp theo. Agent xử lý việc điều phối; bạn chỉ cần cung cấp prompt và tiêu thụ kết quả.

Một ví dụ minh họa hoàn chỉnh: Agent sửa lỗi (bug)

Quickstart chính thức minh họa mẫu này một cách rõ ràng (code dưới đây theo API được ghi trong tài liệu — hãy kiểm tra cú pháp chính xác trong tài liệu quickstart của Anthropic):

Python minh họa (kiểm tra API chính xác trong tài liệu chính thức):

# 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 minh họa (kiểm tra API chính xác trong tài liệu chính thức):

// 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);
}

Điều gì xảy ra khi đoạn code này chạy: Claude đọc utils.py (hoặc .ts) bằng tool Read, suy luận trên code, xác định các trường hợp biên (edge case), sau đó gọi Edit để chèn thêm xử lý phòng thủ (defensive handling). Bạn thấy quá trình suy luận và các lần gọi tool được stream qua dưới dạng object AssistantMessage; ResultMessage cuối cùng báo hiệu hoàn thành. Toàn bộ vòng lặp agent — bao gồm cả việc đọc lại file để xác nhận chỉnh sửa — được SDK quản lý.

Đây là điều làm SDK khác biệt so với việc gọi trực tiếp API model của Anthropic: bạn không triển khai tầng thực thi tool. Claude quyết định khi nào gọi Read, gọi nó, nhận lại nội dung file, và tiếp tục suy luận. Vòng lặp này là tự động.

Permission, Sandboxing, và An toàn cho Production

Chạy các agent tự động trong production đòi hỏi phải suy nghĩ kỹ về những gì chúng có thể tiếp cận. SDK cung cấp nhiều lớp kiểm soát.

Giới hạn tool là hàng phòng thủ đầu tiên. Nếu một agent không cần Bash, đừng đưa nó vào allowedTools. Một agent chỉ có ["Read", "Glob", "Grep"] không thể sửa file, chạy lệnh shell, hoặc gọi network bất kể prompt của nó nói gì.

Permission mode cung cấp lớp kiểm soát thứ hai. dontAsk đảm bảo mọi thứ nằm ngoài allowedTools đều bị âm thầm từ chối thay vì hỏi xác nhận. Điều này cực kỳ quan trọng trong môi trường headless — một prompt bị treo chờ input từ người dùng sẽ làm nghẽn pipeline của bạn.

Tùy chọn cwd giới hạn quyền truy cập filesystem của agent vào một thư mục cụ thể. Trong môi trường multi-tenant, hãy truyền một thư mục làm việc riêng cho mỗi session để agent của các tenant khác nhau không thể đọc file của nhau.

Cách ly tenant yêu cầu thêm các bước: đặt settingSources: [] để không có cấu hình filesystem nào bị rò rỉ giữa các tenant; đặt CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 để ngăn auto-memory tải lên; chỉ định CLAUDE_CONFIG_DIR tới một đường dẫn riêng cho mỗi tenant. Những điều này được ghi chi tiết trong hướng dẫn hosting của Anthropic.

Container sandboxing là lớp vỏ ngoài cùng. Đối với các agent production cần quyền truy cập Bash, hãy chạy SDK trong một container với network egress bị giới hạn chỉ đến các domain bạn cho phép rõ ràng. Các nhà cung cấp như Modal, E2B, Cloudflare Sandboxes, Fly Machines, và Vercel Sandbox được nhắc đến trong tài liệu của Anthropic như các lựa chọn cho việc triển khai SDK sandbox.

maxTurns giới hạn số lượt round trip sử dụng tool, giới hạn cả chi phí và các vòng lặp chạy vô hạn. Đặt giá trị này dựa trên độ phức tạp dự kiến của nhiệm vụ — một review đọc file đơn giản có thể cần 5–10 lượt; một tái cấu trúc (refactor) phức tạp nhiều file có thể cần 30–50 lượt.

Đối với các team xây dựng hooks và luồng permission cho production, hướng dẫn về Claude Code hooks của chúng tôi trình bày chi tiết lifecycle của hook PreToolUse và PostToolUse, bao gồm cách viết các hook callback để chặn, biến đổi, hoặc log các lần gọi tool trước khi chúng thực thi.

MCP: Kết nối Agent với các hệ thống bên ngoài

SDK hỗ trợ đầy đủ Model Context Protocol (MCP), cho phép bạn kết nối agent của mình với bất kỳ hệ thống bên ngoài nào cung cấp một MCP server: database, tự động hóa browser, Jira, Slack, GitHub, và hàng trăm server do cộng đồng xây dựng.

Bạn cấu hình các MCP server trong tùy chọn mcpServers — mỗi mục chỉ định một lệnh để chạy và các tham số tùy chọn. SDK khởi chạy các server đó dưới dạng subprocess, và agent có thể gọi tool của chúng theo cách giống hệt như gọi các tool có sẵn. Đây là cách bạn cho một agent review code quyền truy cập vào issue tracker của bạn, hoặc kết nối một agent tài liệu với knowledge base của công ty bạn.

Mô hình permission cũng áp dụng cho các lần gọi tool MCP — allowedTools có thể bao gồm tên các tool MCP, và permissionMode chi phối điều gì xảy ra với các tool không được liệt kê.

Những điểm cần lưu ý và lỗi thường gặp

Session mặc định chỉ tồn tại cục bộ trong subprocess. Transcript của session nằm trên đĩa cục bộ của host tại ~/.claude/projects/. Trong các triển khai containerized hoặc scale ngang, điều này có nghĩa là trạng thái session bị mất khi khởi động lại hoặc chuyển node. Sử dụng một adapter SessionStore cho bất kỳ session nào bạn cần tiếp tục qua các container.

Mô hình subprocess có ảnh hưởng đến bộ nhớ. Mỗi session đang chạy là một subprocess riêng biệt. Chạy năm mươi session đồng thời nghĩa là năm mươi tiến trình Claude Code. Hướng dẫn chính thức là khoảng 1 GiB RAM cho mỗi agent như một điểm khởi đầu, nhưng mức sử dụng bộ nhớ thực tế phụ thuộc vào độ dài session và hoạt động của tool. Hãy cấp phát kích thước container phù hợp và đặt maxTurns để giới hạn độ sâu session.

Số lượng sub-agent phân tán lớn sẽ gặp giới hạn tần suất (rate limit). Nếu orchestrator của bạn phân công cho hai mươi sub-agent đồng thời, bạn rất có thể sẽ chạm giới hạn tần suất của API Anthropic. Hãy chia các lần phân tán lớn thành các batch và thêm một khoảng chờ nhỏ giữa các lần dispatch.

bypassPermissions yêu cầu một sandbox thực sự. Mode này bỏ qua toàn bộ các lớp kiểm soát permission. Nó được thiết kế cho các môi trường hoàn toàn được kiểm soát như container CI, nơi bạn sở hữu toàn bộ execution context. Sử dụng nó trên máy của một developer — nơi agent có quyền truy cập SSH key, credential cloud, và các đường dẫn filesystem tùy ý — là một rủi ro an ninh.

SDK TypeScript đóng gói sẵn binary Claude Code; Python không cần cài riêng. Nhưng cả hai SDK đều gắn với một phiên bản CLI cụ thể. Khi bạn upgrade package SDK, bạn cũng upgrade CLI phía dưới. Hãy xem changelog trước các bản nâng cấp phiên bản nhỏ — các thay đổi hành vi gây breaking sẽ được thông báo ở đó.

Nội dung prompt và input của tool không được đưa vào OTEL export theo mặc định. Đây là hành vi bảo mật thông tin có chủ đích. Nếu bạn cần trace ở cấp độ prompt để debug, bạn phải chủ động opt-in qua các biến môi trường được ghi trong hướng dẫn observability của Anthropic.

Các phiên bản SDK cũ có thể không hỗ trợ các model mới hơn. Tài liệu của Anthropic ghi rằng các model gần đây có thể yêu cầu một phiên bản SDK gần đây do các thay đổi trong API tham số thinking, nên một SDK lỗi thời có thể thất bại khi dùng với một model mới. Luôn kiểm tra changelog và cố định (pin) một phiên bản đã biết là ổn định khi áp dụng model mới.

SDK so với CLI: Bạn cần cái nào?

Đối với hầu hết developer, câu trả lời là cả hai — và đó là điều được thiết kế có chủ đích.

CLI tương tác là công cụ phù hợp cho công việc phát triển hàng ngày: khám phá một codebase chưa quen thuộc, xử lý một bug phức tạp theo cách tương tác, hoặc chạy một lần refactor đơn lẻ. SDK là công cụ phù hợp cho bất cứ thứ gì cần chạy mà không có con người hiện diện: CI, các tác vụ theo lịch, các tính năng ứng dụng, và các pipeline đa agent.

SDK và CLI không phải là các sản phẩm cạnh tranh nhau. Các workflow bạn phát triển một cách tương tác với CLI chuyển đổi trực tiếp thành tự động hóa SDK — cùng tool, cùng khái niệm permission, cùng bộ nhớ CLAUDE.md và hệ thống skill. Một workflow review bạn prototype với claude trên terminal hôm nay sẽ trở thành một bot CI được cung cấp bởi SDK ngày mai.

Đối với các team sử dụng phiên bản web của Claude Code (được đề cập trong hướng dẫn Claude Code trên web của chúng tôi), SDK mở ra cánh cửa để kết hợp các session web với việc điều phối theo lập trình — khởi động một nhiệm vụ dài hạn từ web, sau đó tương tác với nó theo lập trình từ backend của bạn.

Câu hỏi thường gặp

Claude Code SDK (Agent SDK) chính xác là gì? Đó là một thư viện Python (claude-agent-sdk) và TypeScript (@anthropic-ai/claude-agent-sdk) cung cấp toàn bộ engine agentic của Claude Code — tool, permission, quản lý session, sub-agent, MCP — dưới dạng một API bất đồng bộ có thể lập trình. Bạn gọi query(), truyền vào một prompt và các option, và nhận về stream công việc của agent dưới dạng các message object có kiểu dữ liệu.

Tôi cần cài Claude Code để dùng SDK không? Với SDK TypeScript, không — package đã đóng gói sẵn một binary Claude Code native. Với SDK Python, package claude-agent-sdk xử lý dependency đó. Bạn vẫn cần một API key của Anthropic từ Anthropic Console.

Tôi có thể dùng SDK với các model khác ngoài Claude trên API của Anthropic không? Có. SDK hỗ trợ Amazon Bedrock, Google Vertex AI, Microsoft Azure AI Foundry, và Claude Platform trên AWS qua các biến môi trường. Bạn cũng có thể định tuyến request qua một proxy tùy chỉnh bằng cách đặt ANTHROPIC_BASE_URL.

Làm sao để dùng SDK trong một workflow GitHub Actions? Thêm ANTHROPIC_API_KEY của bạn như một GitHub Actions secret, checkout branch PR trong workflow của bạn, cài đặt package SDK, và chạy script agent của bạn. Sử dụng permissionMode: "dontAsk" với danh sách allowedTools chỉ đọc để agent không thể sửa file trong môi trường CI của bạn. Tài liệu của Anthropic cũng đề cập đến một tích hợp GitHub Actions chuyên dụng tự động hóa việc review PR và phân loại issue mà không cần viết code SDK tùy chỉnh.

Sự khác biệt giữa Agent SDK và Managed Agents là gì? Agent SDK là một thư viện chạy agent loop trong tiến trình và hạ tầng của riêng bạn. Managed Agents là một REST API được hosting, nơi Anthropic chạy agent và sandbox — bạn gửi event và nhận stream kết quả trở lại. SDK phù hợp hơn cho prototyping cục bộ và các agent làm việc trực tiếp trên filesystem của bạn; Managed Agents phù hợp hơn cho production khi bạn không muốn vận hành hạ tầng container.

Làm sao để giới hạn những gì agent có thể truy cập? Sử dụng allowedTools để giới hạn tool nào khả dụng, permissionMode: "dontAsk" để từ chối bất cứ thứ gì ngoài danh sách đó, và cwd để giới hạn quyền truy cập filesystem vào một thư mục cụ thể. Đối với các triển khai multi-tenant, hãy thêm đặt settingSources: [] và CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

SDK có hỗ trợ streaming output không? Có — iterator bất đồng bộ từ query() stream các message theo thời gian thực. Nếu bạn không cần output trực tiếp (cho các job chạy nền hoặc pipeline CI nơi bạn chỉ quan tâm đến kết quả cuối cùng), tài liệu của Anthropic mô tả một single-turn mode thu thập tất cả message trước khi trả về. Xem Streaming vs. single-turn mode trong tài liệu chính thức.

Tôi có thể chạy nhiều agent song song không? Có. Mỗi lần gọi query() khởi chạy một subprocess độc lập. Bạn có thể chạy N session đồng thời — nhưng mỗi session là một tiến trình riêng biệt, nên hãy cấp phát bộ nhớ tương ứng và cần lưu tâm đến giới hạn tần suất API. Đối với các lần phân tán sub-agent đồng thời từ một orchestrator duy nhất, hãy chia thành batch để tránh chạm giới hạn tần suất.

Điều gì xảy ra nếu session bị crash giữa nhiệm vụ? Theo mặc định, transcript của session chỉ tồn tại cục bộ trong container và bị mất khi khởi động lại. Để tồn tại qua các lần khởi động lại, hãy cấu hình một adapter SessionStore (S3, Redis, hoặc Postgres) và truyền nó vào options. Sau đó bạn có thể tiếp tục session bằng session_id trên một container mới.

Chạy Agent mà không cần cài đặt cục bộ

Giá trị cốt lõi của SDK là tự động hóa — nhưng để chạy được tự động hóa đó cần có hạ tầng thực sự: một runtime Python hoặc Node, một API key, một chiến lược container, một quyết định về sandboxing, và thời gian dành cho việc lập mô hình permission trước lần triển khai production đầu tiên của bạn.

Đối với các developer muốn lặp nhanh trên các ý tưởng agent mà không cần gánh chi phí cài đặt đó, Happycapy chạy các agent theo phong cách Claude Code trực tiếp trên browser. Không có cài đặt cục bộ, không quản lý subprocess, và không cấp phát container. Bạn cung cấp một prompt, Happycapy xử lý môi trường thực thi — với quyền truy cập vào hơn 150 model và một sandbox cloud an toàn. Đây là một lối đi nhanh để prototype hành vi agent mà bạn sẽ sau này đưa lên production bằng SDK.

Bắt đầu miễn phí tại happycapy.ai

Hướng dẫn liên quan

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