Claude Code SDK

 (docs.anthropic.com)
1 điểm bởi GN⁺ 2025-05-20 | 1 bình luận | Chia sẻ qua WhatsApp
  • Claude Agent SDK cho phép điều khiển việc thực thi công cụ, vòng lặp agent và quản lý ngữ cảnh của Claude Code từ mã Python·TypeScript, nhờ đó tự động hóa việc đọc tệp, chạy lệnh, tìm kiếm web và chỉnh sửa mã
  • Cung cấp sẵn các công cụ Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, giúp xử lý từ việc khám phá codebase đến câu hỏi xác nhận với người dùng mà không cần tầng thực thi riêng
  • Khi kết hợp hook, sub-agent, MCP, quyền và phiên, có thể xây dựng các cấu hình như nhật ký kiểm toán thay đổi tệp, sub-agent chuyên cho code review, tự động hóa trình duyệt dựa trên Playwright, hoặc agent phân tích chỉ đọc
  • Cài đặt bằng @anthropic-ai/claude-agent-sdk hoặc claude-agent-sdk; Python yêu cầu 3.10 trở lên, còn SDK TypeScript bao gồm binary Claude Code gốc theo nền tảng dưới dạng phụ thuộc tùy chọn
  • Khác với Anthropic Client SDK nơi phải tự triển khai vòng lặp công cụ, Agent SDK cung cấp thực thi công cụ tích hợp sẵn và chạy trong tiến trình cũng như hạ tầng của người dùng, không phải trên hạ tầng Anthropic như Managed Agents

Phạm vi của Claude Agent SDK

  • Claude Agent SDK cho phép sử dụng các công cụ, vòng lặp agent và quản lý ngữ cảnh vận hành Claude Code trong Python và TypeScript
  • Agent có thể đọc tệp, chạy lệnh, tìm kiếm web và chỉnh sửa mã
  • Có bao gồm thực thi công cụ tích hợp sẵn, nên người dùng không cần tự xây dựng một tầng thực thi công cụ riêng để agent bắt đầu làm việc
  • Ví dụ cơ bản cho phép các công cụ Read, Edit, Bash để tìm và sửa lỗi trong auth.py

Cài đặt và luồng xác thực

  • Cài đặt bằng gói theo từng ngôn ngữ
    • TypeScript: npm install @anthropic-ai/claude-agent-sdk
    • Python: pip install claude-agent-sdk
  • Gói Python yêu cầu Python 3.10 trở lên
    • Nếu gặp lỗi No matching distribution found for claude-agent-sdk, có thể trình thông dịch đang là phiên bản cũ hơn 3.10
    • Trên macOS hoặc Linux, kiểm tra bằng python3 --version; trên Windows, dùng py --version
  • SDK TypeScript bao gồm binary Claude Code gốc theo nền tảng như một phụ thuộc tùy chọn, nên không cần cài riêng Claude Code
  • API key được cấp tại Console và thiết lập qua biến môi trường ANTHROPIC_API_KEY
  • Cũng hỗ trợ xác thực với nhà cung cấp API bên thứ ba
    • Amazon Bedrock: đặt CLAUDE_CODE_USE_BEDROCK=1 rồi cấu hình thông tin xác thực AWS
    • Claude Platform on AWS: đặt CLAUDE_CODE_USE_ANTHROPIC_AWS=1, ANTHROPIC_AWS_WORKSPACE_ID rồi cấu hình thông tin xác thực AWS
    • Google Vertex AI: đặt CLAUDE_CODE_USE_VERTEX=1 rồi cấu hình thông tin xác thực Google Cloud
    • Microsoft Azure: đặt CLAUDE_CODE_USE_FOUNDRY=1 rồi cấu hình thông tin xác thực Azure
  • Anthropic không cho phép nhà phát triển bên thứ ba cung cấp đăng nhập claude.ai hoặc rate limit cho sản phẩm dựa trên Claude Agent SDK nếu chưa được phê duyệt trước

Công cụ mặc định và khả năng của agent

  • SDK cho phép điều khiển các tính năng chính của Claude Code từ trong mã
    • công cụ tích hợp sẵn
    • hook
    • sub-agent
    • MCP
    • quyền
    • phiên
  • Các công cụ tích hợp sẵn chính có vai trò như sau
    • Read: đọc tệp trong thư mục làm việc
    • Write: tạo tệp mới
    • Edit: áp dụng chỉnh sửa chính xác lên tệp hiện có
    • Bash: chạy lệnh terminal, script, tác vụ git
    • Monitor: giám sát script chạy nền và phản ứng theo sự kiện với từng dòng đầu ra
    • Glob: tìm tệp bằng mẫu như **/*.ts, src/**/*.py
    • Grep: tìm nội dung tệp bằng biểu thức chính quy
    • WebSearch: tìm thông tin mới nhất trên web
    • WebFetch: lấy và phân tích nội dung trang web
    • AskUserQuestion: đặt câu hỏi xác nhận cho người dùng bằng các lựa chọn trắc nghiệm
  • Agent ví dụ cho phép Read, Glob, Grep để tìm và tóm tắt chú thích TODO trong codebase

Hook, sub-agent và MCP

  • Hook thực thi mã người dùng tại các điểm chính trong vòng đời của agent
    • Có thể dùng hàm callback để kiểm tra, ghi log, chặn hoặc biến đổi hành vi của agent
    • Các hook khả dụng gồm PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit v.v.
    • Ví dụ phát hiện thao tác Edit|Write trong PostToolUse để ghi lại thay đổi tệp vào audit.log
  • Sub-agent là agent chuyên biệt xử lý các tác vụ con tập trung
    • Agent chính ủy quyền công việc và sub-agent trả về kết quả
    • Agent tùy biến được định nghĩa bằng mô tả, prompt và các công cụ sẽ dùng
    • Việc gọi sub-agent diễn ra thông qua công cụ Agent, nên để tự động phê duyệt thì cần thêm Agent vào allowedTools
    • Các thông điệp trong ngữ cảnh sub-agent có thể chứa trường parent_tool_use_id để theo dõi chúng thuộc lần chạy sub-agent nào
  • Model Context Protocol(MCP) có thể kết nối tới hệ thống bên ngoài như cơ sở dữ liệu, trình duyệt, API

Quản lý quyền và phiên

  • Cấu hình quyền giới hạn các công cụ mà agent có thể sử dụng
    • Có thể cho phép tác vụ an toàn, chặn tác vụ rủi ro và yêu cầu phê duyệt cho hành động nhạy cảm
    • Ví dụ chỉ phê duyệt trước Read, Glob, Grep để tạo một agent chỉ đọc phân tích mã nhưng không sửa đổi
  • Công cụ AskUserQuestion và prompt phê duyệt tương tác được dùng cùng nhau trong luồng xử lý đầu vào người dùng
  • Phiên duy trì ngữ cảnh qua nhiều lượt trao đổi
    • Claude ghi nhớ các tệp đã đọc, phần phân tích đã thực hiện và lịch sử hội thoại
    • Sau đó có thể tiếp tục cùng phiên đó hoặc fork để thử cách tiếp cận khác
    • Ví dụ lấy session_id ở truy vấn đầu tiên, rồi dùng resume=session_id ở truy vấn thứ hai để tiếp tục cùng ngữ cảnh

Hỗ trợ cấu hình Claude Code

  • SDK hỗ trợ cấu hình dựa trên hệ thống tệp của Claude Code
  • Với tùy chọn mặc định, nó tải cấu hình từ .claude/ trong thư mục làm việc và ~/.claude/
  • Để giới hạn nguồn cấu hình cần tải, dùng tùy chọn setting_sources trong Python hoặc settingSources trong TypeScript
  • Các tính năng và vị trí được hỗ trợ như sau
    • Skills: khả năng chuyên biệt mà Claude tự dùng hoặc gọi bằng /name, .claude/skills/*/SKILL.md
    • Commands: lệnh tùy chỉnh theo định dạng cũ, .claude/commands/*.md
    • Memory: ngữ cảnh dự án và chỉ dẫn, CLAUDE.md hoặc .claude/CLAUDE.md
    • Plugins: mở rộng skills, agents, hooks, MCP servers, cấu hình theo lập trình bằng tùy chọn plugins

Khác biệt với các công cụ Claude khác

  • Anthropic Client SDK cung cấp truy cập API trực tiếp, nơi người dùng gửi prompt và tự triển khai việc thực thi công cụ
  • Trong Agent SDK, Claude tự chủ xử lý công cụ
    • Với Client SDK, người dùng phải tự triển khai vòng lặp công cụ
    • Agent SDK cung cấp thực thi công cụ tích hợp sẵn cho Claude
  • Tiêu chí chọn theo mục đích sử dụng như sau
    • phát triển tương tác: CLI
    • pipeline CI/CD: SDK
    • ứng dụng tùy chỉnh: SDK
    • tác vụ một lần: CLI
    • tự động hóa production: SDK
  • Nhiều đội ngũ dùng CLI cho phát triển hằng ngày và SDK cho production, và workflow có thể chuyển trực tiếp qua lại giữa hai bên
  • Managed Agents là REST API được host, nơi Anthropic vận hành agent và sandbox
  • Agent SDK là thư viện chạy vòng lặp agent bên trong tiến trình của người dùng
    • vị trí thực thi: Agent SDK chạy trong tiến trình và hạ tầng của người dùng, Managed Agents chạy trên hạ tầng do Anthropic quản lý
    • giao diện: Agent SDK là thư viện Python hoặc TypeScript, Managed Agents là REST API
    • đối tượng thao tác: Agent SDK làm việc với tệp trên hạ tầng người dùng, Managed Agents làm việc với sandbox được quản lý theo từng phiên
    • trạng thái phiên: Agent SDK dùng JSONL trên hệ thống tệp, Managed Agents dùng event log do Anthropic host
    • công cụ tùy chỉnh: Agent SDK dùng hàm Python hoặc TypeScript trong tiến trình, Managed Agents để Claude kích hoạt công cụ rồi người dùng trả về kết quả thực thi
    • trường hợp phù hợp: Agent SDK phù hợp cho prototype cục bộ và agent cần truy cập trực tiếp hệ thống tệp·dịch vụ; Managed Agents phù hợp cho agent production không vận hành sandbox hay hạ tầng phiên, cũng như các phiên chạy dài và bất đồng bộ
  • Lộ trình phổ biến là tạo prototype cục bộ bằng Agent SDK, rồi chuyển sang Managed Agents ở production

Changelog, báo lỗi và branding

  • Có thể theo dõi cập nhật SDK, sửa lỗi và tính năng mới trong changelog của từng kho lưu trữ
  • Có thể báo lỗi hoặc issue trên GitHub
  • Khi đối tác tích hợp Claude Agent SDK, việc dùng thương hiệu Claude là tùy chọn
    • được phép: “Claude Agent”, “Claude”, “Powered by Claude”
    • bị cấm: “Claude Code”, “Claude Code Agent”, ASCII art thương hiệu Claude Code hoặc các yếu tố hình ảnh mô phỏng Claude Code
    • sản phẩm phải giữ branding riêng và không được trông giống Claude Code hay sản phẩm của Anthropic
  • Việc sử dụng Claude Agent SDK chịu sự điều chỉnh của Anthropic’s Commercial Terms of Service
    • ngoại lệ là khi một số thành phần hoặc phụ thuộc chỉ rõ giấy phép khác trong tệp LICENSE của chính thành phần đó

Bài viết liên quan

1 bình luận

 
GN⁺ 2025-05-20
Ý kiến trên Hacker News

  • Hướng đi mà Claude Code nhắm tới khớp chính xác với điều tôi muốn ở một công cụ lập trình kiểu agent, và triết lý kiểu “Unix tool” cũng rất hay
    Tôi đã dùng từ giai đoạn public preview ban đầu và khi đó đã thấy được hướng đi này. Theo tôi, trạng thái cuối cùng lý tưởng của coding agent là khi bạn đưa cho nó một yêu cầu tính năng như Jira ticket, nó sẽ xem xét rồi tạo ra một PR để bạn phản hồi. Theo nghĩa đó, các công cụ lấy trình soạn thảo cục bộ làm trung tâm như Cursor hay Windsurf gần như là ngõ cụt, vì chúng không thể chạy trong CI. Nếu bạn định chỉnh trang codebase để phù hợp với AI bằng rule, MCP, v.v., thì nên nhắm tới công nghệ có thể tiến tới cả việc dùng ở chế độ headless. Claude Code có thể dễ dàng được dùng như một phần của tự động hóa thông qua các công cụ, nên giờ nó đã trở thành lựa chọn mặc định khi tôi nghĩ tới coding agent, và gói npm Codex cũng tương tự. Tuy vậy, tôi đang làm công việc hỗ trợ các công ty chỉnh trang codebase để phù hợp với việc dùng agent, nên có thể tôi hơi thiên về các công cụ dễ cấu hình

    • Tôi khó đồng ý với “trạng thái cuối cùng lý tưởng” đó. Điều tôi muốn là ngồi trong một căn phòng bao quanh bởi nhiều màn hình, nơi các AI agent đang lập trình, thiết kế và kiểm thử, còn tôi ở giữa chỉ đạo phương hướng và áp dụng gu của mình
      Tôi kỳ vọng mọi thứ diễn ra bằng hội thoại, và 99% thời gian không cần chạm vào bàn phím
    • Tôi không nghĩ vậy. Trạng thái cuối cùng “lý tưởng” của coding agent là một coding agent tự do và mã nguồn mở chạy trên máy tính của tôi hoặc trên máy tôi muốn
      Hãy thử tưởng tượng bạn phải trả tiền mỗi lần chạy các lệnh như ls, ps, kill trong terminal thì thật vô lý. Với LLM cũng vậy. Tôi không có ý cấm các LLM độc quyền, nhưng công cụ chính mà các hacker thời nay nên dùng vẫn phải là công cụ tự do và mã nguồn mở
    • Anthropic hôm nay cũng công bố bản beta của một tính năng theo hướng tương tự: https://docs.anthropic.com/en/docs/claude-code/github-action...
    • Tôi cũng đã thử làm việc này với Cursor và MCP. Sau khoảng một ngày thì bị giới hạn mức sử dụng và bị đẩy xuống model chậm nhất, ngốc nhất
      Tôi cũng thử với Claude nhưng nhanh chóng dùng hết hạn mức. Trường hợp PR đạt mức có thể “cho đi luôn” chỉ khoảng 25%, và nhiều khi việc tự làm cho đúng còn nhanh hơn là lần mò xem AI đã làm hỏng ở đâu
    • Tôi hiểu ý về trạng thái có thể đưa yêu cầu tính năng rồi nhận lại một PR để review, nhưng như vậy thì phần bào mòn tâm hồn nhất trong công việc phần mềm là Jira ticket lại là thứ duy nhất còn sót lại, nghe thật u ám

  • Claude Code là cách dùng LLM cho lập trình mà tôi thích nhất
    Nhưng thứ thực sự cần là một phiên bản mã nguồn mở cho phép chuyển qua bất kỳ model nào, đồng thời so sánh câu trả lời từ nhiều model. Aider hay các lựa chọn khác không mang lại cảm giác dễ dùng như Claude Code. Từ góc nhìn của Anthropic thì họ sẽ không muốn điều đó vì hào lũy cạnh tranh sẽ biến mất, nhưng từ góc nhìn người dùng, tôi chỉ muốn dùng model tốt nhất mà không bị trói vào một hệ sinh thái cụ thể. Có lẽ đây là điều mà các nhà cung cấp model LLM sợ nhất

    • OpenAI Codex có lẽ là lựa chọn thay thế gần nhất. Nó là mã nguồn mở và có thể dùng model từ bất kỳ nhà cung cấp nào
      Hiện tại nó chưa tốt bằng Claude Code, nhưng có vẻ sẽ sớm bắt kịp. https://github.com/openai/codex/tree/main
    • Dự án OpenCode có thể phù hợp với mối quan tâm này: https://github.com/opencode-ai/opencode
      Nó vẫn đang được phát triển, nhưng trông khá hứa hẹn
    • Tôi tò mò không biết Claude Code làm tốt hơn Aider ở điểm nào
    • Gần đây tôi đã tự quảng bá hơi nhiều, nhưng nếu xem các bình luận trước của tôi thì sẽ thấy tôi có một dịch vụ viết bằng Go. Nó nhắm chính xác vào nhu cầu này
    • Tôi đồng ý, nhưng chẳng phải các model khác cũng phải được huấn luyện để biết cách làm việc với MCP server sao? Hay điều đó không thành vấn đề?

  • Aider từ lâu đã hỗ trợ Python và shell scripting [0]
    Gần đây, trong quá trình bổ sung hỗ trợ cho 130 ngôn ngữ lập trình mới, họ cũng làm một screencast dùng Aider để viết Bash script tại chỗ [1]. Điều này có thể cho bạn cảm nhận về mức độ mạnh mẽ của cách tiếp cận đó.
    [0] https://aider.chat/docs/scripting.html
    [1] https://aider.chat/docs/recordings/tree-sitter-language-pack...

    • Tôi rất thích Aider. MCP cũng sắp được hỗ trợ, và tôi đang thử nhánh phát triển
      Khi đó, bạn có thể dùng model mình tin tưởng để phát triển từ đầu đến cuối thông qua PR, ticket, v.v.
    • Tôi tò mò không biết có thể làm Aider gần với Claude Code đến mức nào. Trải nghiệm người dùng của Claude Code rất tốt, nhưng tôi không dùng vì tôi thích Gemini 2.5 Pro hơn
      Tôi không thực sự muốn nó tự commit, chủ yếu là tôi thích cảm giác sử dụng của Claude Code
    • Aider có thể trở nên tốt hơn rất nhiều nếu có một workflow GitHub Actions được trau chuốt
      Chỉ cần thêm một file vào repository là có thể trò chuyện với bất kỳ model nào thông qua issue là được

  • Nhóm Claude Code đã nói chi tiết hơn tại đây: http://latent.space/p/claude-code
    Chỉ cần lướt qua phần transcript cũng được, nhưng cá nhân tôi thấy ấn tượng ở chỗ nhân viên Anthropic dù dùng Claude không giới hạn thì chi phí sử dụng trung bình vẫn chỉ khoảng 6 USD/ngày, họ xem Claude Code headless như một tiện ích “Linux” có thể dùng ở bất kỳ đâu trong CI, họ xem nó như một nền tảng có thể được người dùng mở rộng, các tính năng sandboxing, branching và planning nằm trong lộ trình sắp tới, và họ xem Sonnet 3.7 là một mô hình agent bền bỉ

    • Trong link có nói rằng trong số các kỹ sư nội bộ của Anthropic có cả người đã chi hơn 1.000 USD trong một ngày
      Tôi tò mò không biết mức chi tiêu P50, P75 và P95 theo từng nhân viên là bao nhiêu
    • Có thể là do tôi dùng sai, nhưng cứ dùng Claude Code 2 tiếng là rất dễ bay hơn 20 USD
      Nó quá đắt cho các dự án cá nhân nên tôi đã ngừng dùng
    • Gần đây tôi thực sự rất thích nghe podcast latent space. Tôi nghĩ rất hiếm người hay podcast nào vừa giữ được tỷ lệ tín hiệu trên nhiễu cao mà vẫn có sản lượng tổng thể ở mức này
      Thật đáng kinh ngạc khi trong nửa năm hay vài năm qua, dù vẫn phát triển nhiều công việc kinh doanh, lượng và giá trị của các sản phẩm công khai của họ vẫn tiếp tục tăng. Mong là người khác cũng có thể tìm ra đường cong năng suất tương tự. Họ có chia sẻ sơ bộ về điều gì phù hợp, nhưng không dễ để tái tạo. Tôi chỉ nghĩ đến simonw và gwern
    • Tôi tò mò không biết podcast đó trung lập đến mức nào, hay chỉ đơn giản là một màn quảng bá mang tính bán hàng cho sản phẩm này

  • Nếu tôi làm một AI code assistant, thì chuyện khóa chặt vào một nhà cung cấp foundation model sẽ là điều cuối cùng tôi muốn làm
    Để sản phẩm này thành công thì phải giả định rằng hiệu năng mô hình hiện đã chạm trần, mọi foundation model đang hội tụ về gần như cùng một mức hiệu năng và năng lực, và các đơn vị tích hợp sẽ lựa chọn chỉ dựa trên những tiện ích nhỏ như SDK quen thuộc

    • Ngoài command và argument ra thì không có nhiều phần bị khóa chặt. Chỉ là input và output thôi
      Chỉ cần thay cái khác vào hoặc bọc bằng một wrapper là được. Ở đây không có quá nhiều thứ phức tạp
    • Ở thời điểm hiện tại, Claude Code chính là điểm khác biệt phần mềm trong mảng coding dạng agent
      Tôi đang làm một thứ liên quan đến AI code assistant, và đã bắt đầu hack cách tích hợp Claude Code. Đây là thứ đầu tiên chúng tôi muốn build trên nó. Còn quá sớm để lo về lock-in, và vì cần thứ tốt nhất nên chúng tôi sẽ chỉ build xoay quanh thứ tốt nhất

  • Claude Code vốn đã có thể dùng ở chế độ không tương tác, nên có thể tích hợp vào các ứng dụng khác giống như những tiện ích dòng lệnh Unix khác
    SDK này hiện có vẻ chỉ hỗ trợ dùng qua dòng lệnh, vậy chẳng phải nó giống hệt thứ đã có sẵn rồi sao? Tôi không rõ thực sự có gì mới. Tôi đã bỏ sót điều gì à?

    • Tôi cũng không biết. Theo tôi thấy thì gần như chẳng ai nói về điểm này, nên khá lạ

  • Cũng đề xuất Codebuff(https://www.codebuff.com/). Đây cũng là một CLI code assistant rất tốt tương tự Claude Code và có thể tiết kiệm khá nhiều chi phí token
    Tôi không liên quan gì đến dự án này, chỉ là người dùng thôi

  • Trong điều khoản có ghi rằng “không được sử dụng để phát triển sản phẩm hoặc dịch vụ cạnh tranh với dịch vụ, phát triển hoặc huấn luyện thuật toán hay mô hình trí tuệ nhân tạo hoặc máy học, hoặc để bán lại dịch vụ”
    Tôi không hiểu rốt cuộc sản phẩm hoặc dịch vụ phần mềm không cạnh tranh với trí tuệ phổ quát là cái gì. Họ đang bán trí tuệ nhưng lại gắn một điều khoản pháp lý mà nếu diễn giải chặt chẽ thì thành ra cấm dùng cho bất cứ đâu. Có phải nó mơ hồ đến mức không thể thực thi không? Nếu không được dùng để cạnh tranh với trí tuệ phổ quát thì làm sao có thể sở hữu đầu ra? Có phải kiểu “chẳng ai quan tâm đến điều khoản pháp lý” không? Nếu chẳng ai quan tâm thì tại sao lại đặt lệnh cấm bao trùm lên việc dùng dịch vụ? Tôi có quá nhiều câu hỏi, như liệu có phải người dùng đang chấp nhận cả trách nhiệm thua kiện chỉ để nhận được các kết quả này không

    • Cứ để luật sư viết tùy ý là ra thế này
    • Họ đã đổi “artificial” thành “general”, nên ý nghĩa dĩ nhiên thay đổi

  • Lock-in mô hình là một bất lợi lớn trong sử dụng. Nếu ai đó tung ra mô hình tốt nhất mới nhất mà bạn đã đầu tư vào hạ tầng này rồi, bạn sẽ bị mắc kẹt
    Ngay cả khi sau này họ mở ra, rất có thể mô hình đó đã được huấn luyện đặc biệt để hợp với CLI kia nên các mô hình khác sẽ không hoạt động tốt. Nhìn Codex CLI là thấy, vẫn có thể dùng Gemini 2.5 Pro nhưng nó hay dừng ngẫu nhiên hoặc thất bại hơn nhiều so với model của OpenAI

  • GitHub Action mới đúng là tính năng tôi đang tìm: https://docs.anthropic.com/en/docs/claude-code/github-action...
    Nhưng có vẻ không có cách dùng nó với gói Max của Claude Code. Theo tôi thấy thì nó chỉ nhận API key