Bỏ qua tới nội dung
Ông T.vn

claude-agent-sdk-python: tạo agent Claude bằng Python — hướng dẫn cài đặt và dùng

11 phút đọcCập nhật

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 →

claude-agent-sdk-python: tạo 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à SDK Python của Anthropic, cho phép bạn gọi Claude Code ngay từ chương trình Python để Claude đọc file, sửa file, chạy lệnh và dùng công cụ bạn tự viết. Cài bằng một lệnh pip, cần Python 3.10 trở lên, và CLI Claude Code đã được đóng gói sẵn trong gói. Với người đã biết chút Python, việc cài khá dễ.

claude-agent-sdk-python là bộ thư viện Python chính thức để điều khiển Claude Code bằng code. Thay vì gõ từng câu vào khung chat, bạn viết vài dòng Python, gửi yêu cầu, rồi nhận về từng thông điệp trả lời. Claude vẫn dùng được các công cụ quen thuộc của Claude Code như đọc file, ghi file, sửa file và chạy lệnh.

Repo này hợp với lập trình viên mới và người làm văn phòng biết chút Python muốn tự động hoá việc lặp đi lặp lại: tạo file, xử lý thư mục, kiểm tra lệnh trước khi chạy. Nó cũng hợp với dev muốn nhúng một agent vào sản phẩm của mình. Hiện repo có khoảng 8.533 sao và 1.414 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.

Điểm đáng giá nhất là bạn không phải cài Claude Code riêng. README nói CLI Claude Code đã được đóng gói sẵn trong gói, nên cài xong là chạy. Ngoài ra bạn có thể biến một hàm Python thành công cụ cho Claude gọi, và chèn "hook" để chặn hoặc kiểm soát hành động của Claude trước khi nó chạy.

Thư viện

anthropics/claude-agent-sdk-python

Thư viện Python chính thức để điều khiển Claude Code từ code: gửi yêu cầu, cho Claude dùng công cụ, thêm tool và hook tự viết bằng hàm Python.

★ 8.5kPythonMIT
Xem repo trên GitHub

I.claude-agent-sdk-python làm được gì

A.Gửi yêu cầu bằng hàm query()

query() là hàm bất đồng bộ (async). Bạn đưa vào một câu yêu cầu, nó trả về từng thông điệp phản hồi theo thứ tự. Đây là cách ngắn nhất để "hỏi Claude từ Python" và phù hợp với các việc một lần, hỏi một câu rồi nhận kết quả.

B.Cho Claude dùng công cụ, có kiểm soát quyền

Mặc định Claude có cả bộ công cụ của Claude Code (Read, Write, Edit, Bash và một số công cụ khác). Tuỳ chọn allowed_tools là danh sách tự động duyệt: công cụ nào nằm trong đó thì chạy luôn, không hỏi lại. Nó không gỡ công cụ nào khỏi tay Claude. Muốn chặn hẳn một công cụ thì dùng disallowed_tools. Nhờ vậy bạn quyết định được việc nào để Claude tự làm, việc nào phải hỏi.

C.Chọn thư mục làm việc và lời dặn hệ thống

Bạn chỉ định thư mục dự án bằng cwd, để Claude làm việc đúng chỗ. Bạn cũng đặt được system_prompt, tức là lời dặn nền như "bạn là trợ lý hữu ích". README có lưu ý quan trọng: mặc định lời dặn này được ghi lại ở yêu cầu đầu tiên của phiên và dùng lại ở các yêu cầu sau. Nếu bạn đang chỉnh câu chữ liên tục mà thấy không đổi gì, hãy đặt snapshot là False.

D.Hội thoại hai chiều với ClaudeSDKClient

Khác với query(), ClaudeSDKClient cho phép trò chuyện qua lại nhiều lượt trong cùng một phiên. Chỉ bản này mới hỗ trợ công cụ tự viết và hook.

E.Công cụ tự viết bằng hàm Python

Bạn dùng decorator @tool để biến một hàm Python thành công cụ cho Claude gọi. Công cụ chạy ngay trong chương trình của bạn dưới dạng máy chủ MCP nội bộ, không cần tạo thêm tiến trình riêng. README nêu các lợi ích: không phải quản lý tiến trình con, ít độ trễ hơn, triển khai đơn giản hơn, dễ gỡ lỗi hơn. Bạn vẫn dùng được máy chủ MCP bên ngoài song song với máy chủ nội bộ.

F.Hook để chặn hoặc kiểm soát hành động

Hook là hàm Python mà ứng dụng Claude Code (không phải Claude) gọi tại các thời điểm nhất định trong vòng lặp của agent. Ví dụ bạn chặn mọi lệnh Bash chứa một đoạn chữ nguy hiểm trước khi nó được chạy. Đây là chỗ bạn đặt "luật cứng" mà không cần trông chờ Claude tự nhớ.

G.Bắt lỗi rõ ràng

SDK có sẵn các loại lỗi riêng như không tìm thấy Claude Code, lỗi kết nối, tiến trình thất bại, lỗi đọc dữ liệu trả về. Nhờ đó chương trình của bạn xử lý được từng tình huống thay vì sập chung một kiểu.

II.Cần chuẩn bị gì

Theo README và file pyproject.toml, bạn cần:

  • Python 3.10 trở lên. Đây là yêu cầu duy nhất README ghi ở mục Prerequisites.
  • Không cần cài Claude Code riêng. CLI đã được đóng gói sẵn trong gói và SDK dùng bản đó theo mặc định.
  • Terminal. Trên Windows bạn mở PowerShell hoặc Command Prompt. Trên macOS và Linux bạn mở Terminal.

README không nói rõ về tài khoản, cách đăng nhập hay khoá API. Vì SDK chạy Claude Code ở bên dưới, bạn nên đọc thêm tài liệu chính thức của Claude Agent SDK (README có dẫn link tới trang tài liệu Python) để biết cách xác thực. README cũng không ghi yêu cầu phần cứng như GPU.

Claude có thể đọc, ghi, sửa file và chạy lệnh trên máy bạn. Hãy thử trong một thư mục trống hoặc thư mục thử nghiệm trước. Đừng cho tự động duyệt (`allowed_tools`) những công cụ như Bash khi bạn chưa hiểu rõ Claude sẽ chạy lệnh gì. README không nói về chi phí, nên bạn hãy xem điều khoản và bảng giá trong tài liệu chính thức trước khi chạy nhiều.

III.Cài đặt từng bước

  1. Kiểm tra PythonChắc chắn máy có Python 3.10 trở lên
  2. Cài góiChạy một lệnh pip để cài claude-agent-sdk
  3. Tạo file thửChép đoạn Quick Start vào file hello.py
  4. Chạy thửChạy file và xem Claude trả lời

A.Kiểm tra phiên bản Python

Mở terminal (PowerShell trên Windows) rồi gõ lệnh dưới để xem phiên bản. Nếu số hiện ra nhỏ hơn 3.10, bạn cần cài Python mới hơn trước khi đi tiếp. Trên một số máy macOS và Linux, lệnh có thể là python3 thay vì python.

Terminal
python --version

B.Cài gói claude-agent-sdk

Đây là lệnh cài đúng như README. Lệnh tải gói về máy cùng bản Claude Code đã đóng gói sẵn.

Terminal
pip install claude-agent-sdk

Chỗ người mới hay vấp: gõ lệnh ở terminal thường, không gõ bên trong trình soạn thảo Python đang mở. Nếu máy báo không tìm thấy pip, thử python -m pip install claude-agent-sdk. Đây là cách gọi pip phổ biến của Python, không phải lệnh riêng của repo.

Nếu bạn đã cài Claude Code ở nơi khác và muốn dùng bản đó, README có hai cách: cài riêng bằng curl -fsSL https://claude.ai/install.sh | bash, hoặc chỉ đường dẫn bằng ClaudeAgentOptions(cli_path="/path/to/claude"). Người mới thì không cần làm bước này.

C.Tạo file hello.py

Tạo một file tên hello.py rồi chép đoạn Quick Start của README vào. Đoạn này hỏi Claude "2 + 2 bằng mấy" và in từng thông điệp nhận về.

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

Nếu Python báo thiếu module anyio, hãy xem phần dependencies trong pyproject.toml của repo. README không nói rõ chuyện này.

D.Chạy thử

Mở terminal đúng thư mục chứa hello.py rồi chạy:

Terminal
python hello.py

IV.Kiểm tra đã chạy được chưa

Cài thành công khi lệnh python hello.py không báo lỗi và in ra một loạt thông điệp, trong đó có câu trả lời cho phép tính 2 + 2. Mỗi thông điệp là một đối tượng của SDK, nên màn hình sẽ khá dài, không chỉ có chữ "4". README không mô tả chính xác dạng chữ hiện ra, nên đừng lo nếu trông khác một câu trả lời thông thường.

Muốn chỉ in phần chữ của Claude, dùng đoạn sau trong README. Nó lọc ra thông điệp của trợ lý và chỉ in các khối văn bản:

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

Nếu có lỗi CLINotFoundError (không tìm thấy Claude Code) thì xem phần lỗi bên dưới.

V.Dùng vào việc thật

A.Nhân viên văn phòng: nhờ Claude tạo file mẫu

Bạn cần nhanh một file Python nhỏ trong thư mục dự án. Cho phép Claude dùng Read, Write, Bash và tự chấp nhận việc sửa file, rồi giao việc bằng một câu. Cấu hình theo README:

Python
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
    pass

Kết quả: Claude tạo file hello.py mà bạn không phải mở trình soạn thảo. Bạn có thể đổi câu yêu cầu thành việc khác bạn cần. Để Claude làm trong đúng thư mục, thêm cwd="/path/to/project" vào ClaudeAgentOptions.

Cho Claude tự làm việc thì dễ. Khó là biết nó được phép làm gì và không được làm gì.

Ông T

B.Dev: chặn lệnh nguy hiểm bằng hook

Bạn dựng một trợ lý cho team và muốn chắc chắn nó không chạy một số lệnh. Dùng hook PreToolUse kiểm tra lệnh Bash trước khi chạy. Ví dụ trong README chặn mọi lệnh chứa foo.sh:

Python
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher

async def check_bash_command(input_data, tool_use_id, context):
    tool_name = input_data["tool_name"]
    tool_input = input_data["tool_input"]
    if tool_name != "Bash":
        return {}
    command = tool_input.get("command", "")
    block_patterns = ["foo.sh"]
    for pattern in block_patterns:
        if pattern in command:
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": f"Command contains invalid pattern: {pattern}",
                }
            }
    return {}

options = ClaudeAgentOptions(
    allowed_tools=["Bash"],
    hooks={
        "PreToolUse": [
            HookMatcher(matcher="Bash", hooks=[check_bash_command]),
        ],
    }
)

Kết quả: lệnh có foo.sh bị từ chối kèm lý do, còn lệnh an toàn như echo vẫn chạy bình thường. Bạn thay danh sách block_patterns bằng những đoạn chữ cần chặn của mình. Repo còn có thêm ví dụ ở examples/hooks.py.

C.Dev: cho Claude gọi hàm Python của công ty

Bạn có một hàm nội bộ, chẳng hạn tra thông tin trong hệ thống của mình, và muốn Claude gọi được. Dùng @tool để bọc hàm rồi gom vào một máy chủ MCP nội bộ. Ví dụ "chào người dùng" trong README:

Python
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient

# Define a tool using the @tool decorator
@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {
        "content": [
            {"type": "text", "text": f"Hello, {args['name']}!"}
        ]
    }

# Create an SDK MCP server
server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[greet_user]
)

# Use it with Claude. allowed_tools pre-approves the tool so it runs
# without a permission prompt; it does not control tool availability.
options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Greet Alice")

    # Extract and print response
    async for msg in client.receive_response():
        print(msg)

Kết quả: Claude hiểu yêu cầu "Greet Alice", gọi công cụ greet của bạn và trả lại lời chào. Bạn thay phần thân hàm bằng việc thật của mình. Chú ý tên công cụ khi cho phép có dạng mcp__<tên máy chủ trong mcp_servers>__<tên công cụ>, như mcp__tools__greet ở trên.

D.Người mới: đổi lời dặn để Claude trả lời theo vai

Bạn muốn Claude trả lời ngắn gọn và đúng vai. Đặt system_prompt và giới hạn số lượt bằng max_turns, theo README:

Python
options = ClaudeAgentOptions(
    system_prompt="You are a helpful assistant",
    max_turns=1
)

async for message in query(prompt="Tell me a joke", options=options):
    print(message)

Kết quả: Claude trả lời đúng một lượt, theo vai bạn đặt. Đây là cách thử nhanh để hiểu các tuỳ chọn trước khi làm việc lớn hơn. Repo còn có examples/quick_start.py và examples/streaming_mode.py để xem thêm.

VI.Lỗi hay gặp và cách xử lý

A.Báo CLINotFoundError

Đây là lỗi "không tìm thấy Claude Code". README nói CLI đã được đóng gói sẵn, nên lỗi này thường do cài gói không trọn vẹn hoặc bạn đã chỉ sai cli_path. Hãy gỡ phần cli_path đi để SDK dùng bản đóng gói, hoặc cài lại gói bằng pip install claude-agent-sdk. Nếu vẫn lỗi, cài Claude Code riêng theo lệnh trong README.

B.Báo lỗi tiến trình hoặc kết quả (ProcessError, ResultError)

ProcessError cho biết tiến trình thất bại kèm mã thoát. ResultError là khi Claude Code trả về một kết quả lỗi. Hãy bắt lỗi như ví dụ trong README và in e.result hoặc e.errors ra để xem nguyên nhân. Nếu liên quan đến đăng nhập hoặc xác thực, xem tài liệu chính thức của Claude Agent SDK, vì README chưa ghi cách xử lý.

C.Đổi system_prompt mà không thấy khác

Mặc định lời dặn hệ thống được ghi lại ở yêu cầu đầu tiên và dùng lại cho các yêu cầu sau, kể cả khi mở lại phiên. Nên bạn sửa chữ mà Claude vẫn trả lời như cũ. Hãy bắt đầu phiên mới, hoặc đặt snapshot thành False trong dict của system_prompt. README ghi cách này cần Claude Code CLI từ bản 2.1.257 trở lên.

D.Đã đặt allowed_tools mà Claude vẫn dùng công cụ khác

Đây là hiểu nhầm hay gặp. allowed_tools chỉ là danh sách tự động duyệt, không gỡ công cụ khỏi Claude. Muốn chặn hẳn, dùng disallowed_tools, hoặc dùng hook như ví dụ ở trên. Phần quyền chi tiết nằm trong hướng dẫn permissions của tài liệu chính thức.

E.Lỗi khi chạy code async

Hàm query() là async nên không gọi trực tiếp như hàm thường. Hãy bọc trong async def main() và chạy bằng anyio.run(main) như ví dụ Quick Start. Các đoạn dùng async for hay async with ở trên cũng phải nằm trong hàm async, trừ khi bạn dùng môi trường hỗ trợ sẵn như IPython (repo có examples/streaming_mode_ipython.py).

VII.Có nên dùng không

Điểm mạnh. Đây là SDK chính thức, giấy phép MIT, cài một lệnh pip, không phải cài Claude Code riêng. Bạn có được công cụ, hook và máy chủ MCP nội bộ chỉ bằng hàm Python. Repo có thư mục examples/ để học theo, và hiện có khoảng 8.533 sao nên cộng đồng khá đông.

Giới hạn. README ngắn, chủ yếu trỏ sang tài liệu chính thức. Phần đăng nhập, khoá và chi phí README không nói, nên bạn phải tự xem thêm. Bạn cần biết chút Python và hiểu code async, nên nếu chưa từng viết code thì sẽ hơi khó. Về điều khoản, README nêu việc dùng SDK chịu sự điều chỉnh của Điều khoản Thương mại của Anthropic, kể cả khi bạn dùng để làm sản phẩm cho khách hàng của mình. Hãy đọc kỹ trước khi đưa vào sản phẩm.

Khi nào chọn cách khác. Nếu bạn chỉ muốn trò chuyện hoặc nhờ Claude làm việc bằng tay, dùng thẳng Claude Code cho nhanh. SDK này đáng dùng khi bạn muốn tự động hoá, chạy theo kịch bản, hoặc nhúng Claude vào chương trình Python của mình. Nếu bạn dùng ngôn ngữ khác Python thì repo này không phải lựa chọn, vì đây là bản dành riêng cho Python.

4.0/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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

claude-agent-sdk-python có miễn phí không?

Bản thân thư viện dùng giấy phép MIT và cài miễn phí bằng pip. Tuy nhiên README nói việc dùng SDK chịu điều chỉnh của Điều khoản Thương mại của Anthropic. Thông tin về chi phí khi gọi Claude chưa có trong README, bạn nên xem tài liệu chính thức.

Cần cài riêng Claude Code không?

Không bắt buộc. README nói CLI Claude Code đã được đóng gói sẵn trong gói, SDK dùng bản đó theo mặc định. Nếu muốn dùng bản cài sẵn trên máy hoặc một phiên bản cụ thể, bạn chỉ đường dẫn bằng cli_path hoặc cài Claude Code riêng.

Cần phiên bản Python nào, có chạy được trên Windows không?

Cần Python 3.10 trở lên. Quy trình phát hành trong README build gói riêng cho macOS, Linux và Windows, nên Windows được hỗ trợ ở mức gói cài sẵn. Các lệnh trong bài này bạn chạy được trong PowerShell.

Có cần GPU không?

README không nhắc tới yêu cầu GPU hay phần cứng đặc biệt nào. Chỉ có yêu cầu Python 3.10 trở lên được ghi rõ.

Khác gì giữa query() và ClaudeSDKClient?

query() là hàm async để gửi yêu cầu và nhận về từng thông điệp, hợp với việc hỏi một lần. ClaudeSDKClient cho hội thoại hai chiều nhiều lượt, và chỉ bản này hỗ trợ công cụ tự viết cùng hook.

Làm sao ngăn Claude chạy lệnh nguy hiểm?

Dùng disallowed_tools để chặn hẳn một công cụ, hoặc viết hook PreToolUse để kiểm tra từng lệnh trước khi chạy và từ chối nếu có đoạn chữ cấm. README có ví dụ chặn lệnh Bash chứa foo.sh. Lưu ý allowed_tools chỉ tự động duyệt, không gỡ công cụ.

Dữ liệu của tôi có an toàn không?

README không có thông tin về xử lý dữ liệu hay quyền riêng tư. Bạn nên đọc tài liệu chính thức và điều khoản của Anthropic. Vì Claude có thể đọc và ghi file trên máy, hãy thử trong thư mục thử nghiệm trước.

Chuyển nhanh tới mục

  1. I.claude-agent-sdk-python làm được gì
    1. A.Gửi yêu cầu bằng hàm query()
    2. B.Cho Claude dùng công cụ, có kiểm soát quyền
    3. C.Chọn thư mục làm việc và lời dặn hệ thống
    4. D.Hội thoại hai chiều với ClaudeSDKClient
    5. E.Công cụ tự viết bằng hàm Python
    6. F.Hook để chặn hoặc kiểm soát hành động
    7. G.Bắt lỗi rõ ràng
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Kiểm tra phiên bản Python
    2. B.Cài gói claude-agent-sdk
    3. C.Tạo file hello.py
    4. D.Chạy thử
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Nhân viên văn phòng: nhờ Claude tạo file mẫu
    2. B.Dev: chặn lệnh nguy hiểm bằng hook
    3. C.Dev: cho Claude gọi hàm Python của công ty
    4. D.Người mới: đổi lời dặn để Claude trả lời theo vai
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Báo CLINotFoundError
    2. B.Báo lỗi tiến trình hoặc kết quả (ProcessError, ResultError)
    3. C.Đổi system_prompt mà không thấy khác
    4. D.Đã đặt allowed_tools mà Claude vẫn dùng công cụ khác
    5. E.Lỗi khi chạy code async
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.