AI Agents, Draft-Publish Isolation & RAG
Vòng đời Draft -> Readiness -> Publish
Phần tiêu đề “Vòng đời Draft -> Readiness -> Publish”POST /v1/agentsluôn tạo Agent ở trạng thái inactive draft (is_active: false).- Mọi chỉnh sửa qua
PATCH /v1/agents/{id}/draft(bắt buộcIf-Match) chỉ tác động lên draft revision — không ảnh hưởng AI đang chạy live (published_version_id). - Kiểm tra
GET /v1/agents/{id}/readinessđể lấyfingerprintvà phát hiện biến{{...}}chưa khai báo hoặc Knowledge chưa sẵn sàng. POST /v1/agents/{id}/publishđóng băng mộtAgentVersion(agv_...) bất biến và kích hoạt.- Khôi phục tức thì về bản trước với
POST /v1/agents/{id}/restore.
Runtime Sessions & SSE Streaming
Phần tiêu đề “Runtime Sessions & SSE Streaming”- Khởi tạo phiên qua
POST /v1/agent-sessions-> chạy turn vớiPOST /v1/agent-sessions/{id}/runs. - Live run trả trạng thái xếp hàng. Tra trạng thái cuối qua
GET /v1/agent-runs/{id}hoặc SSE của run. - Mỗi session có mutex chạy đồng thời (
409 SESSION_RUN_IN_PROGRESS). - Chế độ
sandboxhoặcsimulatechặn mọi side-effect (tạo đơn, đặt lịch, webhook ngoài) quaSandboxToolInterceptor. - Theo dõi stream qua
GET /v1/agent-runs/{id}/events(text/event-stream), hỗ trợLast-Event-IDđể nối lại sau đứt kết nối.
Tải tệp và tạo media
Phần tiêu đề “Tải tệp và tạo media”- Tạo phiên với
POST /v1/asset-upload-sessions, lấy URL và header cho từng phần quaPOST /v1/asset-upload-sessions/{id}/part-urls, rồi PUT dữ liệu vào URL tương ứng. - Sau khi tải đủ các phần, gọi
POST /v1/asset-upload-sessions/{id}/completions. Với phản hồi202, dùngGET /v1/asset-upload-sessions/{id}cho đến khi worker kiểm tra xong kích thước, checksum và loại tệp. Khi trạng thái làready, đọcresult.asset_id. Phiên chỉ truy cập được từ tích hợp đã tạo nó. POST /v1/media-generation-jobstrả202khi compute đã nhận yêu cầu. Dùng endpoint chi tiết để theo dõi kết quả. Sandbox không gửi yêu cầu tạo media đến nhà cung cấp.
