Khi dự án triển khai AI Agent API chọn OpenAI Agents API, không cần viết lại toàn bộ RFP. Các yêu cầu chung về định nghĩa hoàn tất, phê duyệt, phân loại dữ liệu và KPI vẫn được giữ. Phần cần bổ sung là khác biệt vận hành riêng của Agents API: lưu session/turn, phục hồi sau khi stream ngắt, thời gian chờ input-time connection tối đa 5 phút, environment lifecycle, hosted/self-hosted executor, tách key, filesystem dùng chung giữa subagents, concurrency và giới hạn trace API.
OpenAI công bố Agents API ở giai đoạn public beta ngày 10/9/2026. Nền tảng đưa harness của Codex vào API cho session dài hạn, context, tools, subagents và environment hosted hoặc self-hosted. Điều này quản lý nhiều phần của agent loop nhưng không bảo đảm exactly-once cho nghiệp vụ hay recovery tự động. Tài liệu chính thức nêu rõ completed turn không chứng minh mọi tool đã thành công; event bị lỡ khi stream ngắt không được replay; khách hàng self-hosted chịu trách nhiệm reconnect, shutdown và file cần lưu bền.
Về quyết định triển khai tổng quát, xem Triển khai AI Agent năm 2026. Về approval và governance, xem Quản trị quy trình AI Agent. Về phân tích dữ liệu, xem Data Agent cho sản xuất. Bài này chỉ trình bày phụ lục Agents API cần thêm vào các thiết kế đó.
nền tảng AI Agent: thành phần riêng mà Agents API bổ sung
Cần tách application, harness do OpenAI quản lý, session, environment, executor và tool connection. Với environment.type: none, harness gọi remote MCP và function tool nhưng không có built-in shell, workspace file hay executor MCP. Với openai_hosted, OpenAI provision sandbox và harness chạy command trong đó. Với self_hosted, doanh nghiệp provision compute, chạy codex exec-server, rồi kết nối outbound tới Agents API qua WebSocket.
| Thành phần | Năng lực platform | Trách nhiệm triển khai |
|---|---|---|
| Session | Lưu session, turn, item | Ánh xạ business ID và retention |
| Stream | Phát live event | Phát hiện disconnect, dựng lại từ saved item |
| Hosted environment | Provision sandbox, chạy command | Network policy, input file, lấy artifact |
| Self-hosted | Protocol harness-executor | Compute, startup, reconnect, shutdown, persistence |
| Subagents | Delegation, event, concurrency | Chia việc, shared file, cost ceiling |
| Trace | Dashboard turn/tool/subagent | Tương quan nghiệp vụ, telemetry thay thế |
Nếu chỉ giám sát request/response, doanh nghiệp có thể bỏ sót session còn tồn tại nhưng executor mất kết nối, turn completed nhưng tool lỗi, hoặc client đã ngắt trong khi công việc vẫn chạy.
Tách session, turn, item và business ID
Session chứa hội thoại và công việc qua nhiều turn. Turn là chu kỳ xử lý của một input. Item ghi model response, tool call, command và subagent coordination. Session bền không phải database transaction.
Tách session_id, turn_id, business_execution_id và side_effect_id. Một nghiệp vụ có thể trải qua nhiều turn hoặc tiếp tục ở session mới. Vì vậy không dùng session ID làm business ID. Lưu mapping trong ledger của doanh nghiệp; dùng side-effect ID như idempotency key hoặc query hệ thống đích trước khi retry write.
Context compaction hỗ trợ tác vụ dài nhưng hội thoại đã nén không phải nguồn dữ liệu chuẩn. Checkpoint có cấu trúc cần giữ phiên bản input/policy, step hoàn tất/chưa hoàn tất, artifact hash, external record ID, approval state và safe resume point.
Hướng dẫn hosted sandbox cũng cảnh báo completed turn không bảo đảm tất cả tool thành công. Bộ xác minh business completion phải kiểm tra required tool item, artifact và external record trước khi giao diện hiển thị “hoàn tất”.
Phục hồi sau khi stream ngắt
Event bị lỡ trong thời gian disconnect không được replay tự động. Không gửi lại input ngay vì turn cũ có thể vẫn hoạt động.
Trình tự recovery: 1) hiển thị đang đồng bộ, không phải failed; 2) retrieve session; 3) list saved turns/items để tìm tool, command và artifact cuối đã xác nhận; 4) đối chiếu write không rõ bằng side-effect ID; 5) chỉ gửi resume input ở turn mới sau khi turn cũ kết thúc và step còn thiếu đã rõ.
Hành vi input-time connection tối đa 5 phút
Nếu gửi input khi self-hosted environment offline, API có thể yêu cầu environment connection và chờ tối đa 5 phút. Khi vượt thời gian, submission thất bại; initial input có thể khiến session chuyển sang failed theo cách bất đồng bộ. Không gửi lại input trong thời gian chờ. Executor kết nối muộn không replay input đã timeout. Phải retrieve session và saved items, xác nhận input cũ chưa chạy, rồi mới submit turn mới.
Con số tối đa 5 phút là hành vi sản phẩm được tài liệu hóa, không phải SLA của hệ thống doanh nghiệp. Alert, escalation, manual fallback và mục tiêu recovery phải được định nghĩa riêng.
| Trạng thái | Xử lý không an toàn | Kiểm tra bắt buộc |
|---|---|---|
| Stream ngắt | Resend input ngay | Retrieve session và saved items |
| Chờ environment | Submit trùng trước 5 phút | Connection event và turn creation |
| Timeout 5 phút | Giả định late connection replay | Xác nhận chưa chạy, tạo turn mới |
| Turn completed | Đóng như thành công toàn bộ | Tool item và external record |
| Tool result không rõ | Blind retry write | Reconcile bằng side-effect ID |
| Policy version đổi | Tiếp tục với rule hỗn hợp | Stop, checkpoint, dùng bản đã duyệt |
Tách environment lifecycle khỏi session lifecycle
Session có thể tồn tại khi self-hosted compute offline; executor cũng có thể connected dù không có active turn. Theo dõi connected, disconnected, pending và failed event cùng session state.
OpenAI cảnh báo idle event riêng lẻ không phải safe shutdown signal. Idle có thể đến sau khi connection request biến mất nhưng trước khi input đang chờ bắt đầu turn. Trước khi dừng, kiểm tra lại incoming work, active command, required action và connection request, rồi dùng grace period. Nếu không phối hợp được shutdown, nên giữ compute hoạt động.
Mid-turn disconnect có thể làm tool lỗi dù turn vẫn complete. Command bị kill không tự restart; disconnect cũng không nhất thiết yêu cầu reconnect qua webhook. Recovery phải kiểm tra executor health, command item, artifact và external side effect riêng lẻ.
Hosted sandbox hỗ trợ network enabled, disabled hoặc restricted theo allowed_domains. Ghi lại đích thật trong PoC rồi chuyển sang allowlist. Self-hosted phải test toàn bộ outbound route cho registration và WebSocket. Proxy timeout ngắn hơn 5 phút sẽ cắt đường truyền trước platform.
Tách application key và executor key
Application OPENAI_API_KEY có quyền session và model inference. Self-hosted environment nhận một environment key hạn chế qua CODEX_API_KEY. Giữ application key ngoài sandbox.
Code do agent tạo có thể đọc environment key, nhưng key này chỉ nên cho phép kết nối environment. Không nhúng vào source, image hay log; cần test rotate/revoke. Organization, project và owner phải khớp với session.
Credential bên thứ ba nên nằm ngoài environment trong credential broker, chỉ chèn secret theo phạm vi vào request tới đích được duyệt. Đây là điều khoản riêng quan trọng vì agent-generated code có thể truy cập file, credential và network được mở trong environment.
Kiểm thử shared filesystem và concurrency của subagents
Thiết lập multi_agent.enabled và max_concurrent_subagents khi tạo session. Mặc định được tài liệu nêu là 6 subagents, không tính coordinator, nhưng không phải khuyến nghị production. Hãy chọn theo rate limit, CPU/memory, file contention và token budget.
Coordinator và subagents dùng chung filesystem. Tạo subagent không tạo sandbox mới. Cần work directory riêng, input read-only, file ownership, atomic write và một merge owner.
Subagents kế thừa MCP tools, credential/allowed-tool settings, web search và file/command của environment nhưng không hỗ trợ function tools. Nếu workflow cũ để child gọi function tool, phải chuyển qua coordinator hoặc thiết kế lại thành MCP.
Event stream cho biết subagent creation, coordination, wait và interrupt, nhưng create/wait item completed không có nghĩa child task hoàn tất. Kiểm tra child turn outcome và artifact.
| Kiểm thử | Fault injection | Bằng chứng đạt |
|---|---|---|
| Concurrency | Gửi nhiều việc hơn limit | Số child running không vượt cấu hình |
| Shared file | Hai child sửa cùng file | Phát hiện conflict, không overwrite im lặng |
| Child failure | Làm một command lỗi | Root báo công việc chưa đủ |
| Tool inheritance | Yêu cầu tool bị cấm | Bị chặn và ghi event |
| Function tool | Child yêu cầu function | Phát hiện không hỗ trợ, dùng fallback |
| Interrupt | Interrupt child giữa việc | Truy được outcome/partial artifact |
vận hành AI Agent: bù cho giới hạn trace và observability
Dashboard hiển thị session, turn, model response, tool call, subagent activity, duration, status và token. Tracing bật mặc định cho session mới nhưng được tạo sau khi turn kết thúc và có thể xuất hiện sau answer. Dùng live event cho trạng thái đang chạy, trace cho phân tích sau turn.
Trong public beta, API chưa cung cấp trace retrieval và external trace exporter. Không nên cam kết tự động export platform trace vào SIEM. Application cần lưu session/turn/item ID, business ID, environment event, tóm tắt tool result, artifact hash và external record ID, có masking phù hợp.
Token usage của root và child có thể ghi riêng; usage của parent không nhất thiết gồm child. Phải tổng hợp mọi agent turn để không đánh giá thấp chi phí.
Cancel active turn giữ session và công việc trước đó nhưng không rollback external action đã được nhận. Sau cancel, retrieve saved items, reconcile hệ thống đích rồi chọn resume, compensate hoặc close.
đánh giá AI Agent: thêm phụ lục Agents API vào RFP hiện có
Giữ RFP hiện có cho approval, data governance và business evaluation; chỉ thêm các điều khoản sau.
| Phụ lục | Câu trả lời cần có | Bằng chứng nghiệm thu |
|---|---|---|
| Session mapping | Business ID với session/turn/item | Ledger và retrieval |
| Stream recovery | Resync không dựa vào event replay | Disconnect test log |
| 5-minute connection | Wait, timeout, chặn resend, late connection | Offline executor test |
| Environment lifecycle | Startup, reconnect, shutdown, persistence | Event và runbook |
| Executor boundary | Outbound WebSocket, health, proxy | Network test |
| Key separation | Application key và environment key | Permission/revoke test |
| Multi-agent | Concurrency, shared FS, inherited tools | Conflict/child-failure test |
| Trace limitation | Live event, post-turn trace, API chưa có | Alternative telemetry |
| Beta change | Version pin, monitoring, regression, rollback | Version inventory |
Yêu cầu event và ID làm bằng chứng, không chấp nhận chỉ nói “có hỗ trợ”. Lưu phiên bản SDK, model, harness, container image và tool schema.
Dùng PoC 90 ngày để thử failure mode của Agents API
Giới hạn PoC ở một workflow, một nhóm người dùng và khoảng 2–3 hệ thống kết nối. Đây là ví dụ phạm vi dễ quản lý, không phải giới hạn sản phẩm hay cam kết kết quả.
Ngày 1–30: chọn environment, làm session mapping/business ledger, kiểm tra hosted network policy hoặc self-hosted executor/key separation, và chứng minh session/saved items vẫn retrieve được sau khi client stream đóng.
Ngày 31–60: tạo stream disconnect, executor offline, input-time connection timeout, mid-turn disconnect và unknown tool outcome. Xác minh không submit trùng khi đang chờ, late connection không replay input timeout, và chỉ tạo turn mới sau reconcile. Test concurrency, shared-file conflict, child failure, interrupt và function-tool limitation.
Ngày 61–90: cố định SDK/model/harness/tool schema và chạy lại failure suite. Kiểm tra trace delay, dashboard access, alternative telemetry và runbook cho ba case: session còn nhưng environment chết; turn completed nhưng tool lỗi; executor chỉ reconnect sau timeout 5 phút.
AI Agent doanh nghiệp: kiểm tra khi triển khai tại Thái Lan
Nếu self-hosted executor nằm trong mạng nhà máy Thái Lan, test proxy, DNS, WebSocket idle timeout và chính sách tắt compute ban đêm. Dù API chờ 5 phút, proxy doanh nghiệp ngắn hơn vẫn cắt trước. Khi chờ approval từ Nhật trùng thời gian tắt environment, không shutdown chỉ vì idle; kiểm tra pending input và approval state.
Giữ ID, event name, tool name và error code nguyên bản trong log dù giao diện là tiếng Việt, Thái hay Nhật. Tương quan cùng session_id, turn_id, environment_connection; ghi cả ICT và UTC để chuỗi timeout 5 phút không mơ hồ.
Cách hiểu sai thường gặp
- Durable session nghĩa là auto recovery: không có event replay, external reconciliation hay tự restart command.
- Idle nghĩa là có thể dừng compute: idle riêng lẻ không phải safe shutdown.
- Mỗi subagent có sandbox riêng: coordinator và children dùng chung filesystem.
- Completed turn nghĩa là mọi tool thành công: phải kiểm tra item, artifact và external record.
- Trace lấy/export ngay bằng API: trace là post-turn và public beta chưa có retrieval/exporter API.
Kết luận: nghiệm thu state transition riêng của Agents API
Phần thiết kế bổ sung cho Agents API rất cụ thể: ánh xạ session/turn/item với business ID; phục hồi stream từ saved items thay vì chờ event replay; ngăn gửi trùng trong input-time connection tối đa 5 phút; và hiểu rằng late connection không replay input đã timeout. Environment lifecycle phải được theo dõi riêng với session và không shutdown chỉ vì idle.
Tách application/environment key; test subagents trên shared filesystem với concurrency rõ ràng; sử dụng trace như bằng chứng post-turn nhưng bù giới hạn API/exporter bằng telemetry của application. Thêm phụ lục này vào RFP hiện có và fault-test 2–3 hệ thống kết nối giúp đánh giá Agents API mà không lặp bài governance chung.
TOMAS TECH có thể hỗ trợ bổ sung điều khoản vào RFP và thiết kế test cho hosted/self-hosted, executor connectivity, session recovery, subagent contention và timeout 5 phút. Vui lòng liên hệ TOMAS TECH.
FAQ về thiết kế vận hành Agents API
Stream ngắt có nên resend input không?
Không ngay lập tức. Retrieve session và saved items trước vì turn cũ có thể còn chạy và event bị lỡ không replay. Reconcile write không rõ trước khi tạo turn mới.
Chờ self-hosted 5 phút có phải SLA không?
Không. Đây là hành vi sản phẩm. Submission fail sau cửa sổ connection và late connection không replay input timeout. Cần SLA nội bộ riêng.
Subagent có file cô lập không?
Không. Coordinator và subagents dùng chung filesystem; cần work directory, ownership, atomic write và merge có kiểm soát.
Platform trace có đủ cho audit không?
Trace hữu ích nhưng là post-turn, và public beta không có retrieval/external exporter API. Cần lưu business correlation và bằng chứng quan trọng trong telemetry của ứng dụng.
Phụ lục RFP gồm những gì?
Session mapping, recovery không replay event, 5-minute connection, environment lifecycle, executor/key boundary, shared filesystem/concurrency, trace limits và beta version management.
Nguồn tham khảo
- OpenAI, Introducing the Agents API, 10/9/2026: https://openai.com/index/introducing-the-agents-api/
- OpenAI Developers, Agents API overview: https://developers.openai.com/api/docs/guides/agents-api/overview
- Architecture: https://developers.openai.com/api/docs/guides/agents-api/architecture
- Run and continue sessions: https://developers.openai.com/api/docs/guides/agents-api/sessions
- OpenAI-hosted sandboxes: https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted
- Self-hosted sandboxes: https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted
- Sandbox lifecycle: https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle
- Sandbox security: https://developers.openai.com/api/docs/guides/agents-api/environments/security
- Multi-agent: https://developers.openai.com/api/docs/guides/agents-api/multi-agent
- Observability and usage: https://developers.openai.com/api/docs/guides/agents-api/observability
- Tracing: https://developers.openai.com/api/docs/guides/agents-api/tracing
(Truy cập toàn bộ nguồn sơ cấp ngày 16/9/2026.)
