Bỏ qua điều hướng

Hướng dẫn tự xây dựng một coding agent tối giản

Hướng dẫn xây dựng coding agent bằng Python để tự động hóa lập trình qua vòng lặp ReAct. Triển khai bộ công cụ đọc, ghi, sửa và chạy shell an toàn.

Tuan Tran Van
9 phút đọc
Mục lục (9 phần)
  1. Bước 1 — Dựng vòng lặp hội thoại với model
  2. Bước 2 — Khai báo công cụ đầu tiên và bắt tín hiệu tool_use
  3. Bước 3 — Hoàn thiện bộ công cụ đọc, ghi và sửa file
  4. Bước 4 — Cho agent chạy lệnh shell kèm lớp phê duyệt
  5. Bước 5 — Chạy agent trên một repo thật và kiểm chứng kết quả
  6. Bảng tra cứu bộ công cụ tối thiểu
  7. Xử lý sự cố thường gặp
  8. Bước tiếp theo
  9. Tài liệu tham khảo

Bạn sẽ có một coding agent chạy trên terminal: nó tự đọc mã nguồn, thực thi lệnh shell, chỉnh sửa file và sửa lỗi dựa trên kết quả kiểm thử.

Agent vận hành qua một vòng lặp phản hồi liên tục, nhờ đó tự sửa lỗi mà không cần bạn can thiệp từng bước.

Điều kiện tiên quyết: Python 3.10 trở lên, SDK Anthropic (pip install anthropic) và một API key đặt trong biến môi trường ANTHROPIC_API_KEY. Toàn bộ ví dụ dưới đây dùng model Claude Sonnet 5 làm bộ suy luận chính.

Mã nguồn hoàn chỉnh của dự án mẫu trong bài có sẵn trên GitHub: camnangai-public-sources/coding-agent-demo.

Một coding agent tối giản chạy trong terminal, ghép từ ba phần: mô hình ngôn ngữ, vòng lặp và bộ công cụ

Bước 1 — Dựng vòng lặp hội thoại với model

Cài đặt thư viện: pip install anthropic. Agent cần một lớp quản lý lịch sử hội thoại để duy trì trạng thái giữa các lượt gọi model.

Vòng lặp hội thoại: lịch sử được gửi lên mô hình, mô hình trả lời, câu trả lời nối vào lịch sử rồi lặp lại

Triển khai cấu trúc cơ bản của agent:

python
import anthropic
import os
 
class Agent:
    def __init__(self):
        self.client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
        self.model = "claude-sonnet-5"
        self.history = []
 
    def run_inference(self, system_prompt, tools):
        response = self.client.messages.create(
            model=self.model,
            max_tokens=4096,
            system=system_prompt,
            tools=tools,
            messages=self.history,
            thinking={"type": "adaptive"},  # model tự quyết định mức suy luận cho từng task
        )
        return response

Kiểm chứng: Gọi run_inference với một nội dung văn bản. Terminal phải in ra phản hồi từ Claude để xác nhận kết nối SDK và API key hoạt động bình thường.

Giải thích: Agent thực chất là một vòng lặp gửi liên tục lịch sử hội thoại. Model không lưu trữ dữ liệu; toàn bộ ngữ cảnh được phía client gửi lên trong mỗi lượt tương tác để model "ghi nhớ" các bước đã thực hiện.

Bước 2 — Khai báo công cụ đầu tiên và bắt tín hiệu tool_use

Model không trực tiếp thao tác với ổ cứng. Bạn phải định nghĩa JSON Schema để model biết cách gửi yêu cầu thực thi đến client qua cơ chế ReAct (Reason, Act, Observe).

Chu kỳ ReAct: mô hình phát tín hiệu tool_use, client thực thi công cụ, kết quả tool_result quay lại cho mô hình suy luận tiếp

Định nghĩa schema cho read_file và logic điều hướng:

python
TOOLS = [{
    "name": "read_file",
    "description": "Đọc nội dung file kèm số dòng để phục vụ việc chỉnh sửa.",
    "input_schema": {
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "Đường dẫn file tương đối"}
        },
        "required": ["path"]
    }
}]
 
def execute_tool(tool_name, tool_input):
    if tool_name == "read_file":
        return read_file(tool_input["path"])
    # Các tool khác sẽ được bổ sung ở bước sau
    return "Error: Unknown tool"
 
# Logic ReAct trong vòng lặp chính
response = agent.run_inference(SYSTEM_PROMPT, TOOLS)
if response.stop_reason == "tool_use":
    for block in response.content:
        if block.type == "tool_use":
            print(f"→ Thực thi công cụ: {block.name}")
            result = execute_tool(block.name, block.input)
            # Gửi kết quả (Observe) ngược lại cho model

Kiểm chứng: Yêu cầu agent "Đọc file main.py". Model phải trả về stop_reason == "tool_use" kèm đúng tên tool và tham số path.

Terminal in ra dòng thực thi công cụ read_file với tham số path, sau đó là nội dung main.py kèm số dòng

Giải thích: Model chỉ phát tín hiệu yêu cầu. Phía client chịu trách nhiệm đọc tín hiệu, thực thi logic Python thực tế và trả kết quả về để model tiếp tục suy luận.

Bước 3 — Hoàn thiện bộ công cụ đọc, ghi và sửa file

Dùng chiến lược thay thế chuỗi để chỉnh sửa file chính xác hơn so với việc ghi đè toàn bộ nội dung.

Triển khai bộ công cụ quản lý file:

python
from pathlib import Path
 
WORKSPACE = Path.cwd().resolve()
 
def resolve_workspace_path(path_str):
    resolved = (WORKSPACE / path_str).resolve()
    if WORKSPACE not in resolved.parents and resolved != WORKSPACE:
        raise ValueError(f"Path escapes workspace: {path_str}")
    return resolved
 
def list_files(path="."):
    safe_path = resolve_workspace_path(path)
    return [str(p.relative_to(WORKSPACE)) for p in safe_path.rglob("*") if p.is_file()]
 
def read_file(path, offset=0, limit=500):
    safe_path = resolve_workspace_path(path)
    lines = safe_path.read_text().splitlines()
    subset = lines[offset : offset + limit]
    # Trả về kèm số dòng giúp model định vị chính xác để edit_file
    return "\n".join(f"{i + offset + 1} | {line}" for i, line in enumerate(subset))
 
def edit_file(path, old_str, new_str):
    safe_path = resolve_workspace_path(path)
    content = safe_path.read_text()
    if content.count(old_str) != 1:
        return "Error: old_str không xuất hiện duy nhất một lần. Hãy cung cấp ngữ cảnh cụ thể hơn."
    new_content = content.replace(old_str, new_str)
    safe_path.write_text(new_content)
    return "Success"

Kiểm chứng: Yêu cầu agent "Tìm và sửa một comment trong file X". Kiểm tra file sau khi lưu để đảm bảo chỉ có dòng đích bị thay đổi.

Giải thích: Trả về số dòng trong read_file giúp model giảm sai sót khi trích xuất old_str. Việc giới hạn WORKSPACE là lớp bảo mật cơ bản ngăn agent can thiệp vào file hệ thống nhạy cảm.

Bước 4 — Cho agent chạy lệnh shell kèm lớp phê duyệt

Công cụ run_bash cho phép agent chạy lệnh test hoặc build. Đây là công cụ nguy hiểm nhất, bắt buộc phải có cơ chế phê duyệt thủ công (human-in-the-loop).

Ranh giới an toàn khi cho agent chạy shell: agent đề xuất lệnh, lớp phê duyệt của con người đứng chắn ở giữa, và subprocess không phải là sandbox

Triển khai run_bash và lớp bảo mật:

python
import subprocess
 
BLOCKED_COMMANDS = ["rm -rf /", "rm -rf *", "env", "curl", "wget"]
 
def run_bash(command):
    if any(blocked in command for blocked in BLOCKED_COMMANDS):
        return "Error: Lệnh bị cấm vì lý do bảo mật (chặn rò rỉ dữ liệu hoặc xóa file)."
 
    confirm = input(f"\n[PHÊ DUYỆT] Agent muốn chạy: {command}. Đồng ý? (y/n): ")
    if confirm.lower() != 'y':
        return "User denied execution."
 
    try:
        result = subprocess.run(
            command, shell=True, capture_output=True, text=True, timeout=60
        )
        return f"STDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}"
    except subprocess.TimeoutExpired:
        return "Error: Command timed out (60s)."
 
def execute_tool(tool_name, tool_input):
    """Hàm điều hướng tích hợp toàn bộ toolset"""
    if tool_name == "read_file": return read_file(tool_input["path"])
    if tool_name == "list_files": return list_files(tool_input.get("path", "."))
    if tool_name == "edit_file": return edit_file(tool_input["path"], tool_input["old_str"], tool_input["new_str"])
    if tool_name == "run_bash": return run_bash(tool_input["command"])
    return "Error: Unknown tool"

Kiểm chứng: Yêu cầu agent chạy pytest. Xác nhận agent nhận được kết quả lỗi hoặc thành công từ stderr/stdout để tiếp tục bước sửa lỗi.

Giải thích: subprocess không phải là sandbox. Để an toàn, hãy vận hành agent trong Docker container không có quyền truy cập internet nhằm tránh rò rỉ mã nguồn (exfiltration).

Bước 5 — Chạy agent trên một repo thật và kiểm chứng kết quả

Agent cần bối cảnh dự án (live repo context) để giảm số lượt đoán.

  1. Thiết lập ngữ cảnh: Tạo file CLAUDE.md tại root dự án:

    markdown
    # Hướng dẫn dự án
     
    - Tech stack: FastAPI, Pydantic v2.
    - Quy tắc code: Luôn dùng Type Hints, tuân thủ PEP8.
    - Kiểm thử: Dùng `pytest`. Chạy test sau mỗi lần sửa `edit_file`.
  2. Thực thi nhiệm vụ: Khởi chạy agent và ra lệnh: "Viết thêm một endpoint GET /health vào main.py và chạy test cho đến khi pass".

  3. Khởi chạy CLI: python agent_script.py --cwd ./target_repo.

Kiểm chứng: Quan sát agent tự đọc thông báo lỗi từ run_bash, dùng edit_file để sửa code và lặp lại cho đến khi lệnh test trả về thành công.

Agent đọc CLAUDE.md và test_main.py, dùng edit_file thêm endpoint /health, xin phê duyệt chạy pytest, và kết thúc với hai test đều pass

Giải thích: Khác biệt của agent nằm ở vòng lặp tự kiểm chứng. Nó không chỉ sinh mã mà còn đảm bảo mã đó chạy được trong môi trường thực tế của bạn.

Bảng tra cứu bộ công cụ tối thiểu

Tên công cụCông dụng chínhTham số đầu vào bắt buộc
list_filesLiệt kê cấu trúc thư mục để định hướngpath
read_fileĐọc nội dung file kèm số dòngpath
edit_fileChỉnh sửa code bằng thay thế chuỗipath, old_str, new_str
run_bashThực thi lệnh terminal (test, build)command

Xử lý sự cố thường gặp

Triệu chứng / Dòng lỗiNguyên nhân kỹ thuậtCách khắc phục
"Path escapes workspace"Agent cố truy cập file ngoài thư mục dự ánKiểm tra logic resolve_workspace_path
"old_str not found"Model trích dẫn sai hoặc file đã thay đổiYêu cầu agent gọi lại read_file để lấy ngữ cảnh mới
Vòng lặp vô tậnAgent thử đi thử lại một lệnh saiThiết lập tham số max_steps (ví dụ: tối đa 10 lượt)

Bước tiếp theo

Triển khai ngay cơ chế (context compaction). Khi lịch sử hội thoại vượt ngưỡng, yêu cầu model tóm tắt toàn bộ tiến trình và các file đã sửa, sau đó ghi đè lịch sử cũ bằng bản tóm tắt này để duy trì hiệu suất và tiết kiệm chi phí.

Tài liệu tham khảo

Tự kiểm tra

Ba câu hỏi ngắn để bạn xem mình đã nắm được ý chính của bài chưa.

  1. Cốt lõi của một coding agent là gì?
  2. Agent nên sửa một file đã có như thế nào?
  3. Nên thêm quyền chạy lệnh shell một cách an toàn ra sao?

Chia sẻ bài viết

ZaloX / TwitterFacebookLinkedIn

Thuật ngữ AI