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

> 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ó.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-23 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/claude-agent-sdk-python-huong-dan-cai-dat-va-dung

**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.

```repo
- repo | anthropics/claude-agent-sdk-python
- kind | Thư viện
- desc | 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.
- stars | 8.5k
- lang | Python
- license | MIT
```

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

### 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.

### 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`.

### 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.

### 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.

### 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.

### 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.

## 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.

```note
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õ.
```

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

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

### 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õ:

```bash
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.

### 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.

```bash
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:

```bash
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ài thư viện

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

```bash
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):

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

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

### 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.

### Chạy thử

```bash
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.

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

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

```bash
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.

## 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.

### 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

### 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.

### 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.

### 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.

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

### 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.

### `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.

### 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.

### 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.

### 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.

### 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`.

## 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.

## 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.
