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

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-13 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/claude-agent-sdk-python-xay-agent-claude-bang-python-2

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.

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

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

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

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

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

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

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

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

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

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

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

```steps
- Chuẩn bị Python | Kiểm tra bạn đang dùng Python 3.10 trở lên
- Tải mã nguồn tùy chọn | Clone repo nếu muốn xem ví dụ và mã nguồn
- Cài package | Cà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
```

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

```bash
python --version
```

Nế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.

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

```bash
git clone https://github.com/anthropics/claude-agent-sdk-python.git
cd claude-agent-sdk-python
```

Nế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ài package Python

Cài package theo đúng lệnh trong README:

```bash
pip install claude-agent-sdk
```

Lệ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:

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

Lệ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.

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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