Chat¶

Khung Chat ở bên phải editor cho bạn trò chuyện với một workflow như người chat sẽ làm. Mỗi tin nhắn chạy một run của workflow đã lưu; các bước và câu trả lời hiện dần trong lúc run chạy, và cuộc trò chuyện được lưu lại để workflow có thể nhớ.

Mở khung chat¶

• Nút Chat trên thanh trên, hoặc Shift+C trên canvas, mở và đóng khung. Khung vẫn mở, đúng độ rộng bạn đã kéo (340–760 px), ở lần mở editor sau trên trình duyệt này.
• Cấu hình vẫn ở cạnh, nên bạn sửa một node rồi thử lại được ngay.
• Toàn màn hình (nút mũi tên) hiện chat trên cả cửa sổ, với danh sách các cuộc trò chuyện ở bên trái. Esc để quay lại; cuộc trò chuyện và nội dung đang gõ vẫn còn.
• Trong khung hẹp, chọn cuộc trò chuyện cũ ở menu chọn cuộc trò chuyện cạnh Xem dưới góc nhìn, hoặc bắt đầu cuộc mới bằng nút Chat mới (biểu tượng bút).

Để người ngoài studio chat với workflow, hãy công khai chat trên một trang riêng, và nếu muốn thì nhúng chat vào site của bạn.

Bật chat¶

1. Mở workflow và chọn ⋯ → Cài đặt Chat, hoặc nút bánh răng trong khung Chat. Bạn cần quyền chủ sở hữu để đổi cài đặt (chủ workflow hoặc admin).
2. Bật Chat và kiểm tra các trường:
   • Trường tin nhắn: trường state nhận mỗi tin nhắn (string hoặc list).
   • Trường trả lời: trường state hiện làm câu trả lời.
   • Trường cuộc trò chuyện: một trường list nhận các tin nhắn trước đó (xem Bộ nhớ). Chọn Không cho chat không nhớ.
3. Lưu. Khi lưu, các trường được kiểm tra có trong state của workflow.

Trò chuyện¶

Nhập tin nhắn rồi nhấn Enter (Shift+Enter để xuống dòng). Câu trả lời là Markdown: danh sách, bảng, link và khối code được định dạng; HTML thô và ảnh từ trang khác không hiện, link mở ở tab mới.

• Cuộc trò chuyện mới bắt đầu một cuộc trò chuyện chưa có gì để nhớ. Các cuộc trò chuyện cũ vẫn ở danh sách, mới nhất trên cùng, đặt tên theo tin nhắn đầu tiên.
• Xem dưới góc nhìn ở trên cùng đổi cách xem. Người dựng workflow thấy đầy đủ mọi bước, kèm input và output (bấm vào một bước để mở); Khách chat xem trước đúng như khách thấy trên trang chat công khai: những gì Bước hiện cho người chat cho phép. Khi khung Chat hẹp, nút đổi cách xem hiện nhãn ngắn Người dựng hoặc Khách và chứa luôn Cài đặt Chat; khi đang xem như khách, một dải phía trên cuộc trò chuyện báo điều đó, kèm Về góc nhìn người dựng.

- Mỗi tin nhắn là một run trong lịch sử run (Chạy → Xem tất cả) với nhãn Chat, nên bạn mở được trace đầy đủ ở đó. - Chat dùng workflow đã lưu: hãy lưu thay đổi trước khi thử.

Tệp đính kèm¶

Bật Cho phép đính kèm tệp trong Cài đặt chat để người dùng thêm tệp vào tin nhắn, trong khung Chat, trên trang công khai và trong widget. Mặc định tắt.

• Loại tệp: tài liệu (PDF, TXT, MD, CSV) và hình ảnh (PNG, JPEG, WebP). Máy chủ đọc loại tệp từ nội dung, không theo tên tệp.
• Số tệp mỗi tin nhắn và Dung lượng tối đa (MB): mặc định 5 tệp và 10 MB. Không được vượt mức trần của máy chủ, STUDIO_CHAT_ATTACHMENT_MAX_FILES và STUDIO_CHAT_ATTACHMENT_MAX_MB (xem Cấu hình).
• Trường state: một trường list của workflow nhận các tệp của mỗi tin nhắn, mặc định là files. Không được trùng trường tin nhắn hay trường hội thoại.

Bấm nút kẹp giấy hoặc thả tệp vào ô tin nhắn. Mỗi tệp được kiểm tra ngay trên trang trước khi tải lên (loại, dung lượng, số lượng), hiện thành một thẻ có dung lượng và ảnh thu nhỏ với hình ảnh, và gỡ được trước khi gửi. Nút Gửi chờ mọi tệp tải lên xong. Tin nhắn có thể chỉ có tệp.

Mỗi run nhận một bản ghi cho mỗi tệp trong trường state:

[{"id": "…", "name": "invoice.pdf", "type": "application/pdf", "size": 5120,
  "text": "Invoice 42 …", "text_cut": false}]

text chứa nội dung chữ của tài liệu (tối đa 50.000 ký tự, text_cut cho biết có bị cắt không). Nội dung nhị phân của tệp không bao giờ vào state của run. Để đưa tệp cho mô hình, bật Đưa tệp đính kèm vào ở node LLM hoặc Agent.

Tin nhắn đã gửi liệt kê các tệp kèm nút tải xuống. Chỉ người gửi, và người xây dựng trong Chat của khách, mới tải được; tệp luôn được tải xuống, không mở trong trang. Tệp được lưu cùng cuộc chat và bị xoá cùng cuộc chat (theo thời gian lưu hoặc khi Xoá); tệp đã tải lên mà không gửi bị xoá sau một giờ. Bản demo công khai không nhận tệp tải lên.

Mặc định tệp được lưu trong cơ sở dữ liệu. Người vận hành có thể lưu tệp trong một thư mục (STUDIO_ATTACHMENT_STORAGE=fs, STUDIO_ATTACHMENT_FS_PATH) để cơ sở dữ liệu không phình to. Tải xuống vẫn như cũ: studio đọc tệp rồi gửi đi, với cùng các bước kiểm tra. /api/health cho biết nơi lưu đang dùng (attachment_storage) và việc ghi, đọc, xoá ở đó có chạy không (attachment_storage_ok).

Với STUDIO_ATTACHMENT_STORAGE=s3, tệp được lưu vào một bucket tương thích S3 (AWS S3, Cloudflare R2, Backblaze B2, MinIO). Trình duyệt không bao giờ thấy bucket: không có liên kết tới bucket, và tải xuống vẫn đi qua studio. Đặt STUDIO_ATTACHMENT_S3_BUCKET, và với dịch vụ khác AWS thì đặt thêm STUDIO_ATTACHMENT_S3_ENDPOINT:

Access key không bao giờ xuất hiện trong log, thông báo lỗi hay /api/health; bucket lỗi chỉ hiện một lý do ngắn như S3 error AccessDenied. Các image phát hành đã có sẵn S3 client; cài từ mã nguồn thì cần pip install "superstep-backend[s3]".

Hãy dành cho tệp đính kèm một thư mục hoặc prefix bucket riêng. Studio xoá các tệp còn sót ở đó mà không cuộc trò chuyện nào dùng, nhưng chỉ những tệp có tên do chính nó tạo (<workflow>/<chat>/<id tệp>), nên tệp khác không bao giờ bị động tới. Thư mục trùng với, hoặc chứa, thư mục dữ liệu của studio (cơ sở dữ liệu, khoá bí mật, thư mục import) sẽ bị từ chối: /api/health hiện attachment_storage_ok: false và tải lên sẽ lỗi; hãy dùng thư mục con như /data/attachments. Để trống STUDIO_ATTACHMENT_S3_PREFIX trên bucket dùng chung với thứ khác sẽ ghi cảnh báo vào log; hãy đặt prefix như superstep/.

Mỗi tệp nhớ thư mục hoặc bucket và prefix mà nó được ghi vào, nên đổi STUDIO_ATTACHMENT_FS_PATH, bucket hay prefix về sau không làm mất tệp cũ: chúng vẫn được đọc từ chỗ cũ, và superstep attachments migrate --to fs (hoặc --to s3) chuyển chúng sang chỗ mới. Tệp trong bucket vẫn đọc được sau khi chuyển sang nơi lưu khác và xoá STUDIO_ATTACHMENT_S3_BUCKET, miễn là vẫn còn thông tin xác thực S3 (và endpoint); thiếu chúng thì việc đọc báo lỗi "no S3 credentials".

Bộ nhớ¶

Khi có trường cuộc trò chuyện, mỗi run nhận n lượt hỏi–đáp gần nhất cùng tin nhắn mới trong trường đó, dạng list các mục {"role": "user" | "assistant", "content": "…"}. Dùng nó trong prompt, ví dụ:

Cuộc trò chuyện đến giờ:
{{state.messages}}

Trả lời tin nhắn cuối của người dùng.

Node Agent dùng trường này làm Trường lịch sử và có tin nhắn trong prompt nhiệm vụ ({{state.message}}) gửi tin nhắn mới một lần: dưới dạng prompt nhiệm vụ, không lặp lại ở mục cuối của lịch sử.

Node Human trong chat¶

Tuỳ chọn Người trả lời của node Human quyết định ai trả lời khi workflow chạy từ chat:

• Người chat (mặc định): câu hỏi hiện trong chat với Duyệt và Từ chối; hoặc nhập câu trả lời vào ô tin nhắn. Câu trả lời vào trường output của node và run chạy tiếp. Câu trả lời của bạn được giữ lại trong chat như một tin nhắn của bạn (câu trả lời dạng form thành mỗi trường một dòng trường: giá trị), và các lượt sau nhớ nó cùng với câu hỏi mà nó trả lời, trong cùng một lượt trao đổi.
• Người duyệt: chat báo đang chờ duyệt, còn câu hỏi đến trang Duyệt (và các kênh của nó) như thường lệ. Chat hiện câu trả lời khi run chạy tiếp.

Bước duyệt công cụ của node Agent luôn do người duyệt trả lời: người chat không duyệt hành động của chính agent.

Không gửi được tin nhắn mới khi chat đang chờ trả lời, hoặc khi câu trả lời của bot chưa về xong: nút gửi vẫn là nút dừng cho đến khi câu trả lời được lưu. Hạn chờ của node áp dụng cho cả hai cách; khi quá hạn, hành động khi hết hạn quyết định điều gì xảy ra.

Công khai chat¶

Trong Ai được chat, bật Ai có link, Người đã đăng nhập hoặc Người dùng ứng dụng bên thứ ba, và giữ Chat bật. Có thể chọn nhiều tùy chọn. Chat có một trang riêng ở /c/<địa-chỉ>, nơi người chưa từng mở studio cũng chat được với workflow.

Nút Sao chép link và Mở trang hiện ra khi chat đã công khai.

Trên trang:

• Ai có link: khách chat không cần tài khoản. Trình duyệt giữ một cookie riêng cho chat này, nên khách thấy lại các cuộc trò chuyện cũ khi quay lại, và không ai khác đọc được chúng.
• Người đã đăng nhập: mọi tài khoản của studio này đều chat được, kể cả tài khoản không được mở workflow. Khách chưa đăng nhập được đưa tới trang đăng nhập rồi quay lại chat.
• Người dùng ứng dụng bên thứ ba: backend ứng dụng của bạn ký user token ngắn hạn bằng app key của từng chat. Tích hợp qua Chat API và hướng dẫn xác thực; trang/widget có sẵn chưa có cầu nối identify bằng token.
• Mỗi tin nhắn chạy workflow đã lưu dưới danh nghĩa chủ workflow: dùng credential, knowledge base và MCP server của chủ workflow, như chat qua Slack và Telegram. Các run nằm trong Lịch sử của workflow.
• Trang chỉ hiện những gì Bước hiện cho người chat cho phép. Trang không bao giờ hiện workflow, state hay chủ của workflow.
• Node Human hoạt động như trong khung chat: khách chat trả lời câu hỏi dành cho Người chat, còn lại thì chờ người duyệt.
• Trang theo ngôn ngữ (tiếng Anh hoặc tiếng Việt) và chế độ sáng hay tối của trình duyệt khách.

Giới hạn. Ngoài số tin nhắn mỗi ngày của chat, server còn giới hạn theo từng khách và từng địa chỉ IP (mặc định 10 và 30 tin nhắn mỗi phút). Khách vượt giới hạn được báo khi nào thử lại, và không run nào được chạy. Người vận hành đổi các giới hạn này bằng các cài đặt STUDIO_PUBLIC_CHAT_RATE_* (xem Cấu hình). Bản demo công khai không công khai chat nào.

Để gỡ trang, bỏ chọn mọi tùy chọn truy cập công khai (chỉ người dựng workflow), hoặc tắt Chat. Trang khi đó báo chat không mở.

Chat của khách¶

Mở ⋯ → Lịch sử chat & phản hồi → Khách để xem chat trên trang công khai bên ngoài khung Chat. Danh sách hiện từng cuộc trò chuyện của khách ở chế độ chỉ xem, có đủ mọi bước, cho tới khi Thời gian lưu xoá nó. Danh sách không hiện tên hay id của khách. Khách không được báo rằng cuộc trò chuyện được lưu, nên hãy ghi điều đó trong lời giới thiệu nếu cần.

Dưới mỗi câu trả lời đã xong, khách có thể đánh dấu hữu ích hoặc chưa hữu ích. Đánh dấu chưa hữu ích có thể kèm một câu ngắn về chỗ chưa đúng. Khách đổi hoặc bỏ đánh dấu được. Chat nhúng cũng có các nút này, vì đó chính là trang này.

Trong Lịch sử chat & phản hồi, người dựng thấy đánh dấu và nhận xét trên câu trả lời. Bộ lọc Có không thích chỉ giữ chat khách có đánh dấu đó. Các thẻ thống kê cho biết số lượt hữu ích/chưa hữu ích và tỷ lệ chưa hữu ích của workflow trong 7 và 30 ngày qua. Tab Cuộc trò chuyện liệt kê chat Studio của bạn; dùng khung Chat để tiếp tục trò chuyện. Lưu thành test case trên câu trả lời đã được đánh dấu mở một test nháp của run đó. Khi bật theo dõi LangSmith, đánh dấu cũng được gửi lên trace của run dưới tên user_rating.

Nhúng chat vào site của bạn¶

Chat mở cho Ai có link cũng hiện được trên một site khác.

1. Thêm site vào Các site được nhúng chat này, mỗi dòng một site, ví dụ https://www.example.com (http://localhost:<cổng> cũng được, để thử). Site khác không hiện được trang trong frame.
2. Sao chép một trong hai đoạn mã hiện ra:
   • Bong bóng chat: dán trước </body>. Một nút tròn ở góc trang mở chat. Khách giữ được cuộc trò chuyện trên site đó ở mọi trình duyệt.
   • Frame: hiện chat ngay trong trang, ở chỗ bạn đặt nó. Một số trình duyệt (Safari) xoá dữ liệu mà frame lưu, nên khách có thể phải bắt đầu lại mỗi lần ghé; dùng bong bóng chat để giữ cuộc trò chuyện.

<script src="https://studio.example.com/c/widget.js" data-slug="ho-tro" async></script>

Bong bóng nhận data-position="left" để nằm bên trái, và data-open="true" để mở sẵn. Bong bóng giữ khoá chat của khách trong bộ nhớ của chính site đó, nên script trên site đọc được khoá và mở được các cuộc trò chuyện của khách: chỉ nhúng bong bóng vào site bạn tin cậy với các cuộc trò chuyện đó.

Phần còn lại của studio không hiện được trong frame trên bất kỳ site nào.

Lỗi¶

Xem thêm Chạy từ chat cho Slack và Telegram.

Để tích hợp người dùng riêng và tuỳ chỉnh giao diện, xem bộ giao diện React và API widget.

Sửa tin nhắn đã gửi¶

Trên máy chủ có capabilities.edit trong dữ liệu cuộc trò chuyện, chọn Sửa tin nhắn ở tin nhắn người dùng đã lưu. Câu trả lời cho Human không phải tin nhắn được sửa. Lưu sẽ mở nhánh hội thoại mới với lịch sử trước đó và nội dung đã sửa; cuộc trò chuyện gốc cùng các tin nhắn sau nó vẫn được giữ nguyên. Chọn Cuộc trò chuyện gốc để quay về. Các tin nhắn kế thừa chỉ đọc, không tạo thêm đánh giá. Tệp được sao chép sang ID và đối tượng lưu trữ riêng, nên xoá một cuộc trò chuyện không làm hỏng tệp của cuộc trò chuyện kia.

Hộp xác nhận nêu rõ thao tác sẽ chạy lại workflow đang lưu/công khai: lệnh gọi API, ghi dữ liệu và thông báo có thể lặp lại. Thao tác không hoàn tác hành động cũ hay chỉ tạo lại văn bản của model. Câu hỏi Human và yêu cầu người duyệt cần được trả lời lại. Hãy chờ cuộc trò chuyện đang chạy/chờ xử lý xong và tải lại nếu lịch sử đã thay đổi. Huỷ sửa không thay đổi tin nhắn.

Sửa tin nhắn và tạo lại câu trả lời cần Superstep 0.11.0 trở lên. Dùng các phiên bản SDK/giao diện tương thích với máy chủ; các gói native tiếp tục tạm hoãn.

Tạo lại câu trả lời cuối¶

Dùng Tạo lại câu trả lời trên câu trả lời cuối đã kết thúc, kể cả khi lỗi, bị huỷ hoặc hết thời gian. Xác nhận Chạy lại trong nhánh mới để chạy lại tin nhắn đã tạo ra câu trả lời đó. Cuộc trò chuyện mới giữ lịch sử trước tin nhắn ấy và sao chép file độc lập; câu trả lời gốc cùng đánh giá được giữ nguyên. Dùng Cuộc trò chuyện gốc để quay lại.

Thao tác chạy workflow đang lưu/công khai từ đầu, nên lệnh gọi API, ghi dữ liệu và thông báo có thể lặp lại. Các câu trả lời Human và yêu cầu duyệt của người duyệt trong lần trước không được dùng lại: bạn cần trả lời/duyệt các yêu cầu mới. Cuộc trò chuyện đang chạy hoặc đang chờ không tạo lại được. Huỷ hộp thoại không tạo nhánh. Cần capabilities.regenerate; câu trả lời kế thừa chỉ được đọc.