Codex bắt đầu hỗ trợ Subagents

• OpenAI Codex hỗ trợ workflow subagent, cho phép phân phối song song các tác vụ phức tạp cho nhiều agent chuyên biệt và hợp nhất kết quả thành một
• Chỉ tạo subagent khi người dùng yêu cầu rõ ràng; do mỗi agent sử dụng mô hình và công cụ độc lập nên mức tiêu thụ token tăng so với một agent đơn lẻ
• Có thể định nghĩa agent tùy chỉnh bằng tệp TOML để cấu hình riêng theo từng agent như mô hình, chế độ sandbox, máy chủ MCP, v.v.
• Cũng bao gồm tính năng thử nghiệm spawn_agents_on_csv, tạo hàng loạt worker agent với mỗi hàng trong tệp CSV là một đơn vị công việc
• Tài liệu chính thức hướng dẫn trực tiếp các mẫu kết hợp agent tùy chỉnh cho những kịch bản thực tế như review code, debug frontend, v.v.

---

Tổng quan và khả dụng của subagent

• Codex hỗ trợ workflow subagent, có thể spawn các agent chuyên biệt song song và thu thập kết quả thành một phản hồi duy nhất
• Đặc biệt hữu ích cho các tác vụ phức tạp đòi hỏi mức độ song song cao, như khám phá codebase hoặc lập kế hoạch triển khai tính năng nhiều bước
• Trong workflow subagent, cũng có thể định nghĩa agent tùy chỉnh với các thiết lập mô hình và chỉ dẫn khác nhau tùy theo tác vụ
• Trong bản phát hành Codex hiện tại, workflow subagent được bật mặc định
• Hiện có thể xem hoạt động của subagent trong ứng dụng Codex và CLI; khả năng hiển thị trong IDE Extension sẽ sớm được bổ sung
• Chỉ tạo subagent khi người dùng yêu cầu rõ ràng; vì mỗi subagent tự thực hiện các tác vụ mô hình và công cụ riêng nên tiêu thụ token nhiều hơn so với chạy một agent đơn lẻ

Workflow thông thường

• Codex xử lý orchestration giữa các agent: bao gồm tạo subagent mới, định tuyến chỉ dẫn tiếp theo, chờ kết quả và kết thúc thread của agent
• Khi nhiều agent đang chạy, Codex sẽ đợi đến khi tất cả kết quả yêu cầu sẵn sàng rồi trả về phản hồi hợp nhất
• Ví dụ prompt: yêu cầu tạo một agent cho từng hạng mục như vấn đề bảo mật, chất lượng code, bug, race condition, độ ổn định của test, khả năng bảo trì đối với PR hiện tại, rồi tóm tắt toàn bộ kết quả

Quản lý subagent

• Trong CLI, có thể dùng lệnh /agent để chuyển giữa các thread agent đang hoạt động và kiểm tra các thread đang chạy
• Cũng có thể yêu cầu trực tiếp Codex điều khiển, dừng hoặc kết thúc thread đã hoàn thành của subagent đang chạy

Phê duyệt và kiểm soát sandbox

• Subagent kế thừa chính sách sandbox hiện tại của người dùng
• Trong phiên CLI tương tác, yêu cầu phê duyệt từ các thread agent không hoạt động vẫn có thể hiển thị ngay cả khi đang dùng thread chính; lớp phủ phê duyệt sẽ hiển thị nhãn thread nguồn
  • Nhấn o để mở thread đó, rồi có thể phê duyệt, từ chối hoặc phản hồi
• Trong luồng không tương tác, không thể hiển thị phê duyệt mới, nên các tác vụ cần phê duyệt sẽ thất bại và lỗi được chuyển lên workflow cấp trên
• Khi tạo agent con, Codex áp dụng lại các runtime override đang hoạt động của lượt cha: gồm thay đổi qua /approvals hay các thiết lập tương tác như --yolo
  • Dù tệp agent tùy chỉnh được chọn có đặt mặc định khác, thiết lập của agent cha vẫn được ưu tiên
• Có thể override riêng cấu hình sandbox cho từng agent tùy chỉnh (ví dụ: đặt một agent cụ thể ở chế độ chỉ đọc)

Agent tùy chỉnh

• Codex cung cấp sẵn 3 loại agent tích hợp mặc định
  • default: agent fallback đa dụng
  • worker: agent thiên về thực thi tập trung vào triển khai và chỉnh sửa
  • explorer: agent thiên về đọc để khám phá codebase
• Khi định nghĩa agent tùy chỉnh, thêm tệp TOML độc lập vào ~/.codex/agents/ (cá nhân) hoặc .codex/agents/ (phạm vi dự án)
• Mỗi tệp định nghĩa một agent tùy chỉnh, và Codex tải tệp đó thành lớp cấu hình của phiên tạo agent
• Các trường bắt buộc phải có trong mọi tệp agent tùy chỉnh:
  • name, description, developer_instructions
• Các trường tùy chọn như nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config... sẽ kế thừa từ phiên cha nếu bị lược bỏ

Cấu hình toàn cục

• Cấu hình toàn cục cho subagent được định nghĩa trong phần [agents] của tệp configuration
• agents.max_threads: giới hạn trên số thread agent mở đồng thời (mặc định 6)
• agents.max_depth: độ sâu lồng nhau của agent được tạo (mặc định 1, chỉ cho phép tạo agent con trực tiếp, ngăn lồng sâu hơn)
• agents.job_max_runtime_seconds: timeout mặc định cho mỗi worker trong tác vụ spawn_agents_on_csv (nếu không đặt thì mặc định theo mỗi lần gọi là 1800 giây)
• Nếu tên agent tùy chỉnh trùng với agent tích hợp như explorer, thì agent tùy chỉnh sẽ được ưu tiên

Schema tệp agent tùy chỉnh

• name (string, bắt buộc): tên agent mà Codex dùng khi tạo hoặc tham chiếu tới agent
• description (string, bắt buộc): hướng dẫn dành cho con người về thời điểm Codex nên dùng agent này
• developer_instructions (string, bắt buộc): chỉ dẫn cốt lõi định nghĩa hành vi của agent
• nickname_candidates (string[], tùy chọn): danh sách nickname hiển thị cho agent được tạo
• Cũng có thể bao gồm các khóa config.toml khác được hỗ trợ như: model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config...
• Codex nhận diện agent bằng trường name; việc để tên tệp trùng với tên agent là quy ước đơn giản nhất, nhưng trường name mới là nguồn chân lý

Nickname hiển thị

• nickname_candidates dùng để hiển thị nhãn dễ phân biệt trên UI khi chạy nhiều instance của cùng một agent tùy chỉnh
• Nickname chỉ dùng để hiển thị; Codex vẫn nhận diện và tạo agent bằng name
• Danh sách nickname phải là tập tên duy nhất, không rỗng, và có thể dùng ký tự ASCII, số, khoảng trắng, dấu gạch nối, dấu gạch dưới
• Ví dụ: nếu đặt nickname ["Atlas", "Delta", "Echo"] cho agent reviewer, thì nickname sẽ được hiển thị trong app và CLI, nhưng loại agent cơ bản vẫn là reviewer

Ví dụ 1: Mẫu review PR

• Một mẫu chia việc review thành ba agent tùy chỉnh chuyên biệt
  • pr_explorer: agent chỉ đọc để lập bản đồ codebase và thu thập bằng chứng (mô hình: gpt-5.3-codex-spark, reasoning effort: medium)
  • reviewer: reviewer PR tìm lỗi về tính đúng đắn, bảo mật và rủi ro kiểm thử (mô hình: gpt-5.4, reasoning effort: high)
  • docs_researcher: chuyên gia tài liệu dùng máy chủ MCP riêng để kiểm tra tài liệu framework hoặc API (mô hình: gpt-5.3-codex-spark, chỉ đọc)
• Cấu hình dự án: max_threads = 6, max_depth = 1
• Chỉ dẫn cho pr_explorer: giữ chế độ khám phá, theo dõi đường chạy thực tế, trích dẫn tệp và symbol, và hạn chế đề xuất chỉnh sửa trừ khi agent cha yêu cầu
• Chỉ dẫn cho reviewer: review từ góc nhìn owner, ưu tiên tính đúng đắn, bảo mật, hồi quy hành vi, độ bao phủ test còn thiếu; nếu có thể thì kèm bước tái hiện, tránh comment chỉ về style trừ khi chúng che khuất bug thật
• Chỉ dẫn cho docs_researcher: dùng docs MCP server để xác minh API, tùy chọn và hành vi theo phiên bản, rồi trả lời ngắn gọn kèm liên kết hoặc tham chiếu chính xác, không được sửa code
• Ví dụ prompt sử dụng: "Review nhánh này so với main. pr_explorer lập bản đồ các đường code bị ảnh hưởng, reviewer tìm các rủi ro thực chất, và docs_researcher xác minh các framework API mà bản vá phụ thuộc vào"

Xử lý hàng loạt bằng CSV: spawn_agents_on_csv (thử nghiệm)

• Đây là tính năng thử nghiệm và có thể thay đổi trong tương lai
• Khi có nhiều tác vụ tương tự, có thể tạo hàng loạt worker subagent với mỗi hàng trong CSV là một đơn vị công việc
• Codex đọc CSV, tạo một worker agent cho mỗi hàng, đợi toàn bộ batch hoàn tất rồi xuất kết quả ra CSV
• Các trường hợp sử dụng phù hợp:
  • Review một tệp, package hoặc service trên mỗi hàng
  • Kiểm tra danh sách incident, PR hoặc đối tượng migration
  • Tạo tóm tắt có cấu trúc cho số lượng lớn đầu vào tương tự
• Tham số đầu vào của công cụ: csv_path (CSV nguồn), instruction (mẫu prompt cho worker, dùng placeholder {column_name}), id_column (ID mục ổn định), output_schema (dạng JSON cố định), output_csv_path, max_concurrency, max_runtime_seconds
• Mỗi worker phải gọi report_agent_job_result chính xác một lần; nếu kết thúc mà không báo kết quả thì hàng đó sẽ được đánh dấu lỗi
• Khi chạy bằng codex exec, trong lúc batch đang xử lý sẽ hiển thị cập nhật tiến độ một dòng trên stderr
• CSV được xuất ra sẽ bao gồm dữ liệu hàng gốc cùng các metadata như job_id, item_id, status, last_error, result_json
• Các thiết lập runtime liên quan: agents.max_threads (giới hạn thread đồng thời), agents.job_max_runtime_seconds (timeout cho từng worker, max_runtime_seconds theo từng lần gọi được ưu tiên), sqlite_home (đường dẫn lưu trạng thái SQLite dùng cho tác vụ agent và kết quả xuất)

Ví dụ 2: Mẫu debug tích hợp frontend

• Một mẫu hữu ích cho lỗi tích hợp băng qua hồi quy UI, luồng trình duyệt thiếu ổn định, và cả code ứng dụng lẫn sản phẩm đang chạy
• Kết hợp ba agent tùy chỉnh:
  • code_mapper: agent khám phá chỉ đọc tìm các đường code frontend/backend liên quan (mô hình: gpt-5.3-codex-spark, reasoning effort: medium)
  • browser_debugger: UI debugger dùng công cụ trình duyệt để tái hiện vấn đề và thu thập bằng chứng (mô hình: gpt-5.4, reasoning effort: high, sandbox: workspace-write)
    • Dùng công cụ trình duyệt cho ảnh chụp màn hình, output console và bằng chứng mạng; không được chỉnh sửa code ứng dụng
    • Kết nối tới máy chủ MCP của Chrome DevTools (http://localhost:3000/mcp, startup_timeout_sec: 20)
  • ui_fixer: agent thiên về triển khai phụ trách sửa nhỏ và có mục tiêu sau khi đã xác định được vấn đề (mô hình: gpt-5.3-codex-spark, reasoning effort: medium)
    • Thực hiện thay đổi nhỏ nhất có thể bảo vệ được, không đụng vào các tệp không liên quan và chỉ xác minh hành vi đã thay đổi
• Ví dụ prompt sử dụng: "Điều tra vì sao modal cài đặt không lưu được. browser_debugger tái hiện lỗi, code_mapper theo dõi đường code liên quan, và ui_fixer triển khai bản sửa tối thiểu sau khi xác định được chế độ lỗi"

[kgcrom]

Agent chỉ dùng mỗi model GPT-5.1-Codex-Mini, nhưng khi thêm prompt bên dưới vào Custom instructions của Codex App thì agent lại hoạt động bằng GPT-5.3-Codex-Spark.

"- when it spawns agents, use models \"GPT-5.3-Codex-Spark\" or higher."

Hoặc lúc tạo agent cũng khá thú vị khi có thể chỉ định model, và mình thích việc Codex App hiển thị theo cấu trúc thư mục con.

[xguru]

Codex cũng hãy nhanh chóng tạo tính năng điều khiển từ xa nhé!