Tận dụng Codex Harness: Cách OpenAI xây dựng App Server

• OpenAI xây dựng và cung cấp kiến trúc App Server được chuẩn hóa cùng giao thức JSON-RPC để có thể tích hợp Codex vào sản phẩm của mình
• Ban đầu xuất phát từ harness TUI tập trung vào CLI, nhưng sau khi áp dụng giao thức JSON-RPC, nhiều client như IDE, web, ứng dụng cục bộ có thể dùng chung cùng một agent loop
• App Server là tiến trình chạy lâu dài lưu trữ thư viện lõi Codex, phơi bày cho client toàn bộ trải nghiệm agent như quản lý vòng đời thread, cấu hình/xác thực, thực thi công cụ
• Thông qua ba primitive hội thoại là item, turn và thread, có thể cấu trúc các tương tác phức tạp của agent loop và xây dựng UI phong phú
• Cùng một harness được tái sử dụng trên nhiều bề mặt như VS Code, JetBrains, Xcode, ứng dụng desktop, runtime web, đồng thời hỗ trợ client binding đa ngôn ngữ như Go, Python, TypeScript, Swift, Kotlin
• Ngoài ra còn có các cách tích hợp thay thế như máy chủ MCP, chế độ CLI, TypeScript SDK, nhưng App Server đã trở thành tiêu chuẩn tích hợp ưu tiên hàng đầu
• OpenAI sẽ tiếp tục duy trì App Server là con đường mặc định để tích hợp Codex, đồng thời hỗ trợ mọi người tích hợp Codex vào workflow riêng thông qua repo CLI mã nguồn mở

---

Bối cảnh cơ bản của App Server

• Ban đầu đây là cách thực dụng để tái sử dụng Codex harness trong nhiều sản phẩm, nhưng dần phát triển thành một giao thức chuẩn
• Codex CLI khởi đầu là TUI (giao diện người dùng trên terminal), và khi xây dựng tiện ích mở rộng VS Code, cần có cách chạy cùng harness đó trong UI của IDE
  • Cần hỗ trợ nhiều kiểu tương tác vượt ra ngoài mô hình request/response như duyệt workspace, stream tiến trình suy luận, xuất diff
• Lúc đầu từng thử phơi bày Codex như một máy chủ MCP, nhưng khó duy trì ngữ nghĩa MCP theo cách phù hợp với VS Code
• Phương án thay thế là áp dụng giao thức JSON-RPC phản ánh vòng lặp TUI, và đây trở thành phiên bản không chính thức đầu tiên của App Server
  • Khi đó chưa dự đoán được các client khác sẽ phụ thuộc vào nó, nên nó không được thiết kế như một API ổn định
• Khi việc áp dụng Codex mở rộng, các nhóm nội bộ và đối tác bên ngoài (JetBrains, Xcode, v.v.) bắt đầu yêu cầu khả năng nhúng harness vào sản phẩm của riêng họ
  • Cần thiết kế một platform surface cho phép phát triển giao thức mà vẫn duy trì khả năng tương thích ngược

Cấu trúc bên trong của Codex harness

• Codex core là thư viện chứa toàn bộ mã agent, đồng thời là runtime chạy agent loop và quản lý tính liên tục của một Codex thread (cuộc hội thoại)
• Ngoài agent loop cốt lõi còn có ba nhóm chức năng chính:
  • Vòng đời thread và tính bền vững: tạo, tiếp tục, fork, lưu trữ thread; duy trì bản ghi sự kiện để client có thể kết nối lại và render timeline nhất quán
  • Cấu hình và xác thực: tải cấu hình, quản lý giá trị mặc định, trạng thái thông tin xác thực, thực thi các luồng xác thực như "Đăng nhập bằng ChatGPT"
  • Thực thi và mở rộng công cụ: chạy công cụ shell/tệp trong sandbox, kết nối các tích hợp như máy chủ MCP và skill để tham gia vào agent loop dưới một mô hình chính sách thống nhất

Kiến trúc App Server

• App Server là giao thức JSON-RPC giữa client và server, đồng thời là một tiến trình chạy lâu dài lưu trữ các thread lõi của Codex
• Có bốn thành phần chính:
  • Trình đọc stdio: đảm nhiệm việc đọc đầu vào từ client
  • Bộ xử lý thông điệp Codex: giao tiếp trực tiếp với từng core session để gửi request từ client và nhận cập nhật
  • Trình quản lý thread: khởi chạy một core session cho mỗi thread
  • Core thread: nơi agent loop thực sự chạy
• Một request từ client có thể tạo ra rất nhiều cập nhật sự kiện, và chính các sự kiện chi tiết này cho phép xây dựng UI phong phú
• Trình đọc stdio và bộ xử lý thông điệp Codex đóng vai trò là lớp chuyển đổi, biến request JSON-RPC từ client thành thao tác trên Codex core, đồng thời chuyển đổi luồng sự kiện nội bộ thành các thông báo JSON-RPC ổn định và có thể dùng cho UI
• Giao thức JSON-RPC giữa client và App Server là hai chiều hoàn toàn
  • Khi agent cần đầu vào như phê duyệt, server có thể chủ động bắt đầu request và tạm dừng turn cho tới khi client phản hồi

Các primitive hội thoại

• Cốt lõi của việc thiết kế API cho agent loop là nhận ra rằng tương tác giữa người dùng và agent không phải request/response đơn giản, mà là một chuỗi thao tác có cấu trúc
• Ba primitive cốt lõi:

• Item

  • Đơn vị cơ bản của đầu vào/đầu ra trong Codex
  • Có kiểu rõ ràng: tin nhắn người dùng, tin nhắn agent, thực thi công cụ, yêu cầu phê duyệt, diff, v.v.
  • Có vòng đời tường minh: item/started → item/*/delta tùy chọn (streaming) → item/completed (payload cuối cùng)
  • Client có thể render ngay từ started, stream cập nhật dần ở delta, và hoàn tất ở completed

• Turn

  • Một đơn vị công việc của agent bắt đầu từ đầu vào của người dùng
  • Ví dụ: khi client gửi "run tests and summarize failures" thì turn bắt đầu, và khi agent hoàn tất tạo đầu ra thì turn kết thúc
  • Một turn bao gồm chuỗi item thể hiện các bước trung gian và kết quả

• Thread

  • Container bền vững cho một Codex session đang diễn ra giữa người dùng và agent
  • Chứa nhiều turn, có thể được tạo, tiếp tục, fork và lưu trữ
  • Lịch sử thread được duy trì liên tục để client có thể kết nối lại và render timeline nhất quán

Luồng hội thoại client-server

• Khi bắt đầu hội thoại, client và server cần thiết lập bắt tay initialize
  • Client gửi một request initialize duy nhất trước mọi method khác, và server xác nhận bằng phản hồi
  • Hai bên thống nhất về quản lý phiên bản giao thức, cờ tính năng và giá trị mặc định
• Khi có request mới, server tạo thread rồi tạo turn, sau đó gửi các thông báo thread/started và turn/started
• Lời gọi công cụ cũng được gửi tới client dưới dạng item, và server có thể yêu cầu phê duyệt để thực thi thao tác
  • Khi có yêu cầu phê duyệt, turn sẽ tạm dừng cho tới khi client phản hồi bằng "cho phép" hoặc "từ chối"
• Server gửi tin nhắn agent và kết thúc turn bằng turn/completed
  • Các sự kiện delta của tin nhắn agent stream từng phần nội dung, rồi hoàn tất bằng item/completed
• Nếu muốn xem JSON của toàn bộ turn, có thể chạy lệnh codex debug app-server send-message-v2 "run tests and summarize failures"

Mẫu tích hợp với client

• Ứng dụng cục bộ và IDE

  • Cách truyền là JSON-RPC (JSONL) qua stdio
  • Client cục bộ sẽ đóng gói hoặc tải về binary App Server theo từng nền tảng rồi chạy nó như một tiến trình con chạy dài hạn
  • Trong tiện ích mở rộng VS Code và ứng dụng desktop, artifact phát hành bao gồm binary Codex theo từng nền tảng, được khóa ở phiên bản đã kiểm thử
  • App Server client đã được triển khai bằng nhiều ngôn ngữ như Go, Python, TypeScript, Swift, Kotlin
    • TypeScript: có thể tạo trực tiếp định nghĩa bằng lệnh codex app-server generate-ts
    • Ngôn ngữ khác: tạo gói JSON Schema bằng lệnh codex app-server generate-json-schema rồi đưa vào code generator
  • Các đối tác như Xcode có thể tách biệt chu kỳ phát hành bằng cách giữ client ổn định và trỏ tới binary App Server mới nhất
    • Có thể triển khai cải tiến phía server (như tự động compact tốt hơn, khóa cấu hình mới) và sửa lỗi mà không phải chờ phát hành client
    • JSON-RPC surface có tương thích ngược nên client cũ vẫn có thể giao tiếp an toàn với server mới

• Runtime web của Codex

  • Chạy trong môi trường container
  • Worker cấp phát một container với workspace đã checkout, chạy binary App Server bên trong đó và duy trì JSON-RPC qua kênh stdio
  • Ứng dụng web (trình duyệt người dùng) giao tiếp với backend Codex qua HTTP và SSE để stream sự kiện công việc
  • Cách này giúp giữ UI phía trình duyệt gọn nhẹ trong khi vẫn cung cấp runtime nhất quán trên cả desktop lẫn web
  • Vì session web ngắn hạn (đóng tab, mất mạng), trạng thái và tiến độ được giữ ở phía server
    • Ngay cả khi tab biến mất, công việc vẫn tiếp tục; session mới có thể dễ dàng kết nối lại và tiếp tục từ điểm đang dở

• Kế hoạch tái cấu trúc TUI

  • TUI hiện tại là client "native" chạy trong cùng tiến trình với agent loop và giao tiếp trực tiếp với các kiểu lõi Rust thay vì giao thức App Server
  • Có kế hoạch tái cấu trúc TUI để hoạt động như các client khác bằng App Server
    • Có thể kết nối tới Codex server đang chạy trên máy từ xa
    • Agent gắn chặt với hạ tầng tính toán, nên vẫn có thể tiếp tục công việc ngay cả khi laptop sleep hoặc mất kết nối
    • Đồng thời vẫn cung cấp cập nhật trực tiếp và khả năng điều khiển ở máy cục bộ

Chọn đúng giao thức

• App Server là cách tích hợp ưu tiên hàng đầu, nhưng cũng có một số lựa chọn thay thế với tính năng hạn chế hơn

• Máy chủ MCP

  • Chạy codex mcp-server và kết nối từ mọi MCP client hỗ trợ stdio server (ví dụ: OpenAI Agents SDK)
  • Phù hợp khi đã có workflow dựa trên MCP và muốn dùng Codex như một công cụ có thể gọi được
  • Nhược điểm: chỉ dùng được những gì MCP cung cấp; các tương tác riêng của Codex như cập nhật diff có thể không ánh xạ mượt mà

• Giao diện di động giữa nhiều hệ thống

  • Phù hợp khi cần một lớp trừu tượng duy nhất cho nhiều nhà cung cấp model và runtime
  • Nhược điểm: thường hội tụ về tập con chức năng chung nhỏ nhất, khiến việc biểu đạt tương tác phong phú trở nên khó khăn
  • Lĩnh vực này đang phát triển rất nhanh và được kỳ vọng sẽ xuất hiện thêm nhiều chuẩn chung hơn nữa (ví dụ: agentskills.io)

• App Server

  • Phơi bày toàn bộ Codex harness qua một luồng sự kiện ổn định và thân thiện với UI
  • Ngoài toàn bộ chức năng của agent loop, còn dùng được các tính năng hỗ trợ như đăng nhập bằng ChatGPT, khám phá model, quản lý cấu hình
  • Chi phí chính: cần xây dựng binding JSON-RPC phía client bằng ngôn ngữ đang dùng
    • Nếu cung cấp JSON Schema và tài liệu, Codex có thể xử lý nhiều tác vụ phức tạp, và nhiều đội đã tích hợp rất nhanh

• Chế độ CLI

  • Chế độ dạng script gọn nhẹ cho các tác vụ một lần và chạy CI
  • Chạy một lệnh đơn theo kiểu không tương tác, stream đầu ra có cấu trúc, và kết thúc với tín hiệu thành công/thất bại rõ ràng
  • Phù hợp cho tự động hóa và pipeline

• TypeScript SDK

  • Thư viện TypeScript cho phép điều khiển agent Codex cục bộ theo cách lập trình ngay trong ứng dụng riêng
  • Phù hợp khi cần giao diện thư viện native mà không muốn tự xây client JSON-RPC riêng
  • Ra mắt trước App Server nên hỗ trợ ít ngôn ngữ hơn và phạm vi áp dụng hẹp hơn
  • Tùy theo mức độ quan tâm của nhà phát triển, có thể sẽ có thêm SDK bọc giao thức App Server

Kế hoạch sắp tới

• App Server phơi bày Codex core, cho phép client vận hành toàn bộ agent loop, và hỗ trợ nhiều bề mặt rộng khắp như TUI, tích hợp IDE cục bộ, runtime web
• Toàn bộ mã nguồn được công khai trong repo mã nguồn mở Codex CLI
• OpenAI hoan nghênh các yêu cầu tính năng và phản hồi, đồng thời sẽ liên tục cải tiến để giúp việc sử dụng agent trở nên dễ dàng hơn

• Tài liệu chính thức về Codex App Server