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à bộ SDK Python của Anthropic để bạn gọi Claude Code (agent biết đọc, ghi file, chạy lệnh) ngay trong chương trình Python của mình. Cài bằng một lệnh pip, bản Claude Code CLI đã được đóng gói sẵn trong gói. Chỉ cần Python 3.10 trở lên nên cài không khó.

claude-agent-sdk-python là thư viện Python chính thức của Anthropic, giúp bạn điều khiển Claude Code (agent của Claude biết đọc file, sửa file, chạy lệnh) từ chính code Python của mình. Thay vì gõ từng câu trong cửa sổ chat, bạn viết vài dòng Python để gửi yêu cầu, nhận kết quả, rồi nối vào quy trình công việc của bạn.

Repo này hợp với lập trình viên mới muốn làm thử một "trợ lý AI biết làm việc", và với người làm văn phòng, kinh doanh có biết chút Python, muốn tự động hoá việc lặp lại. 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 3 tháng gần đây.

Điểm đáng giá nhất: bản Claude Code CLI được đóng gói sẵn trong gói cài đặt. Bạn không phải cài thêm công cụ nào khác, chỉ cần một lệnh pip install. Ngoài ra bạn còn tự viết được công cụ riêng (là các hàm Python) để Claude gọi, và đặt "hook" để chặn hoặc kiểm tra những gì Claude định làm.

Thư viện

anthropics/claude-agent-sdk-python

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

★ 8.5kPythonMIT
Xem repo trên GitHub

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

A.Gửi yêu cầu và nhận phản hồi bằng query()

Đây là cách đơn giản nhất. Bạn gọi hàm query() với một câu lệnh (prompt), và nhận về các tin nhắn trả lời theo từng phần. Hợp với việc "hỏi một lần, nhận kết quả", ví dụ nhờ Claude tóm tắt hay tạo một file.

B.Cho Claude dùng công cụ có sẵn

Mặc định Claude có toàn bộ bộ công cụ của Claude Code, trong đó có Read, Write, Edit, Bash. Nghĩa là nó có thể đọc file, tạo file, sửa file, chạy lệnh. Bạn dùng allowed_tools để liệt kê công cụ được tự động duyệt (khỏi hỏi lại). README nói rõ: allowed_tools chỉ là danh sách cho phép, không gỡ công cụ nào khỏi Claude. Muốn chặn hẳn công cụ nào thì dùng disallowed_tools.

C.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. Đây cũng là chỗ bạn dùng được tool tự viết và hook.

D.Tự viết công cụ cho Claude (custom tools)

Bạn viết một hàm Python, gắn decorator @tool, rồi đưa cho Claude gọi khi cần. Các tool này chạy ngay trong chương trình của bạn dưới dạng MCP server trong tiến trình, nên không cần chạy thêm tiến trình riêng. Có thể dùng chung với các MCP server bên ngoài.

E.Hook để kiểm soát hành vi của agent

Hook là hàm Python do ứng dụng Claude Code gọi (không phải Claude) tại những thời điểm nhất định. Ví dụ trước khi Claude chạy một lệnh Bash, hook kiểm tra và từ chối nếu lệnh chứa mẫu bị cấm. Đây là cách đặt "hàng rào" chắc chắn thay vì chỉ dặn Claude bằng lời.

F.Các tuỳ chọn khác

Qua ClaudeAgentOptions bạn đặt được thư mục làm việc (cwd), system prompt, số lượt tối đa (max_turns), chế độ cấp quyền (permission_mode) và nhiều thứ khác. Thư viện cũng có sẵn các loại lỗi riêng để bắt lỗi gọn gàng.

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

Theo README và file pyproject.toml, yêu cầu bắt buộc chỉ có một:

  • Python 3.10 trở lên.

Claude Code CLI đã được đóng gói sẵn trong gói, nên không phải cài riêng. 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ể, README cho hai cách: cài Claude Code riêng, hoặc chỉ đường dẫn qua ClaudeAgentOptions(cli_path="/path/to/claude").

Quy trình phát hành của repo build gói cho macOS, Linux và Windows, nên dùng được trên cả ba hệ điều hành này.

README không nói về tài khoản, API key hay cách đăng nhập. Phần này README chưa ghi, bạn xem thêm trong tài liệu chính thức mà README dẫn tới (Claude Agent SDK documentation) để biết cách xác thực.

Claude có thể ghi file và chạy lệnh trên máy bạn. Lần đầu hãy thử trong một thư mục trống, đừng trỏ thẳng vào thư mục dữ liệu quan trọng. Chỉ bật tự động duyệt (allowed_tools, permission_mode) cho những công cụ bạn hiểu rõ.

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

  1. Kiểm tra PythonĐảm bảo máy có Python 3.10 trở lên
  2. Tạo môi trường ảoTách thư viện của dự án khỏi phần còn lại của máy
  3. Cài góiChạy pip install claude-agent-sdk
  4. Tạo file thửChép đoạn Quick Start của README vào một file .py
  5. Chạy thửChạy file bằng Python và xem Claude trả lời

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

Mở terminal (trên Windows là PowerShell hoặc Terminal, trên Mac/Linux là Terminal) rồi gõ:

Terminal
python --version

Phải thấy số từ 3.10 trở lên. Nếu thấy 3.9 hoặc thấp hơn, bạn cần cài Python mới hơn trước. Một số máy dùng lệnh python3 thay cho python, bạn thử cả hai.

B.Tạo môi trường ảo (nên làm)

Bước này không có trong README nhưng là thói quen tốt của người dùng Python. Nó giúp thư viện chỉ nằm trong thư mục dự án của bạn.

Terminal
mkdir thu-claude-sdk
cd thu-claude-sdk
python -m venv .venv

Kích hoạt môi trường. Trên Windows (PowerShell):

PowerShell
.venv\Scripts\activate

Trên Mac hoặc Linux:

Terminal
source .venv/bin/activate

Kích hoạt xong, đầu dòng lệnh sẽ có chữ (.venv). Chỗ người mới hay vấp: mỗi lần mở terminal mới, bạn phải kích hoạt lại.

C.Cài thư viện

Đây là lệnh cài theo đúng README:

Terminal
pip install claude-agent-sdk

Lệnh này tải gói claude-agent-sdk về, kèm bản Claude Code CLI đã đóng gói. Bạn không cần cài Claude Code riêng.

Nếu bạn muốn dùng bản Claude Code cài riêng trên máy, README nêu lệnh sau (dành cho shell kiểu Mac/Linux):

Terminal
curl -fsSL https://claude.ai/install.sh | bash

Người mới không cần bước này.

D.Tạo file chạy thử

Tạo file tên hello.py trong thư mục vừa tạo, dán đoạn Quick Start của README:

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)

Giải thích ngắn: query() là hàm bất đồng bộ (async), nên cần anyio.run(main) để chạy. Vòng async for nhận từng tin nhắn khi Claude trả về, và print in ra màn hình.

E.Chạy thử

Terminal
python hello.py

Nếu báo lỗi liên quan đăng nhập hay xác thực, README chưa ghi cách xử lý. Bạn xem tài liệu chính thức mà README dẫn tới.

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

Trước hết kiểm tra thư viện đã vào máy chưa:

Terminal
pip show claude-agent-sdk

Thấy tên gói và số phiên bản là đã cài xong. Sau đó chạy python hello.py. README không mô tả chính xác màn hình kết quả, nhưng theo Quick Start, chương trình sẽ in ra các tin nhắn của Claude cho câu hỏi "What is 2 + 2?", trong đó có câu trả lời là 4. Bạn sẽ thấy nhiều dòng, vì print(message) in cả các loại tin nhắn khác nhau chứ không chỉ chữ trả lời.

Muốn chỉ in phần chữ, dùng đoạn README đưa ra cho query():

Python
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

async for message in query(prompt="Hello Claude"):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)

Đoạn này lọc ra tin nhắn của Claude và chỉ in phần văn bản. Nhớ đặt nó trong một hàm async giống ví dụ trên.

Repo còn có thư mục examples/, trong đó README nhắc examples/quick_start.py và examples/streaming_mode.py. Bạn có thể mở ra tham khảo.

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

Những tình huống dưới đây bám theo những gì README mô tả. Phần prompt là ví dụ minh hoạ do mình tự soạn, bạn đổi theo việc của mình.

A.Dev mới: nhờ Claude tạo file trong thư mục dự án

Bối cảnh: bạn đang học lập trình, muốn Claude tạo nhanh một file mẫu. README có ví dụ đúng việc này: cho phép các công cụ Read, Write, Bash và tự duyệt chỉnh sửa file.

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 trong thư mục làm việc. Muốn chỉ định thư mục khác, thêm cwd="/path/to/project" vào ClaudeAgentOptions. Nên trỏ vào một thư mục thử nghiệm.

Hook là hàng rào chắc chắn: bạn không cần cầu mong Claude nghe lời, code của bạn tự chặn lệnh nguy hiểm.

Ông T

B.Người lo an toàn: chặn lệnh không mong muốn bằng hook

Bối cảnh: bạn cho Claude chạy lệnh Bash nhưng muốn cấm một số lệnh cụ thể. README có ví dụ hook PreToolUse kiểm tra lệnh trước khi chạy và từ chối nếu chứa mẫu bị cấm (trong ví dụ là 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 chứa 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 đổi danh sách block_patterns thành những mẫu mà bạn muốn chặn.

C.Dev trong công ty: cho Claude gọi hàm nghiệp vụ của bạn

Bối cảnh: bạn có sẵn một hàm Python (ví dụ tra cứu dữ liệu nội bộ) và muốn Claude gọi nó khi cần. Dùng @tool để biến hàm thành công cụ. Ví dụ "greet" trong README:

Python
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient

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

server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[greet_user]
)

options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Greet Alice")
    async for msg in client.receive_response():
        print(msg)

Kết quả: Claude gọi công cụ greet với tên Alice và trả về lời chào. Khi làm thật, bạn thay phần thân hàm bằng việc của bạn. Tên công cụ để duyệt có dạng mcp__<tên server trong mcp_servers>__<tên tool>, như mcp__tools__greet ở ví dụ trên.

D.Làm chatbot nhiều lượt trong chương trình của bạn

Bối cảnh: bạn muốn hỏi Claude liên tiếp, câu sau dựa trên câu trước. Dùng ClaudeSDKClient thay vì query(). Mỗi lần gọi client.query(...) rồi đọc kết quả bằng client.receive_response(), như ví dụ hook ở trên (có hai lần hỏi liên tiếp trong cùng một phiên). README gợi ý xem examples/streaming_mode.py cho các ví dụ đầy đủ về chế độ này.

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

A.Lỗi không tìm thấy Claude Code (CLINotFoundError)

README có loại lỗi này, ý nghĩa là Claude Code chưa được cài. Thường gói đã kèm sẵn CLI, nên nếu gặp lỗi, hãy thử cài lại gói bằng pip install claude-agent-sdk trong đúng môi trường ảo đang dùng. Nếu muốn dùng bản cài riêng, chỉ đường dẫn bằng cli_path như README hướng dẫn.

B.pip báo không tìm thấy phiên bản phù hợp

Thường do Python trên máy cũ hơn 3.10. Kiểm tra lại bằng python --version, cài Python mới hơn rồi tạo lại môi trường ảo.

C.Chạy mà không thấy gì, hoặc báo lỗi async

query() là hàm bất đồng bộ, nên không thể gọi trực tiếp ở cấp ngoài cùng của file Python thường. Hãy đặt trong async def main() và chạy bằng anyio.run(main) như ví dụ Quick Start. Nhớ cài anyio nếu bị báo thiếu, thư viện này được ví dụ README dùng.

D.Claude vẫn dùng công cụ mà bạn tưởng đã tắt

Đâ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 công cụ, dùng disallowed_tools. Có thể thêm hook như ví dụ ở trên để chặn chính xác theo nội dung lệnh.

E.Sửa system prompt mà không thấy khác

Theo README, Claude Code mặc định ghi lại system prompt ở yêu cầu đầu tiên của phiên và dùng lại cho các yêu cầu sau, kể cả khi bạn mở lại phiên. Nên nếu bạn đổi prompt mà không thấy tác dụng, hãy bắt đầu phiên mới, hoặc đặt snapshot thành False trong dict system prompt. Tuỳ chọn này cần Claude Code CLI từ phiên bản 2.1.257 trở lên.

F.Lỗi khi chạy (ProcessError, ResultError)

README có các loại lỗi riêng để bạn bắt và in ra thông tin: ProcessError (tiến trình thất bại, có mã thoát), ResultError (Claude báo kết quả lỗi, có các trường như subtype, terminal_reason), CLIJSONDecodeError (không đọc được JSON). Bọc lời gọi query() trong try/except và in lỗi ra sẽ giúp bạn biết lỗi ở đâu. Danh sách đầy đủ nằm trong file src/claude_agent_sdk/_errors.py.

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

Điểm mạnh:

  • Thư viện chính thức của Anthropic, giấy phép MIT, repo còn được cập nhật.
  • Cài đơn giản bằng một lệnh pip, Claude Code CLI đã đóng gói sẵn.
  • Có cả cách gọi nhanh (query()) lẫn cách hội thoại nhiều lượt (ClaudeSDKClient).
  • Tự viết tool và hook bằng Python, không cần dựng thêm tiến trình riêng.
  • Có thư mục examples/ và tài liệu chính thức để học tiếp.

Giới hạn:

  • Cần biết chút Python, và hiểu cơ bản về async mới viết được code của riêng mình.
  • Agent có thể ghi file và chạy lệnh, nên cần cẩn thận về quyền hạn.
  • README không nói về xác thực, chi phí hay giới hạn sử dụng. Bạn cần xem tài liệu chính thức trước khi dùng nghiêm túc.
  • Việc sử dụng SDK chịu Điều khoản Dịch vụ Thương mại của Anthropic, kể cả khi bạn dùng nó để làm sản phẩm cho khách hàng của mình. Đọ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 không biết lập trình và chỉ muốn trò chuyện với Claude, dùng ứng dụng hoặc Claude Code trực tiếp sẽ nhanh hơn. Còn nếu bạn muốn nhúng một "trợ lý biết làm việc" vào quy trình, script hay sản phẩm của mình bằng Python, thì đây là lựa chọn đáng thử đầu tiên.

3.9/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 không nói gì về chi phí khi Claude chạy, và việc dùng SDK chịu Điều khoản Dịch vụ Thương mại của Anthropic. Bạn nên xem tài liệu chính thức để biết chi phí và cách xác thực.

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

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

Cần Python phiên bản nào?

Python 3.10 trở lên, theo cả README và file pyproject.toml.

Chạy được trên Windows không?

Có khả năng cao. Quy trình phát hành của repo build gói riêng cho macOS, Linux và Windows. README không có hướng dẫn riêng cho Windows, nhưng lệnh pip cài đặt giống nhau trên các hệ điều hành.

Cần GPU không?

Tư liệu không nhắc đến yêu cầu GPU hay phần cứng nào. Thư viện chỉ điều khiển Claude Code từ Python, nên bạn không cần cấu hình đặc biệt theo những gì README nói.

Claude có tự ý sửa file hay chạy lệnh trên máy tôi không?

Mặc định Claude có cả bộ công cụ của Claude Code như Read, Write, Edit, Bash. allowed_tools quyết định công cụ nào được tự động duyệt, còn công cụ không nằm trong danh sách sẽ tuỳ vào permission_mode và can_use_tool. Bạn có thể chặn bằng disallowed_tools hoặc hook, và nên thử trong thư mục riêng.

query() khác ClaudeSDKClient thế nào?

query() là hàm bất đồng bộ để gửi yêu cầu và nhận kết quả. ClaudeSDKClient hỗ trợ hội thoại hai chiều, tương tác nhiều lượt, và chỉ nó mới dùng được tool tự viết và hook theo README.

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 và nhận phản hồi bằng query()
    2. B.Cho Claude dùng công cụ có sẵn
    3. C.Hội thoại hai chiều với ClaudeSDKClient
    4. D.Tự viết công cụ cho Claude (custom tools)
    5. E.Hook để kiểm soát hành vi của agent
    6. F.Các tuỳ chọn khác
  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.Tạo môi trường ảo (nên làm)
    3. C.Cài thư viện
    4. D.Tạo file chạy thử
    5. E.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.Dev mới: nhờ Claude tạo file trong thư mục dự án
    2. B.Người lo an toàn: chặn lệnh không mong muốn bằng hook
    3. C.Dev trong công ty: cho Claude gọi hàm nghiệp vụ của bạn
    4. D.Làm chatbot nhiều lượt trong chương trình của bạn
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Lỗi không tìm thấy Claude Code (CLINotFoundError)
    2. B.pip báo không tìm thấy phiên bản phù hợp
    3. C.Chạy mà không thấy gì, hoặc báo lỗi async
    4. D.Claude vẫn dùng công cụ mà bạn tưởng đã tắt
    5. E.Sửa system prompt mà không thấy khác
    6. F.Lỗi khi chạy (ProcessError, ResultError)
  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ỏ.