Đưa Logic Của Bạn Vào Vòng Lặp Agentic Của Codex

Hầu hết chúng ta tùy chỉnh Codex thông qua prompts (lời nhắc). Chúng ta mô tả nhiệm vụ, đưa ra chỉ dẫn và yêu cầu kết quả mong muốn. Nhưng đôi khi, prompting không đủ. Bạn muốn can thiệp sâu hơn vào quá trình thực thi? Câu trả lời nằm ở Codex hooks – cơ chế cho phép gắn logic tùy chỉnh vào các giai đoạn khác nhau của một phiên làm việc Codex. Bài viết này sẽ khám phá khái niệm, giải thích vị trí của chúng trong vòng lặp agentic và minh họa qua một case study thực tế.

Hiểu Về Codex Hooks

Khi Codex xử lý một nhiệm vụ, nó trải qua một vòng lặp agentic – một chuỗi các bước từ phân tích vấn đề, gọi công cụ, đến hoàn thành nhiệm vụ. Toàn bộ quá trình này có thể xem như một vòng đời (lifecycle), và tại các điểm khác nhau, Codex phát ra các sự kiện (events) với tên riêng:

• SessionStart: Phát ra khi phiên làm việc bắt đầu
• PreToolUse: Phát ra ngay trước khi Codex gọi một công cụ
• PostToolUse: Phát ra sau khi công cụ hoàn thành
• Stop: Phát ra khi Codex chuẩn bị kết thúc phản hồi
• SessionEnd: Phát ra khi phiên Codex kết thúc

Hook là cơ chế cho phép chúng ta gắn logic của riêng mình vào các sự kiện này. Ví dụ, dùng SessionStart để nạp thêm ngữ cảnh, PreToolUse để kiểm tra lệnh trước khi thực thi, hoặc Stop để xác thực kết quả.

Khi cấu hình một hook, bạn cần trả lời ba câu hỏi cơ bản:

• Tại điểm nào trong vòng đời nó nên chạy?
• Trong điều kiện nào nó nên kích hoạt tại điểm đó?
• Hành động nào nó nên thực thi?

Trong Codex, ba yếu tố này tương ứng với event (sự kiện), matcher (bộ so khớp) và handler (bộ xử lý) – đây chính là mô hình cơ bản đằng sau Codex hooks.

Case Study: Thêm Cổng Kiểm Soát Chất Lượng Cho Nghiên Cứu Sâu

Trong case study này, chúng ta xây dựng một quy trình nghiên cứu sâu nhỏ với Codex. Cụ thể, yêu cầu Codex nghiên cứu xu hướng mới nhất về một chủ đề nhất định, thực hiện tìm kiếm web và xác định ba xu hướng quan trọng trong 90 ngày qua, sau đó trả về một bản tóm tắt nghiên cứu có cấu trúc.

Để minh họa khái niệm hook, chúng ta thêm một bước kiểm tra chất lượng ngay trước khi Codex hoàn thành. Bước này sẽ xác minh rằng bản tóm tắt có đủ nguồn và các nguồn đó đến từ nhiều tên miền hợp lý. Nếu vượt qua, Codex kết thúc; nếu không, hook sẽ gửi phản hồi về cho Codex để tiếp tục nghiên cứu trong cùng một phiên.

Chuẩn Bị Nhiệm Vụ Nghiên Cứu

Đầu tiên, chúng ta tạo một mẫu prompt:

# Deep research task
Research **{{TOPIC}}**.
Use sources published from **{{WINDOW_START}}** through **{{WINDOW_END}}**,
inclusive. Identify the three most important trends in that period and prepare
a concise, source-backed brief.
Return a concise, source-backed research brief that follows the supplied schema.

Đồng thời, chuẩn bị một JSON schema để định dạng đầu ra mong muốn:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["summary", "trends"],
  "properties": {
    "summary": {"type": "string"},
    "trends": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["title", "summary", "sources"],
        "properties": {
          "title": {"type": "string"},
          "summary": {"type": "string"},
          "sources": {
            "type": "array",
            "items": {"type": "string"}
          }
        }
      }
    }
  }
}

Lưu file này thành schemas/research_brief.schema.json – đây cũng chính là cấu trúc mà hook của chúng ta sẽ kiểm tra.

Thiết Kế Cổng Kiểm Soát Chất Lượng

Hook sẽ kiểm tra ba điều kiện sau:

• Mỗi xu hướng phải có ít nhất hai nguồn
• Bản tóm tắt phải có tổng cộng ít nhất mười nguồn duy nhất
• Các nguồn phải đến từ ít nhất năm tên miền duy nhất

Vì chỉ có thể kiểm tra sau khi Codex hoàn thành bản tóm tắt, chúng ta dùng Stop hook. Tạo script kiểm tra tại .codex/hooks/validate_research.py:

import json
import sys
from urllib.parse import urlparse

MIN_PER_TREND = 2
MIN_SOURCES = 10
MIN_DOMAINS = 5

event = json.load(sys.stdin)
brief = json.loads(event["last_assistant_message"])
errors = []
all_urls = set()

for number, trend in enumerate(brief["trends"], 1):
    urls = set(trend["sources"])
    all_urls.update(urls)
    if len(urls) < MIN_PER_TREND:
        errors.append(
            f"Trend {number} ('{trend['title']}') has {len(urls)} sources; "
            f"at least {MIN_PER_TREND} are required."
        )

if len(all_urls) < MIN_SOURCES:
    errors.append(
        f"Brief cites {len(all_urls)} unique sources; "
        f"at least {MIN_SOURCES} are required."
    )

domains = {urlparse(url).netloc for url in all_urls}
if len(domains) < MIN_DOMAINS:
    errors.append(
        f"Brief cites {len(domains)} unique domains; "
        f"at least {MIN_DOMAINS} are required."
    )

if errors:
    result = {
        "decision": "block",
        "reason": "Research brief failed quality checks.",
        "errors": errors,
    }
else:
    result = {
        "decision": "approve",
        "reason": "Research brief passed quality checks.",
        "errors": [],
    }

print(json.dumps(result, indent=2))

Tiếp theo, tạo file cấu hình .codex/config.toml để đăng ký hook:

[hooks.stop]
matcher = "last_assistant_message"
handler = ".codex/hooks/validate_research.py"

Ở đây, matcher hướng dẫn Codex chỉ chạy hook khi last_assistant_message chứa nội dung phù hợp (tức là bản tóm tắt nghiên cứu thay vì văn bản thường).

Chạy Phiên Codex

Chuẩn bị prompt đầu vào trong outputs/research_prompt.md với các tham số cụ thể, sau đó chạy lệnh sau:

codex exec --search --model gpt-5-codex --output-schema schemas/research_brief.schema.json \
  -o outputs/research_brief.json --json < outputs/research_prompt.md > outputs/run.jsonl

Một số điểm cần lưu ý:

• exec: chạy Codex không tương tác
• --search: cho phép agent truy cập tìm kiếm web
• --output-schema: cung cấp schema định nghĩa sẵn để ràng buộc đầu ra
• -o: lưu phản hồi vào file đích
• --json và >: xuất ra các sự kiện thực thi dạng JSONL để theo dõi

Trong quá trình thử nghiệm, Codex ban đầu tạo ba xu hướng với bảy nguồn duy nhất. Mỗi xu hướng có hơn hai nguồn, nhưng không đạt yêu cầu tổng cộng mười nguồn. Hook Stop hoạt động chính xác và gửi phản hồi:

"The brief needs broader corroboration. I'm adding at least three independent, in-window sources while preserving the same three evidence-supported trends."

Sau một vòng nữa, Codex tạo bản tóm tắt với 12 nguồn duy nhất từ 10 tên miền. Kết quả xác định ba xu hướng chính: sự trỗi dậy của các khuôn viên AI quy mô gigawatt, quyền truy cập năng lượng và giấy phép là rào cản hạ tầng, và xu hướng chuyển sang làm mát bằng chất lỏng. Hook chạy lại và lần này cho phép Codex hoàn thành.

Khi Nào Nên Dùng Hooks

Case study trên minh họa cách dùng Stop hook để kiểm tra kết quả. Quy trình thiết kế tương tự áp dụng cho các sự kiện khác:

• SessionStart: hữu ích khi cần nạp ngữ cảnh khi phiên bắt đầu
• PreToolUse: để kiểm tra hoạt động trước khi nó xảy ra
• PostToolUse: để xử lý kết quả sau khi gọi công cụ

Khi thiết kế hook, luôn tự hỏi ba câu hỏi: Điểm nào trong vòng đời? Điều kiện kích hoạt là gì? Hành động thực thi là gì? Đây chính là cách bạn thêm logic quyết định vào vòng lặp Codex – một công cụ mạnh mẽ để biến trợ lý AI trở thành một phần không thể thiếu trong quy trình làm việc của bạn, đặc biệt hữu ích cho các nhà phát triển Việt Nam khi xây dựng các quy trình tự động hóa phức tạp.