claude-agent-sdk-python: xây agent Claude bằng Python — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về anthropics/claude-agent-sdk-python — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: claude-agent-sdk-python: xây agent Claude bằng Python — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
claude-agent-sdk-python là thư viện Python để xây ứng dụng dùng Claude Agent thông qua Claude Code. Bạn có thể gửi câu hỏi, cho agent đọc/ghi tệp, chạy công cụ, dùng MCP server và kiểm soát hành vi bằng hook. Cài đặt khá đơn giản vì Claude Code CLI đã được đóng gói sẵn trong package.
Repo này là SDK Python giúp bạn đưa Claude Agent vào chương trình của mình. Thay vì chỉ trò chuyện thủ công, bạn có thể viết một ứng dụng Python để gửi yêu cầu, nhận phản hồi theo luồng, cho agent làm việc với tệp hoặc công cụ, rồi tự xử lý kết quả.
Thư viện phù hợp với lập trình viên muốn xây trợ lý nội bộ, công cụ tự động hóa, bot xử lý mã nguồn hoặc ứng dụng có khả năng gọi công cụ riêng. Người mới cần biết Python và cách chạy chương trình bất đồng bộ ở mức cơ bản.
Điểm đáng giá nhất là Claude Code CLI được đóng gói tự động cùng package, nên bạn không phải cài riêng CLI trong trường hợp thông thường. SDK cũng hỗ trợ custom tool chạy ngay trong cùng tiến trình Python, hook để chặn hoặc kiểm tra lệnh, cùng cả MCP server nội bộ và MCP server bên ngoài.
anthropics/claude-agent-sdk-python
SDK Python giúp bạn tích hợp Claude Agent vào ứng dụng, gọi công cụ, tạo MCP server nội bộ và kiểm soát agent bằng hook.
I.claude-agent-sdk-python làm được gì
A.Gửi yêu cầu đến Claude bằng Python
Hàm query() cho phép ứng dụng gửi prompt đến Claude Code và nhận về một AsyncIterator của các message. Bạn có thể dùng cách này cho các tác vụ đơn giản như hỏi đáp, phân tích nội dung hoặc yêu cầu agent thực hiện một công việc trong thư mục dự án.
Vì kết quả được trả theo luồng, chương trình có thể xử lý từng message thay vì phải chờ toàn bộ tác vụ hoàn thành. Đây là nền tảng phù hợp cho giao diện dòng lệnh, ứng dụng nội bộ hoặc dịch vụ cần hiển thị tiến độ.
B.Cấu hình số lượt và vai trò của agent
ClaudeAgentOptions cho phép đặt system prompt, giới hạn số lượt xử lý bằng max_turns, chọn thư mục làm việc và cấu hình quyền. Bạn có thể định hướng agent thành trợ lý viết mã, bot kiểm tra tệp hoặc một tác nhân chuyên xử lý quy trình cụ thể.
SDK cũng hỗ trợ system prompt tùy chỉnh và cơ chế snapshot. Nếu prompt được ghi lại cho session, prompt mới có thể chưa có hiệu lực cho đến khi session được compact hoặc bắt đầu session mới. Khi cần xây lại prompt ở mỗi request, README minh họa cách đặt snapshot thành False.
C.Cho agent dùng bộ công cụ của Claude Code
Theo README, Claude có quyền truy cập bộ công cụ Claude Code như Read, Write, Edit, Bash và các công cụ khác. allowed_tools là danh sách cho phép tự động chấp thuận, không phải danh sách loại bỏ công cụ khỏi agent.
Điểm này hữu ích khi bạn muốn giảm số lần hỏi quyền cho những thao tác đã kiểm soát. Nếu muốn cấm một công cụ cụ thể, cần dùng disallowed_tools. Những công cụ không nằm trong danh sách tự động chấp thuận sẽ được xử lý tiếp theo permission_mode và can_use_tool.
D.Tạo custom tool ngay trong ứng dụng
Bạn có thể viết một hàm Python, đánh dấu bằng decorator @tool, rồi đưa hàm đó vào SDK MCP server bằng create_sdk_mcp_server(). Claude có thể gọi công cụ này khi cần, còn công cụ chạy trực tiếp trong cùng tiến trình với ứng dụng.
Cách này loại bỏ việc quản lý subprocess riêng, giảm chi phí giao tiếp liên tiến trình và đơn giản hóa triển khai. Type hint của Python cũng giúp phần định nghĩa công cụ dễ đọc và dễ kiểm tra hơn.
E.Kết hợp MCP nội bộ và MCP bên ngoài
Một cấu hình có thể chứa cả SDK MCP server chạy trong tiến trình và MCP server bên ngoài chạy qua stdio. Bạn có thể giữ công cụ đơn giản ở trong ứng dụng Python, đồng thời kết nối các server đã có sẵn bằng subprocess.
Điều này phù hợp khi hệ thống đã có một số MCP server độc lập nhưng bạn muốn bổ sung nhanh các hàm nội bộ mà không phải tạo thêm một tiến trình riêng.
F.Kiểm soát agent bằng hook
Hook là hàm Python được Claude Code gọi tại các điểm nhất định trong vòng lặp agent. Hook không phải là công cụ của Claude; nó là cơ chế để ứng dụng kiểm tra và phản hồi một cách quyết định.
Ví dụ trong README dùng PreToolUse để xem lệnh Bash trước khi chạy. Nếu lệnh chứa mẫu bị cấm, hook trả về quyết định deny. Bạn có thể dùng cách này để chặn một số lệnh nguy hiểm hoặc áp quy tắc riêng cho môi trường làm việc.
G.Nhận diện lỗi có cấu trúc
SDK cung cấp nhiều loại lỗi như CLINotFoundError, CLIConnectionError, ProcessError, ResultError và CLIJSONDecodeError. Chương trình có thể bắt từng loại để đưa ra thông báo phù hợp thay vì chỉ hiện một lỗi chung.
Các kiểu message và content block cũng được định nghĩa rõ, gồm AssistantMessage, UserMessage, SystemMessage, ResultMessage, TextBlock, ToolUseBlock và ToolResultBlock.
II.Cần chuẩn bị gì
- Python phiên bản 3.10 trở lên. Đây là yêu cầu được ghi trong README và
pyproject.toml. - Một môi trường có thể cài package Python bằng
pip. - Claude Agent SDK package. Claude Code CLI được tự động đóng gói cùng package nên thông thường không cần cài riêng.
- Nếu muốn dùng CLI cài toàn hệ thống hoặc một phiên bản CLI cụ thể, bạn có thể cài CLI riêng và truyền đường dẫn bằng
ClaudeAgentOptions(cli_path="/path/to/claude"). - Nếu xây ứng dụng có custom tool, hook hoặc MCP server, bạn cần có kiến thức Python đủ để viết hàm bất đồng bộ và cấu hình
ClaudeAgentOptions.
Tư liệu được cung cấp không nêu chi tiết về API key, cách đăng nhập tài khoản, chi phí sử dụng hay cấu hình GPU. Bạn không nên tự suy đoán các mục này từ README. Hãy kiểm tra tài liệu Claude Agent SDK và chính sách của dịch vụ trước khi đưa ứng dụng vào sử dụng thật.
README có đề cập workflow phát hành tạo wheel cho macOS, Linux và Windows. Tuy vậy, README không cung cấp hướng dẫn Windows riêng cho người dùng cuối. Trên Windows, bạn nên kiểm tra package và môi trường Python thực tế nếu gặp lỗi cài đặt hoặc chạy CLI.
III.Cài đặt từng bước
- Chuẩn bị PythonKiểm tra bạn đang dùng Python 3.10 trở lên
- Tải mã nguồn tùy chọnClone repo nếu muốn xem ví dụ và mã nguồn
- Cài packageCài claude-agent-sdk bằng pip
- Tạo chương trình thửGọi query() và in phản hồi
- Chạy thửXác nhận chương trình nhận được message từ Claude
A.Chuẩn bị Python
Mở Terminal, PowerShell hoặc cửa sổ dòng lệnh trong môi trường bạn muốn dùng. Trước tiên, kiểm tra phiên bản Python. README chỉ yêu cầu Python 3.10 trở lên.
python --versionNếu máy có nhiều bản Python, hãy chắc chắn lệnh python đang trỏ đến bản từ 3.10 trở lên. README không cung cấp lệnh tạo virtual environment, nên bạn có thể dùng môi trường Python hiện có hoặc quy trình quản lý môi trường mà bạn đang quen dùng.
B.Clone repo để xem mã nguồn và ví dụ
Bạn không bắt buộc phải clone repo để cài package từ PyPI. Tuy nhiên, clone repo giúp bạn xem examples/, tests/, mã nguồn trong src/ và file pyproject.toml.
git clone https://github.com/anthropics/claude-agent-sdk-python.git
cd claude-agent-sdk-pythonNếu chỉ muốn dùng thư viện, bạn có thể bỏ qua bước này. Nếu đã clone, hãy chạy lệnh cd tại thư mục chứa repo vừa tải về. Người mới thường gặp lỗi vì mở terminal ở thư mục khác hoặc gõ sai tên thư mục.
C.Cài package Python
Cài package theo đúng lệnh trong README:
pip install claude-agent-sdkLệnh này cài package claude-agent-sdk. Claude Code CLI được đóng gói tự động nên thông thường không cần cài CLI riêng.
Nếu bạn muốn dùng một CLI cài toàn hệ thống, README đưa ra lệnh sau:
curl -fsSL https://claude.ai/install.sh | bashLệnh này được README nêu như lựa chọn thay thế, không phải bước bắt buộc trong cách cài mặc định. Chỉ chạy lệnh cài CLI riêng khi bạn hiểu môi trường của mình và thực sự cần dùng bản CLI bên ngoài package.
D.Tạo chương trình tối thiểu
Tạo một file Python trong thư mục làm việc của bạn, sau đó đặt nội dung theo ví dụ Quick Start trong README:
import anyio
from claude_agent_sdk import query
async def main():
async for message in query(prompt="What is 2 + 2?"):
print(message)
anyio.run(main)Đoạn chương trình định nghĩa hàm bất đồng bộ main(), gọi query() và in từng message nhận được. anyio.run(main) khởi chạy hàm bất đồng bộ từ chương trình Python thông thường.
README không đặt tên file cụ thể cho ví dụ Quick Start. Bạn có thể lưu đoạn mã vào file Python do mình chọn trong thư mục dự án, rồi chạy bằng lệnh Python tương ứng với môi trường của bạn.
E.Thử cấu hình quyền và thư mục làm việc
Khi muốn agent làm việc với một dự án cụ thể, truyền cwd vào ClaudeAgentOptions:
from pathlib import Path
options = ClaudeAgentOptions(
cwd="/path/to/project" # or Path("/path/to/project")
)cwd có thể là chuỗi đường dẫn hoặc đối tượng Path. Hãy thay /path/to/project bằng thư mục thật của bạn. Không nên trỏ vào thư mục chứa dữ liệu nhạy cảm nếu bạn chưa hiểu các công cụ mà agent được phép sử dụng.
Để tự động chấp thuận một số công cụ và thao tác chỉnh sửa tệp, README minh họa:
options = ClaudeAgentOptions(
allowed_tools=["Read", "Write", "Bash"], # auto-approve these tools
permission_mode='acceptEdits' # auto-accept file edits
)
async for message in query(
prompt="Create a hello.py file",
options=options
):
# Process tool use and results
passallowed_tools không làm biến mất các công cụ khác. Nó chỉ tự động chấp thuận những tên được liệt kê. permission_mode='acceptEdits' khiến việc chỉnh sửa tệp được tự động chấp thuận, vì vậy bạn cần dùng thật cẩn thận.
Không tự động chấp thuận Read, Write hoặc Bash trong thư mục có dữ liệu quan trọng nếu bạn chưa kiểm tra quyền. Hãy giới hạn cwd và xem kỹ prompt trước khi cho agent chạy lệnh hoặc sửa tệp.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra tối thiểu là chạy chương trình Quick Start sau khi cài package. Nếu import thành công và chương trình in ra các message trả về cho câu hỏi What is 2 + 2?, phần cài đặt cơ bản đã hoạt động.
Bạn cũng có thể kiểm tra cách lọc message bằng ví dụ trong README:
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
# Simple query
async for message in query(prompt="Hello Claude"):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text)Kết quả mong đợi là nội dung văn bản nằm trong TextBlock được in ra. README không đưa ra một chuỗi kết quả cố định cho lời chào, nên bạn chỉ cần xác nhận rằng chương trình nhận được phản hồi và không kết thúc bằng lỗi kết nối, lỗi tiến trình hoặc lỗi phân tích JSON.
Nếu gặp lỗi, hãy bắt các loại lỗi SDK cung cấp để biết nguyên nhân cụ thể. CLINotFoundError liên quan đến việc không tìm thấy CLI, ProcessError có mã thoát của tiến trình, còn CLIJSONDecodeError báo vấn đề phân tích phản hồi.
V.Dùng vào việc thật
A.Nhân viên văn phòng tạo bản nháp từ thư mục tài liệu
Một nhân viên có thể đặt tài liệu trong một thư mục riêng, cấu hình cwd trỏ vào đó rồi yêu cầu agent đọc và tóm tắt. Prompt mẫu là Read the documents in this project and create a concise summary. Bạn nên chỉ cho phép các công cụ cần thiết và kiểm tra tệp đầu ra trước khi gửi cho người khác.
Kết quả nhận được là các message từ agent. Nếu cần lấy riêng phần chữ, lọc AssistantMessage và TextBlock như ví dụ trong README.
B.Chủ shop tạo công cụ tra cứu đơn hàng nội bộ
Chủ shop hoặc nhóm vận hành có thể viết một custom tool Python như get_order_status, nhận mã đơn rồi trả về nội dung dạng text. Đăng ký hàm bằng @tool, tạo server bằng create_sdk_mcp_server(), sau đó đặt server vào mcp_servers.
Prompt mẫu là Check the status of order A123 and explain what I should tell the customer. Agent có thể gọi công cụ khi cần và trả lời theo dữ liệu mà hàm cung cấp. Cách này phù hợp khi dữ liệu tra cứu đã có trong ứng dụng Python và bạn không muốn dựng thêm một MCP server riêng.
C.Lập trình viên kiểm tra và sửa một dự án
Dev có thể đặt cwd vào repo cần xử lý, rồi gửi yêu cầu như Inspect the project, identify the failing test, and suggest a fix. Nếu muốn agent thực sự tạo file, cần cấu hình quyền phù hợp và xem xét Write hoặc Edit trước khi chạy.
Nếu cần cho phép một số công cụ không hỏi lại, dùng allowed_tools. Nếu không muốn agent chạy một số lệnh, kết hợp disallowed_tools hoặc hook PreToolUse để kiểm tra trước khi thực thi.
D.Nhóm phát triển chặn lệnh Bash nguy hiểm
Nhóm có thể viết hook kiểm tra tool_name và tool_input["command"]. README minh họa việc chặn mọi lệnh chứa mẫu foo.sh, trả về permissionDecision: "deny" cùng lý do cụ thể.
Prompt mẫu là Run the bash command: ./foo.sh --help. Hook sẽ chặn lệnh này. Với prompt Run the bash command: echo 'Hello from hooks example!', hook cho phép tiếp tục theo ví dụ. Đây là lớp kiểm soát xác định, hữu ích khi bạn muốn bảo vệ quy tắc nội bộ khỏi việc agent diễn giải sai.
Hãy để agent làm phần suy luận, nhưng giữ quyền quyết định cuối cùng ở những công cụ có thể thay đổi dữ liệu.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Python thấp hơn phiên bản yêu cầu
Package yêu cầu Python 3.10 trở lên. Nếu import hoặc cài đặt thất bại trên bản Python cũ, hãy chuyển sang Python phù hợp rồi chạy lại lệnh cài package trong đúng môi trường đó.
B.Không tìm thấy Claude Code CLI
SDK mặc định dùng CLI được bundle cùng package, nhưng README vẫn cung cấp lỗi CLINotFoundError. Kiểm tra package đã cài đúng môi trường Python chưa. Nếu bạn chủ động dùng CLI bên ngoài, xác nhận đường dẫn truyền vào ClaudeAgentOptions(cli_path=...) là đường dẫn thật.
C.Agent tự ý sửa tệp hoặc chạy lệnh
allowed_tools chỉ tự động chấp thuận công cụ được liệt kê, còn permission_mode='acceptEdits' có thể tự động chấp nhận chỉnh sửa. Hãy bỏ cấu hình tự động chấp thuận khi chưa cần, giới hạn cwd, và dùng hook để chặn mẫu lệnh không được phép.
D.Không thấy nội dung chữ trong message
query() trả về nhiều loại message, không phải message nào cũng có text trực tiếp. Hãy kiểm tra AssistantMessage, sau đó duyệt message.content và lọc TextBlock như ví dụ README.
E.Prompt hệ thống mới chưa có hiệu lực
README nói system prompt có thể được snapshot và dùng lại trong các request sau. Nếu đã thay đổi prompt mà kết quả chưa đổi, hãy bắt đầu session mới hoặc compact session. Khi cần xây lại prompt mỗi request, xem cấu hình snapshot=False trong ví dụ của README.
VII.Có nên dùng không
Bạn nên chọn thư viện này nếu muốn xây ứng dụng Python có Claude Agent thay vì chỉ gọi mô hình một lần. SDK có API tương đối trực tiếp, hỗ trợ streaming message, cấu hình thư mục làm việc, tool, hook, MCP nội bộ và MCP bên ngoài. Việc Claude Code CLI được bundle cũng làm giảm số bước cài đặt ban đầu.
Repo có giấy phép MIT, dùng Python và còn được cập nhật. Hiện repo có khoảng 8.538 sao và 1.414 fork. Cấu trúc repo cũng có examples/, tests/, e2e-tests/, src/ và pyproject.toml, thuận tiện để đọc thêm khi bạn muốn đi từ ví dụ nhỏ lên ứng dụng hoàn chỉnh.
Giới hạn chính là SDK có thể cho agent quyền đọc, ghi tệp hoặc chạy Bash, nên triển khai thực tế cần thiết kế quyền cẩn thận. README được cung cấp chưa nói rõ quy trình tài khoản, API key, chi phí hay bảo mật dữ liệu, nên bạn cần bổ sung bước kiểm tra theo môi trường sử dụng.
Nếu bạn chỉ cần gửi một prompt đơn giản và nhận một câu trả lời, SDK này có thể nhiều chức năng hơn mức cần thiết. Nếu bạn cần agent làm việc trong dự án, gọi công cụ Python, kết hợp MCP và áp quy tắc an toàn bằng hook, đây là lựa chọn đáng cân nhắc.
Câu hỏi thường gặp
claude-agent-sdk-python có miễn phí không?
Repo sử dụng giấy phép MIT. Tuy nhiên, tư liệu được cung cấp không nói chi tiết về chi phí sử dụng Claude hoặc các dịch vụ liên quan, nên chưa thể kết luận toàn bộ quá trình chạy là miễn phí.
Có cần cài Claude Code CLI riêng không?
Thông thường không cần. README nói Claude Code CLI được tự động đóng gói cùng package và SDK dùng bản bundle mặc định. Bạn chỉ cài CLI riêng khi muốn dùng bản toàn hệ thống hoặc chỉ định một phiên bản cụ thể.
Có cần GPU không?
README không yêu cầu GPU và cũng không nêu yêu cầu phần cứng đặc biệt. Tư liệu chỉ ghi điều kiện Python 3.10 trở lên.
Có chạy được trên Windows không?
README nói workflow phát hành tạo wheel cho macOS, Linux và Windows. Tuy vậy, tài liệu được cung cấp không có hướng dẫn cài đặt Windows riêng, nên bạn cần kiểm tra môi trường Python thực tế nếu gặp lỗi.
Có thể cho agent sửa file và chạy Bash không?
Có. README cho biết bộ công cụ mặc định gồm Read, Write, Edit, Bash và các công cụ khác. Bạn có thể dùng allowed_tools, disallowed_tools, permission_mode và hook để kiểm soát việc chấp thuận hoặc chặn công cụ.
Custom tool khác MCP server thông thường thế nào?
Custom tool được định nghĩa bằng hàm Python và chạy trong cùng tiến trình với ứng dụng thông qua SDK MCP server. Cách này không cần quản lý subprocess riêng, giảm giao tiếp liên tiến trình và đơn giản hóa triển khai.
Dữ liệu gửi qua SDK có an toàn không?
README không cung cấp chính sách bảo mật dữ liệu cụ thể. Bạn nên giới hạn thư mục làm việc, kiểm soát quyền công cụ, dùng hook cho lệnh nhạy cảm và kiểm tra điều khoản dịch vụ trước khi đưa dữ liệu thật vào ứng dụng.


