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

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

13 phút đọcCập nhật
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à SDK Python để gọi Claude Agent và Claude Code từ ứng dụng Python. Bạn có thể chạy truy vấn bất đồng bộ, cho agent đọc/sửa tệp, dùng MCP nội bộ và kiểm soát lệnh bằng hook. Cài đặt khá đơn giản vì gói tự kèm Claude Code CLI; chỉ cần Python 3.10 trở lên.

claude-agent-sdk-python là SDK Python để nhúng Claude Agent vào chương trình của bạn. Thay vì chỉ trò chuyện trong giao diện, bạn có thể viết mã Python để giao nhiệm vụ cho Claude, nhận phản hồi theo luồng và cho agent làm việc với tệp, lệnh hoặc công cụ được cấp quyền.

Repo phù hợp với lập trình viên muốn xây trợ lý nội bộ, tự động hóa quy trình hoặc thêm khả năng xử lý ngôn ngữ vào sản phẩm. Người mới cũng có thể bắt đầu bằng một đoạn mã ngắn. Điểm đáng giá nhất là gói đã tự kèm Claude Code CLI, đồng thời hỗ trợ cả công cụ MCP chạy ngay trong cùng tiến trình Python.

Repo hiện có khoảng 8538 sao và 1414 fork. Đây là dự án mã nguồn mở theo giấy phép MIT, dùng Python và vẫn còn được cập nhật. Tuy vậy, việc sử dụng SDK chịu các điều khoản thương mại của Anthropic khi bạn dùng nó để vận hành sản phẩm cho khách hàng hoặc người dùng cuối.

Thư viện

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 nội bộ và kiểm soát hành vi bằng hook.

★ 8.5kPythonMIT
Xem repo trên GitHub

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

SDK cung cấp hàm query() để gửi yêu cầu cho Claude Code và nhận về một luồng phản hồi bất đồng bộ. Cách này phù hợp với tác vụ dài, vì chương trình có thể xử lý từng thông báo thay vì chờ toàn bộ kết quả mới tiếp tục.

Bạn có thể cấu hình ClaudeAgentOptions cho từng phiên làm việc. Các tùy chọn trong README gồm system prompt, số lượt tối đa, thư mục làm việc, công cụ được tự động chấp thuận, chế độ quyền và đường dẫn Claude Code CLI.

Theo mặc định, 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. Bạn có thể dùng allowed_tools để tự động chấp thuận một số công cụ. Cần hiểu đúng: danh sách này không xóa các công cụ còn lại khỏi bộ công cụ của Claude. Công cụ không nằm trong danh sách sẽ tiếp tục được xử lý bởi permission_mode và can_use_tool.

Nếu muốn ngăn hẳn một công cụ, bạn dùng disallowed_tools. Đây là điểm quan trọng khi agent có thể làm việc với tệp hoặc chạy lệnh trên máy.

SDK cũng có ClaudeSDKClient cho các cuộc hội thoại hai chiều, tương tác nhiều lượt. So với query(), client này còn cho phép bạn định nghĩa custom tool và hook bằng các hàm Python.

Custom tool là một hàm Python mà Claude có thể gọi khi cần. Tool được tạo thành MCP server chạy ngay trong ứng dụng. Bạn không cần quản lý một tiến trình riêng, không phải giao tiếp qua IPC và có thể dùng type hint của Python để mã dễ kiểm tra hơn.

Bạn cũng có thể kết hợp MCP server nội bộ với MCP server bên ngoài. Điều này hữu ích khi một phần công cụ nằm trong ứng dụng Python, còn phần khác vẫn chạy như một subprocess độc lập.

Hook cho phép ứng dụng Claude Code gọi một hàm Python tại các điểm cụ thể trong vòng lặp agent. Hook không phải là Claude. Nó là lớp kiểm soát mang tính quyết định, có thể kiểm tra lệnh trước khi chạy và trả về quyết định cho phép hoặc từ chối.

README có ví dụ dùng hook PreToolUse để chặn lệnh Bash chứa mẫu foo.sh. Cách này phù hợp với quy trình cần rào chắn an toàn, chẳng hạn cấm một số script hoặc kiểm tra đầu vào trước khi agent sử dụng công cụ.

SDK có các kiểu thông báo và khối nội dung rõ ràng. Bạn có thể phân biệt AssistantMessage, UserMessage, SystemMessage, ResultMessage, cũng như TextBlock, ToolUseBlock và ToolResultBlock để xử lý kết quả có cấu trúc.

Phần lỗi cũng được tách riêng thành nhiều loại. Có lỗi không tìm thấy CLI, lỗi kết nối, lỗi tiến trình, lỗi kết quả cuối cùng và lỗi phân tích JSON. Nhờ đó chương trình có thể đưa ra hướng xử lý cụ thể thay vì bắt mọi lỗi bằng một thông báo chung.

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

Bạn cần Python 3.10 trở lên. README không nêu yêu cầu phần cứng đặc biệt.

Bạn cần cài gói Python claude-agent-sdk. Gói này tự kèm Claude Code CLI nên thông thường không cần cài CLI riêng. SDK sẽ dùng CLI được đóng gói theo mặc định.

Nếu muốn dùng một bản Claude Code CLI cài trên toàn hệ thống hoặc một bản cụ thể, README cho phép cài CLI riêng và truyền đường dẫn tùy chỉnh qua ClaudeAgentOptions(cli_path=...).

Tư liệu được cung cấp không nói rõ có cần thiết lập API key, tài khoản nào, biến môi trường nào hay chi phí ra sao. Vì vậy, bạn không nên tự đoán tên biến hoặc chép một cấu hình key không có trong README. Hãy kiểm tra tài liệu và cấu hình Claude Code tương ứng trước khi đưa vào môi trường thật.

Repo có quy trình đóng gói wheel cho macOS, Linux và Windows. README cũng cho biết có thể dùng IPython để chạy một số ví dụ tương tác. Tuy nhiên, phần cài đặt cơ bản chỉ ghi rõ yêu cầu Python 3.10 trở lên.

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

  1. Cài PythonKiểm tra bạn đang dùng Python 3.10 trở lên
  2. Cài SDKCài gói claude-agent-sdk bằng pip
  3. Tạo chương trình thửGọi query() và in phản hồi
  4. Cấu hình agentThêm quyền, thư mục hoặc system prompt khi cần
  5. Kiểm tra lỗiBắt các loại lỗi SDK để biết nguyên nhân

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

Mở Terminal, PowerShell hoặc cửa sổ dòng lệnh tại nơi bạn muốn tạo chương trình. Kiểm tra Python trước khi cài gói:

Terminal
python --version

Kết quả cần là Python 3.10 hoặc mới hơn. Nếu máy có nhiều bản Python, hãy bảo đảm lệnh python trỏ tới bản đáp ứng yêu cầu. README chỉ yêu cầu phiên bản Python, không đưa ra lệnh tạo môi trường ảo, nên phần này tùy cách quản lý Python của bạn.

B.Cài gói Python

Chạy đúng lệnh cài đặt trong README:

Terminal
pip install claude-agent-sdk

Lệnh này cài SDK từ Python Package Index. Claude Code CLI được đóng gói cùng package, nên bạn không cần cài thêm CLI cho cách dùng mặc định.

Nếu pip báo không tìm thấy hoặc cài vào sai bản Python, hãy kiểm tra lại python --version và môi trường Terminal đang dùng. README không đưa ra biến môi trường hay lệnh thay thế cụ thể, vì vậy không nên tự thêm các cờ hoặc tên gói khác.

Nếu bạn muốn dùng Claude Code CLI cài riêng, README đưa ra lệnh sau:

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

Cách này phù hợp khi bạn muốn dùng CLI toàn hệ thống. Nếu chương trình cần một đường dẫn CLI cụ thể, truyền đường dẫn đó trong cấu hình:

Python
options = ClaudeAgentOptions(cli_path="/path/to/claude")

Đường dẫn /path/to/claude chỉ là mẫu trong README. Bạn phải thay bằng đường dẫn thật trên máy, không nên chép nguyên mẫu này.

C.Tạo chương trình đầu tiên

Tạo một tệp Python, chẳng hạn quick_start.py, rồi chép đoạn mã tối thiểu 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 mã tạo một hàm bất đồng bộ, gọi query() và in từng thông báo trả về. anyio.run(main) là điểm khởi chạy chương trình.

README không ghi một lệnh cụ thể để chạy tệp ví dụ. Với một tệp Python thông thường, bạn có thể chạy từ thư mục chứa tệp bằng lệnh phổ thông:

Terminal
python quick_start.py

Khi chạy, chương trình sẽ nhận các message từ agent và in ra màn hình. Nếu bạn muốn chỉ in phần văn bản của câu trả lời, dùng các kiểu message như ví dụ dưới đây:

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 phải nằm trong một hàm bất đồng bộ như main() ở ví dụ trước. Người mới thường vấp ở chỗ gọi async for bên ngoài hàm async hoặc quên anyio.run(main).

D.Thêm tùy chọn cho agent

Bạn có thể đặt system prompt và giới hạn số lượt xử lý:

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)

system_prompt định hướng vai trò của agent. max_turns giới hạn số lượt. Khi thử nghiệm, giới hạn lượt giúp bạn dễ dự đoán thời gian và hành vi của chương trình.

Để chỉ định thư mục làm việc, dùng đường dẫn chuỗi hoặc Path:

Python
from pathlib import Path

options = ClaudeAgentOptions(
    cwd="/path/to/project"
)

Đường dẫn trong README là ví dụ. Hãy thay bằng thư mục dự án thật. Nếu dùng Windows, cần kiểm tra cách viết đường dẫn phù hợp với Python; README không cung cấp một ví dụ Windows cụ thể.

E.Cấp quyền cho công cụ

Ví dụ dưới đây cho phép tự động chấp thuận Read, Write và Bash, đồng thời tự động chấp thuận chỉnh sửa tệp:

Python
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode='acceptEdits'
)

async for message in query(
    prompt="Create a hello.py file",
    options=options
):
    pass

allowed_tools là danh sách cho phép tự động. Nó không phải danh sách công cụ duy nhất mà Claude nhìn thấy. permission_mode quyết định cách xử lý các trường hợp còn lại. Chỉ nên cấp quyền đúng với việc cần làm, nhất là khi có Bash hoặc Write.

F.Thêm custom tool và hook

Với ClaudeSDKClient, bạn có thể tạo một tool ngay trong ứng dụng:

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)

Tool nhận args, rồi trả về nội dung dạng danh sách. Tên được cho phép trong allowed_tools phải khớp mẫu MCP mà README minh họa. Nếu đổi tên server hoặc tool, hãy kiểm tra lại tên quyền tương ứng.

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

Cách kiểm tra đơn giản nhất là chạy ví dụ query() với prompt What is 2 + 2?. Nếu chương trình không báo lỗi import, không báo thiếu CLI và in được các message, SDK đã được cài và gọi được agent.

Khi cần kiểm tra nội dung dễ đọc hơn, dùng AssistantMessage và TextBlock để chỉ in văn bản. Kết quả mong đợi là một câu trả lời văn bản từ Claude, thay vì chỉ nhìn thấy cấu trúc object của message.

Với custom tool, chạy prompt Greet Alice. Agent cần gọi tool greet, sau đó chương trình nhận message qua receive_response(). Kết quả trong tool là nội dung chào người dùng.

Nếu chạy thất bại, phần lỗi trong README giúp phân loại nguyên nhân. CLINotFoundError cho biết không tìm thấy Claude Code. CLIConnectionError liên quan kết nối. ProcessError có mã thoát. ResultError cho biết CLI trả về kết quả lỗi cuối cùng. CLIJSONDecodeError liên quan việc phân tích phản hồi JSON.

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

A.Chủ shop muốn tạo bản nháp phản hồi khách hàng

Chủ shop có thể viết chương trình nhận nội dung câu hỏi của khách rồi gửi cho query() với system prompt định hướng trợ lý chăm sóc khách hàng. Chương trình in từng message để hiển thị phản hồi.

Ví dụ prompt có thể là Viết câu trả lời ngắn, lịch sự cho khách hỏi về thời gian giao hàng.. SDK sẽ trả về phản hồi dạng message. README không cung cấp kết nối trực tiếp với sàn thương mại điện tử, nên phần nhập câu hỏi và gửi kết quả vào hệ thống bán hàng cần bạn tự xây thêm.

B.Nhân viên văn phòng muốn xử lý tệp trong một thư mục

Bạn có thể đặt cwd vào thư mục dự án và cấp các công cụ phù hợp:

Python
options = ClaudeAgentOptions(
    cwd="/path/to/project",
    allowed_tools=["Read", "Write"]
)

Prompt mẫu là Đọc các tệp trong thư mục làm việc và tạo bản tóm tắt vào một tệp mới.. Agent có thể dùng Read và Write theo quyền đã cấu hình. Hãy kiểm tra kết quả trước khi chia sẻ, vì README chỉ mô tả khả năng công cụ chứ không cam kết độ chính xác của nội dung.

C.Lập trình viên mới muốn tạo tệp mẫu

Một lập trình viên có thể dùng prompt Create a hello.py file cùng cấu hình Read, Write và Bash trong ví dụ của README. cwd giúp agent làm việc đúng trong dự án.

Nếu chỉ muốn thử tạo tệp mà không cho chạy lệnh, bạn có thể bỏ Bash khỏi allowed_tools. Ngược lại, nếu cần agent chạy lệnh, hãy đọc kỹ cách permission_mode và disallowed_tools được dùng trong dự án của mình.

D.Đội phát triển muốn chặn lệnh nguy hiểm

Đội phát triển có thể dùng hook PreToolUse để kiểm tra lệnh Bash trước khi Claude chạy. README minh họa việc từ chối mọi lệnh có chứa foo.sh và cho phép lệnh echo 'Hello from hooks example!'.

Đây là cách phù hợp để đặt quy tắc cố định trong mã nguồn. Bạn có thể bắt đầu từ HookMatcher(matcher="Bash", hooks=[check_bash_command]), sau đó thay mẫu kiểm tra bằng quy tắc thật của dự án.

Quyền của agent nên được thiết kế như quyền của một nhân viên mới: đủ để làm việc, nhưng không mặc nhiên được chạm vào mọi thứ.

Ô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

README yêu cầu Python 3.10 trở lên. Nếu pip không cài được package hoặc chương trình lỗi do phiên bản, hãy kiểm tra python --version và chuyển sang Python đáp ứng yêu cầu.

B.Không tìm thấy Claude Code CLI

SDK mặc định tự kèm CLI. Nếu vẫn gặp CLINotFoundError, kiểm tra package đã cài đúng môi trường Python chưa. Khi dùng CLI hệ thống, cài bằng lệnh trong README hoặc truyền cli_path trỏ tới đường dẫn thật.

C.Gọi async sai cách

query() là hàm async và trả về AsyncIterator. Bạn cần gọi nó bên trong hàm async, dùng async for, rồi khởi chạy bằng anyio.run(main). Không nên chuyển đoạn async for ra ngoài hàm async.

D.Agent không chạy được công cụ như mong muốn

allowed_tools chỉ tự động chấp thuận công cụ được liệt kê, không xóa các công cụ khác. Kiểm tra lại permission_mode, can_use_tool và disallowed_tools. Đồng thời xác nhận tên MCP tool, chẳng hạn mcp__tools__greet, khớp với cấu hình server.

E.Chương trình dừng với lỗi tiến trình hoặc kết quả

Dùng các exception được SDK cung cấp để in nguyên nhân. ProcessError có exit_code; ResultError có các trường như subtype, terminal_reason, api_error_status, result hoặc errors. Không nên chỉ bắt một lỗi chung rồi bỏ qua thông tin chẩn đoán.

Hãy xem allowed_tools, permission_mode và disallowed_tools là cấu hình an toàn quan trọng. Read, Write và Bash có thể tác động trực tiếp đến dự án. Tư liệu được cung cấp không nêu chi tiết API key, tài khoản hay chi phí, nên cần kiểm tra cấu hình Claude Code trước khi đưa ứng dụng vào sử dụng thật.

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

Nên dùng nếu bạn đã có ứng dụng Python và muốn tích hợp Claude Agent bằng mã nguồn thay vì điều khiển thủ công qua giao diện. SDK có API khởi đầu ngắn, hỗ trợ phản hồi bất đồng bộ, cấu hình thư mục, quyền công cụ, custom tool, MCP nội bộ và hook.

Khả năng chạy custom tool trong cùng tiến trình là điểm mạnh rõ rệt. Nó giúp giảm việc quản lý subprocess, giảm overhead IPC, đơn giản hóa triển khai và thuận tiện hơn khi gỡ lỗi. Việc có các kiểu message và exception riêng cũng giúp chương trình dễ xử lý kết quả có cấu trúc.

Giới hạn là README không mô tả đầy đủ cách xác thực, API key, chi phí, chính sách dữ liệu hoặc quy trình triển khai sản phẩm. Bạn cũng phải tự thiết kế lớp giao diện, lưu trữ, giám sát và kiểm soát quyền cho ứng dụng của mình. Nếu chỉ cần hỏi đáp thủ công, dùng Claude Code trực tiếp có thể đơn giản hơn. Nếu cần một framework agent khác, một mô hình chạy hoàn toàn cục bộ hoặc một hệ thống không phụ thuộc Claude Code CLI, repo này có thể không phải lựa chọn phù hợp.

4.6/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?

Repo dùng giấy phép MIT. Tuy nhiên, tư liệu được cung cấp không nói rõ chi phí sử dụng Claude, API hay Claude Code, nên chưa thể kết luận toàn bộ việc dùng 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 cho biết Claude Code CLI được tự động đóng gói cùng package và SDK dùng bản đi kèm theo mặc định. Bạn chỉ cần cài riêng nếu muốn dùng bản toàn hệ thống hoặc một phiên bản cụ thể.

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

Cần Python 3.10 trở lên. Đây là yêu cầu được ghi rõ trong README.

Có cần GPU không?

README không nêu yêu cầu GPU hay phần cứng đặc biệt. Tư liệu chỉ ghi yêu cầu Python 3.10 trở lên.

Có chạy được trên Windows không?

Quy trình phát hành của repo có xây wheel cho macOS, Linux và Windows. Tuy nhiên, README cài đặt cơ bản không đưa hướng dẫn Windows riêng.

Có cần API key hoặc tài khoản riêng không?

Tư liệu được cung cấp không nêu API key, biến môi trường hoặc yêu cầu tài khoản cụ thể. Bạn cần kiểm tra tài liệu Claude Code và cấu hình môi trường trước khi chạy ứng dụng thật.

SDK khác gì so với MCP server bên ngoài?

SDK cho phép tạo MCP server chạy ngay trong cùng tiến trình Python. README nêu các lợi ích là không phải quản lý subprocess, giảm IPC, triển khai đơn giản hơn, dễ gỡ lỗi hơn và gọi hàm trực tiếp có type hint.

Chuyển nhanh tới mục

  1. I.claude-agent-sdk-python làm được gì
  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 Python
    3. C.Tạo chương trình đầu tiên
    4. D.Thêm tùy chọn cho agent
    5. E.Cấp quyền cho công cụ
    6. F.Thêm custom tool và hook
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ shop muốn tạo bản nháp phản hồi khách hàng
    2. B.Nhân viên văn phòng muốn xử lý tệp trong một thư mục
    3. C.Lập trình viên mới muốn tạo tệp mẫu
    4. D.Đội phát triển muốn chặn lệnh nguy hiểm
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Python thấp hơn phiên bản yêu cầu
    2. B.Không tìm thấy Claude Code CLI
    3. C.Gọi async sai cách
    4. D.Agent không chạy được công cụ như mong muốn
    5. E.Chương trình dừng với lỗi tiến trình hoặc kết quả
  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ỏ.