Hướng dẫn build bot

Một bot là data thuần — vài file YAML + Markdown trong một thư mục, không có code. Runtime đọc các file này để quyết định bot nói gì. Nhiều file vì mỗi file lo một việc riêng, nhưng bạn không cần điền hết ngay: chỉ 3 file lõi + 1 kịch bản là bot đã chạy, phần còn lại thêm dần.

Bot hoạt động thế nào (30 giây)

Mỗi lượt khách nói, bot chạy 2 làn song song:

Làn nhanh (~0.6s): model nhỏ đọc ý khách theo extract_schema, điền chỗ trống từ defaults_table, bắnstall / direct template để giữ nhịp.
Làn nghĩ (~3–6s): model lớn đọc core_prompt + đúngskill + kb cần thiết, gọitools (tra chuyến/ghế/giá) rồi soạn câu trả lời đầy đủ.

Vì vậy có file cho hiểu ý, file cho tính cách, file cho nghiệp vụ, và file cho tốc độ — mỗi nhóm bên dưới.

Bắt đầu nhanh — build một bot mới

Tạo bot ở Bot mới — để trống hoặc clone bot có sẵn (nhanh nhất là clone rồi sửa).
Hồ sơ (bot.yaml): đặt name và default_skill.
Tính cách (core_prompt.md): xưng hô, phong cách nói, và điều CẤM (không bịa giá/chuyến).
Hiểu ý khách (extract_schema.yaml): liệt kê các intent + thông tin cần bóc tách.
Nghiệp vụ chính (skills/*.md): mỗi nghiệp vụ 1 file, có id + keywords.
Kiến thức (kb/*): giá, tuyến, văn phòng… — số liệu phải chính xác.
Công cụ (tools.yaml): khai báo API bot gọi để tra cứu.
Tối ưu (nhóm ③): thêm defaults / stall / direct / responses khi muốn nhanh & mượt hơn.
Validate → Test → Lưu: bấm Validate, thêm vào bản nháp rồi mở Playground test, cuối cùng Lưu & reload (tự commit git).

Các file trong một bot

① Bắt buộc — bot chạy được

Ba file lõi. Chỉ cần chúng + một skill là bot đã trả lời được.

Hồ sơ botbot.yamlbắt buộc

Khai báo bot cho runtime: id, tên, nghiệp vụ mặc định, trỏ tới tools/responses.

Mẹo: Đổi default_skill để chọn nghiệp vụ chạy khi chưa rõ ý khách. Đừng đổi bot_id nếu bot đã chạy thật.

Tính cách & quy tắccore_prompt.mdbắt buộc

Đoạn mô tả vai trò + phong cách nói, nhét vào đầu mọi lượt — quyết định 'chất giọng' của bot.

Mẹo: Viết như lời nói (đọc qua TTS), nêu rõ xưng hô và điều CẤM (không bịa giá/chuyến).

Hiểu ý kháchextract_schema.yamlbắt buộc

Danh sách ý định (intent) bot phân loại + thông tin (entity) bot bóc tách từ câu khách.

Mẹo: Thêm intent ở mục intents; mỗi entity ghi optional và 'KHÔNG bịa nếu khách chưa nói'.

Ví dụ: intents: [booking, faq, complaint, …]

② Nội dung nghiệp vụ

Kịch bản, kiến thức và công cụ — phần "bộ não" thật sự của bot. Tách nhỏ, nạp theo nhu cầu.

Công cụ / APItools.yamlbắt buộc

Khai báo công cụ/API bot gọi ra (provider, timeout, cache, tham số).

Mẹo: required liệt kê tham số bắt buộc; cache.ttl_seconds giảm gọi lặp. Tên tool phải khớp code provider.

Ví dụ: name: get_seat_map · required: [route_code, date]

Câu phản hồi cố địnhresponses.yaml

Thư viện câu trả lời cố định theo khoá tình huống (cần tuyến, cần ngày…).

Mẹo: Mỗi khoá có 'default'; kết |CHAT (chờ khách) hoặc |ENDCALL (kết thúc).

Kịch bản nghiệp vụskills/*.mdbắt buộcnhiều file

Kịch bản chi tiết cho một nghiệp vụ — chỉ nạp khi khách rơi vào nghiệp vụ đó.

Mẹo: Frontmatter cần id + keywords để khớp. Viết các bước rõ ràng kèm câu nói mẫu.

Ví dụ: --- id: dat_ve · keywords: [đặt vé, mua vé] ---

Kiến thức tra cứukb/*nhiều file

Kiến thức nền để tra cứu (giá, tuyến, văn phòng…). Nạp theo nhu cầu, không nhồi hết.

Mẹo: Ghi keywords để bot tìm đúng. Số liệu phải chính xác — bot trích thẳng từ đây.

Tình huống đặc biệtedge_cases/*.mdnhiều file

Hướng xử lý tình huống đặc biệt/ngoại lệ, nạp khi phát hiện đúng ca.

Mẹo: Mỗi file một ca (thú cưng, khứ hồi, Tết…). Nêu điều kiện nhận diện + cách đáp.

③ Tối ưu tốc độ & độ mượt

Không bắt buộc. Thêm khi muốn bot phản hồi nhanh hơn / giữ nhịp cuộc gọi tự nhiên hơn.

Giá trị mặc địnhdefaults_table.yaml

Điền sẵn giá trị cho slot còn trống TRƯỚC khi quyết định gọi tool.

Mẹo: Chỉ default slot an toàn (ngày → mai, số lượng → 1). KHÔNG default slot quan trọng như tuyến.

Câu giữ nhịpstall_templates.yaml

Câu 'giữ máy' bot nói khi đang chờ tool/đang nghĩ — khách không bắt buộc trả lời.

Mẹo: Mỗi câu kèm safe_default để khách im vẫn đi tiếp. Kết câu bằng |CHAT.

Câu mẫu nhanhdirect_templates.yaml

Câu trả lời bắn thẳng cho tình huống đơn giản, bỏ qua AI (nhanh, rẻ, chắc chắn).

Mẹo: Dùng cho chào/tạm biệt/câu cố định. |ENDCALL để kết thúc, |CHAT để chờ khách.

Các trường trong bot.yaml

bot_id	Mã bot duy nhất (thư mục bots/<bot_id>). Đừng đổi khi bot đã chạy thật.
name	Tên hiển thị (vd "Long Vân").
default_skill	Nghiệp vụ chạy khi chưa rõ ý khách — phải trỏ tới một file trong skills/.
core_prompt	Tên file tính cách (mặc định core_prompt.md).
tools_file	Tên file khai báo công cụ/API (mặc định tools.yaml).
responses_file	Tên file câu phản hồi cố định (mặc định responses.yaml).
description	Mô tả ngắn bot làm gì — cho người vận hành, không đưa vào prompt.
alternate_bot_ids	(Tuỳ chọn) các id gọi thay thế, vd mã số tổng đài.

Quy ước quan trọng

Marker cuối câu

Câu trong template/responses kết thúc bằng một marker cho runtime biết làm gì tiếp:

|CHAT — chờ khách nói tiếp (giữ máy).
|ENDCALL — kết thúc cuộc gọi (chào tạm biệt).

Frontmatter cho skill / kb / edge

Mỗi file mở đầu bằng khối YAML để runtime khớp đúng file với câu khách:

--- id: dat_ve · keywords: [đặt vé, mua vé] ---

keywords càng sát cách khách nói thì bot nạp đúng file càng chuẩn.

Nguyên tắc vàng: không bịa

Giá, chuyến, ghế phải đến từ tool hoặc kb. Thiếu dữ kiện thì hỏi lại hoặc hẹn nhân viên — tuyệt đối không đoán số.

Tách nhỏ, nạp theo nhu cầu

skill / kb / edge_case chỉ được nạp khi khớp ý khách. Cứ tách mỗi việc một file thay vì nhồi một file khổng lồ — bot chạy nhanh và đỡ nhiễu hơn.

Luồng làm việc an toàn

Validate — bắt lỗi cú pháp/thiếu trường trước khi lưu.
Thêm vào nháp → Playground (draft) — test thay đổi CHƯA commit, không ảnh hưởng bot đang chạy.
Lưu & reload — ghi file, hot-reload runtime, và tự tạo git commit.
History — xem diff từng lần sửa và rollback nếu cần.

Mở một bot ở Dashboard rồi vào tab Content để bắt đầu sửa — helpbox từng file ở đó nhắc lại đúng phần hướng dẫn này.