Làm việc cùng AI agent

Agent làm được gì

• Tạo dự án, thêm nguồn tham khảo (trang web, văn bản dán vào, video tải lên) và tải ảnh tham chiếu.
• Đọc bối cảnh dự án và gửi storyboard; server kiểm tra miễn phí.
• Tạo báo giá và, sau khi người dùng đồng ý giá, bắt đầu sản xuất.
• Theo dõi tiến độ, đọc các clip đã kiểm tra và chuẩn bị bàn giao; người dùng đồng ý trước khi bàn giao được phát hành.
• Chỉnh ảnh và video, dịch một video đã xong và nhập bảng tính sản phẩm.

Danh mục tool liệt kê mọi tool theo bước công việc, còn phần tình huống sử dụng đưa ra các công thức trọn vẹn.

Endpoint và giao thức

Server dùng JSON-RPC 2.0 qua HTTPS POST tại đường dẫn bên dưới, trên cùng host với studio bạn đăng nhập. Các method được hỗ trợ: initialize, notifications/initialized, ping, tools/list và tools/call.

POST /api/v1/agent/mcp
Authorization: Bearer <token>
Content-Type: application/json

• Gửi token kèm initialize. Phản hồi có header Mcp-Session-Id; gửi lại header đó ở các lần gọi sau. Một phiên kéo dài tối đa một giờ và không bao giờ quá hạn của token.
• Trường instructions trong phản hồi initialize mang sẵn quy trình và quy tắc, nên agent đã kết nối biết phải làm gì mà không cần đọc các trang này.
• Kết quả tool nằm trong result.structuredContent. Để tải một clip đã kiểm tra, gọi download_path của nó với Authorization: Bearer <Mcp-Session-Id>, không dùng token.

Chế độ token

Quản trị viên workspace tạo token ở trang Nhà phát triển. Mỗi token có một chế độ:

• tools/list chỉ hiện các tool mà chế độ và danh sách cho phép của token được dùng. Gọi một tool bị ẩn sẽ trả về MODE_FORBIDS_TOOL.
• Khi tạo token, hãy cho phép mọi tool của chế độ đó để token tự có cả các tool thêm sau này. Token liệt kê tool theo tên sẽ không bao giờ có tool mới; khi đó hãy tạo token mới.
• Phạm vi là cả workspace hoặc một dự án. Trang Nhà phát triển tạo token cho cả workspace; với một dự án hoặc từng tool riêng, quản trị viên dùng Cài đặt, mục API & MCP. Token chỉ cho một dự án thì không tạo được dự án mới.
• Token hết hạn sau 1, 7 hoặc 30 ngày và chỉ hiện một lần. Quản trị viên thu hồi token trong danh sách token; các yêu cầu tiếp theo của token bị từ chối.

Giới hạn của một token

Mỗi token có ba giới hạn do quản trị viên đặt ở trang Nhà phát triển (Sửa giới hạn). Chúng chỉ áp dụng cho token đó: việc bắt đầu trên ứng dụng web không bao giờ bị giới hạn.

• Các kiểm tra chỉ từ chối lần bắt đầu mới. Việc đang chạy không bao giờ bị dừng, và lời gọi bị từ chối không để lại gì: không giữ tiền, không có bản ghi dở dang.
• Hạn mức chi tính phần việc của chính token đã dùng hoặc đang giữ. Hãy đặt ngay sau khi tạo token execute.

Request key

Phần lớn thao tác ghi nhận một request_key: một UUIDv4 agent tạo cho mỗi thay đổi. Nếu mất phản hồi, agent gửi lại đúng lời gọi đó với cùng key, và server trả về kết quả lần đầu thay vì làm hai lần.

• Tạo key mới cho mỗi thao tác ghi mới.
• Chỉ dùng lại key để thử lại đúng lời gọi cũ. Key đã dùng mà khác dữ liệu sẽ lỗi IDEMPOTENCY_CONFLICT.
• Sau khi hết thời gian chờ hoặc gặp WRITE_OUTCOME_UNKNOWN, đọc trạng thái trước khi quyết định. Không gửi lại một cách mù quáng.

Quy tắc chi tiêu: báo giá, người dùng duyệt, rồi mới sản xuất

1. Agent gọi create_quote. Bước này miễn phí, cần token execute và lưu giá của từng shot cùng tổng giá.
2. Agent dừng lại và cho người dùng xem giá.
3. Chỉ khi người dùng đồng ý, agent mới gọi approve_production, lệnh này bắt đầu sản xuất ngay.

confirmed: true (lưu trữ, quyết định review, bàn giao) và rights_confirmed: true (quyền dùng ảnh và nội dung) cũng ghi lại quyết định của người dùng. Agent chỉ đặt các giá trị này sau khi người dùng đã đồng ý trong cuộc trò chuyện.

Giá của mọi báo giá, lượt chạy và tác vụ media đều được lưu, nên người dùng có thể kiểm tra lại số đã chi.

Cấu trúc lỗi

Lời gọi thất bại trả về isError: true và structuredContent.error:

{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "This request_key was already used with different input. Use a new request_key for a different request.",
  "field_path": "request_key",
  "next_action": "Fix the argument(s) named in field_path/message, then call the same tool again (with a NEW request_key if the tool takes one).",
  "retry_policy": "after_fix",
  "owner": "client"
}

• owner cho biết ai xử lý: client (agent sửa lời gọi), user (người dùng quyết định hoặc cung cấp thêm), admin (quản trị viên workspace đổi cài đặt hoặc token) hay server (phía chúng tôi).
• retry_policy là một trong never, after_fix, refresh_then_retry, backoff hoặc reconcile. Với reconcile, đọc trạng thái; không gửi lại.
• next_action là bước tiếp theo chính xác. Làm theo nó, đừng đoán.

Danh mục mã lỗi liệt kê các mã cùng người xử lý và cách làm.

Ngoài phạm vi các trang này

• Chưa có SDK. MCP và REST API là các cách kết nối được hỗ trợ.
• Chưa có tool tạo nhiều video hoàn chỉnh trong một lần gọi. Để làm nhiều video, agent lặp lại mỗi mục một dự án: xem Clip cho cả danh mục sản phẩm. Nhiều clip ngắn từ một bảng là ngoại lệ: xem Clip video và lô clip. Lô bàn giao chỉ gom các video đã xong để tải về.
• Các trang này không ghi giá. Giá của một việc đến từ create_quote trong workspace của bạn.