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.

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.

Triển khai cấu trúc cơ bản của agent:
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 responseKiể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).

Định nghĩa schema cho read_file và logic điều hướng:
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 modelKiể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.

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:
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).

Triển khai run_bash và lớp bảo mật:
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.
-
Thiết lập ngữ cảnh: Tạo file
CLAUDE.mdtạ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`. -
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".
-
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.

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ính | Tham số đầu vào bắt buộc |
|---|---|---|
list_files | Liệt kê cấu trúc thư mục để định hướng | path |
read_file | Đọc nội dung file kèm số dòng | path |
edit_file | Chỉnh sửa code bằng thay thế chuỗi | path, old_str, new_str |
run_bash | Thực thi lệnh terminal (test, build) | command |
Xử lý sự cố thường gặp
| Triệu chứng / Dòng lỗi | Nguyên nhân kỹ thuật | Cách khắc phục |
|---|---|---|
| "Path escapes workspace" | Agent cố truy cập file ngoài thư mục dự án | Kiểm tra logic resolve_workspace_path |
| "old_str not found" | Model trích dẫn sai hoặc file đã thay đổi | Yêu cầu agent gọi lại read_file để lấy ngữ cảnh mới |
| Vòng lặp vô tận | Agent thử đi thử lại một lệnh sai | Thiế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
- How to Build an Agent — Amp
- Tutorial: Build a Tool-Using Agent — Claude Platform Docs
- How to Build a Coding Agent: Free Workshop — Geoffrey Huntley
- Build a Coding Agent from Scratch: The Complete Python Tutorial — Sid Bharath
- mini-coding-agent — Sebastian Raschka (GitHub)
- Components of a Coding Agent — Sebastian Raschka
- Pi, Minimal and Performant — Earendil
- Designing Agentic Loops — Simon Willison
- What You Only Learn by Building a Coding Agent From Scratch — QuillCode