Claude Code: Tạo agent tự tìm và sửa lỗi theo tài liệu

Hôm nay mình sẽ hướng dẫn anh em tạo agent sửa file utils.py bằng Claude Code qua SDK, từ cài đặt đến kiểm tra thay đổi. Agent SDK là bộ thư viện để anh em viết chương trình giao việc cho agent. Agent ở đây là chương trình tự dùng tool để đọc file, sửa file và làm xong việc mình giao.

Mình đọc tài liệu chính thức rồi gom lại các thao tác để anh em làm theo. Mình chưa tự chạy thử, nên phần kết quả bên dưới dựa trên những gì tài liệu mô tả. Cuối bài này anh em sẽ có một file Python nhỏ, chạy lên là agent tự đọc và sửa lỗi trong file khác.

Bước 1: Anh em chuẩn bị Claude Code qua SDK

Mình chọn luồng Python trên macOS hoặc Linux, để anh em chỉ cần theo các thao tác dưới đây và không phải chuyển qua lại giữa những cách cài tài liệu liệt kê. Trước khi làm, anh em cần Python 3.10+ và tài khoản Anthropic.

Anh em mở terminal, tức cửa sổ gõ lệnh, rồi nhập:

mkdir my-agent
cd my-agent

Thư mục riêng giúp anh em biết nơi agent đọc và sửa file, vì SDK mặc định truy cập được các file trong thư mục chạy chương trình và những thư mục nằm bên trong.

Anh em tạo môi trường ảo bằng venv rồi cài SDK bằng các lệnh sau:

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Môi trường ảo (venv) là một thư mục riêng để cài gói Python cho bài này, không lẫn với các project khác trên máy. Lệnh source .venv/bin/activate bật môi trường đó lên trước khi anh em cài SDK. Theo tài liệu, SDK Python đã đóng gói sẵn bản Claude Code, nên phần lớn lần cài không cần cài công cụ riêng.

Anh em lấy API key trong Claude Console, rồi đặt key trong chính terminal sẽ chạy agent bằng lệnh dưới đây, trước khi chuyển sang tạo các file cho bài thực hành. API key là chuỗi chương trình dùng để đăng nhập với dịch vụ.

export ANTHROPIC_API_KEY=your-api-key

Anh em thay phần your-api-key bằng chuỗi lấy từ tài khoản của mình trước khi thực hiện lệnh, vì chữ trong mẫu chỉ cho biết vị trí anh em cần điền key. Anh em nhớ thay đúng key của mình trước khi chạy lệnh trong terminal nhé. SDK sẽ đọc key từ chính cửa sổ terminal đang chạy agent.

Bước 2: Anh em tạo file lỗi và agent

Anh em tạo file utils.py trong thư mục vừa chuẩn bị, rồi dán nguyên đoạn code mẫu dưới đây để agent có file cần đọc và có lỗi cụ thể để sửa. Tài liệu cố ý cài hai lỗi vào file này để agent có cái mà sửa.

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

Theo tài liệu, calculate_average([]) lỗi chia cho không, còn get_user_name(None) lỗi TypeError. Mình giữ nguyên code mẫu của tài liệu để anh em dán vào đúng file, khỏi lo chép lệch.

Anh em tiếp tục tạo file agent.py trong cùng thư mục, rồi dán chương trình mẫu bên dưới để giao việc kiểm tra lỗi và nhận thông tin khi agent đang làm việc. Chương trình này nhờ agent tìm và sửa những lỗi khiến chương trình dừng đột ngột.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Agentic loop: streams messages as Claude works
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Auto-approve these tools
            permission_mode="acceptEdits",  # Auto-approve file edits
        ),
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

Trước khi chạy, mình giải thích nhanh prompt: đó là yêu cầu bằng chữ mình giao cho agent. Ở đây yêu cầu là tìm lỗi khiến chương trình dừng đột ngột và sửa luôn những lỗi tìm được.

Anh em xem allowed_tools để biết agent được dùng sẵn những tool nào. Danh sách này cho phép sẵn Read, Edit và Glob để agent đọc, sửa và tìm file, còn thiết lập permission_mode="acceptEdits" tự chấp nhận thay đổi mà agent thực hiện trong file.

Đoạn code này nhận từng thông báo khi Claude làm việc, rồi in lời giải thích, tên tool và dòng kết quả cuối. Anh em không cần hiểu từng dòng code, chỉ cần nhớ yêu cầu ở prompt và quyền sửa file ở permission_mode.

Bước 3: Anh em chạy agent rồi kiểm tra file

Giờ mình sẽ chỉ anh em chạy agent từ terminal lúc nãy, nơi đã bật môi trường Python và đặt key. Anh em nhớ lưu file. Khi các file đã được lưu, anh em chạy lệnh nguyên văn dưới đây trong terminal đang mở:

python agent.py

Theo tài liệu, chương trình sẽ in phần giải thích và công cụ agent sử dụng, rồi kết thúc bằng Done: success khi xong nhiệm vụ, để anh em theo dõi ngay trong terminal. Mình chưa tự chạy thử để xác nhận kết quả trên máy.

Anh em mở lại utils.py sau khi chương trình kết thúc để xem những chỗ agent đã sửa, rồi đối chiếu với lỗi danh sách rỗng và lỗi không có người dùng. Tài liệu mô tả code sẽ có xử lý các trường hợp này.

Mình khuyên anh em mở utils.py ra đọc kỹ chỗ agent sửa, vì Done: success chỉ cho biết agent chạy xong chứ chưa chắc sửa đúng ý mình. File sau khi sửa cho anh em thấy các thay đổi cụ thể.

Sau lượt thực hành này, tài liệu còn đưa ra yêu cầu thêm chú thích cho hàm hoặc bổ sung kiểu dữ liệu, để anh em tiếp tục giao việc cho chương trình. Mình giữ yêu cầu tìm lỗi cho lượt đầu để dễ đối chiếu.

Lỗi hay gặp

Nếu chương trình báo Not logged in hoặc Invalid API key, anh em kiểm tra biến môi trường ANTHROPIC_API_KEY trong terminal, vì SDK đọc key từ cửa sổ chạy agent. Anh em kiểm tra chỗ đặt key trước khi chạy lại chương trình.

Nếu anh em lưu key trong .env, SDK không tự đọc file đó. Với luồng đang làm, anh em dùng lại lệnh đặt key ở trên trong terminal hiện tại rồi chạy chương trình, thay vì cho rằng việc lưu file đã đủ để đăng nhập.

Nếu lỡ package Python không kèm sẵn Claude Code, anh em cài riêng theo hướng dẫn mà tài liệu dẫn tới. Tài liệu lấy ARM64 Windows làm ví dụ cho trường hợp pip cài bản mã nguồn thay vì bản đóng sẵn cho nền tảng.

Sau khi cài riêng, SDK sẽ tìm chương trình qua PATH, tức danh sách thư mục máy dùng để tìm lệnh khi anh em gõ trong terminal. Agent được sửa file ngay khi chạy, nên mình khuyên anh em đọc lại từng thay đổi.