Mang AI agent của riêng bạn lên WhatsApp: kết nối mọi framework (LangGraph, ADK, tùy chỉnh) bằng endpoint webhook

Bạn có thể kết nối gần như bất kỳ AI agent nào với WhatsApp mà không cần viết lại. Hãy chạy agent của bạn, được xây dựng bằng LangGraph, Google ADK, CrewAI hoặc code của riêng bạn, phía sau một endpoint HTTPS, rồi thêm nó vào MonoChat dưới dạng AI Harness với nhà cung cấp Custom: một URL endpoint và một khóa bí mật dùng chung. Đặt một node AI Agent vào luồng, kết nối số WhatsApp của bạn, và agent của bạn sẽ trả lời khách hàng trên WhatsApp cùng mọi kênh khác mà MonoChat kết nối, với hộp thư chung và chuyển giao cho nhân viên xung quanh nó.

Hướng dẫn này dành cho các đội ngũ đã có agent, hoặc muốn kiểm soát hoàn toàn cách nó hoạt động. Nội dung gồm khi nào việc mang agent của riêng bạn là hợp lý, endpoint của bạn chịu trách nhiệm những gì, cách thiết lập trong MonoChat và các chi tiết quan trọng khi chạy thực tế.

Vì sao nên mang agent của riêng bạn?

Hầu hết các nền tảng nhắn tin với khách hàng đi kèm một AI agent tích hợp sẵn. Điều đó tiện lợi cho đến khi:

• Agent của bạn đã được xây dựng. Lập trình viên của bạn đã dành nhiều tháng cho một đồ thị LangGraph hoặc một thiết lập đa agent ADK, kèm đánh giá và kiểm thử. Xây dựng lại nó trong trình tạo bot của một nhà cung cấp là bỏ phí công sức đó.
• Bạn cần logic của riêng mình. Quy tắc giá, kiểm tra điều kiện, các bước tuân thủ hoặc hệ thống nội bộ mà chỉ code của bạn mới truy cập được.
• Bạn muốn tự chọn framework. Các framework thay đổi rất nhanh. Hôm nay là LangGraph; năm sau có thể là thứ khác. Các kênh và hộp thư của bạn không nên phải thay đổi theo.
• Dữ liệu phải ở lại với bạn. Một số tổ chức muốn quá trình suy luận và gọi công cụ của agent chạy trên hạ tầng của riêng họ.

Agent Harness của MonoChat được xây dựng cho việc này: mang framework agent của riêng bạn và giữ mọi thứ xung quanh nó, các kênh, hộp thư, con người, ở cùng một nơi.

Harness Custom hoạt động như thế nào

Hãy hình dung đó là một sự phân công lao động.

MonoChat xử lý tầng cuộc trò chuyện:

• Các kết nối chính thức đến WhatsApp, Instagram, Messenger, TikTok, Telegram, web chat, SMS và thoại (MonoChat là Đối tác Kinh doanh chính thức của Meta).
• Luồng quyết định khi nào agent được gọi, thông qua node AI Agent.
• Hộp thư chung của đội ngũ, nơi một người có thể tiếp quản với đầy đủ lịch sử.

Endpoint của bạn xử lý agent:

• Nhận cuộc trò chuyện từ MonoChat.
• Chạy agent của bạn: suy luận, công cụ và bộ nhớ của nó.
• Trả về câu trả lời của agent.

Giữa hai bên là một khóa bí mật dùng chung, một giá trị cả hai bên cùng biết, để endpoint của bạn có thể xác minh rằng yêu cầu đến từ tài khoản MonoChat của bạn. MonoChat định nghĩa chính xác định dạng yêu cầu và phản hồi mà endpoint của bạn triển khai; nếu bạn chưa có, hãy liên hệ với chúng tôi và chúng tôi sẽ chia sẻ với lập trình viên của bạn.

Endpoint của bạn nên làm gì

Dù bạn dùng framework nào, một endpoint agent sẵn sàng cho môi trường thực tế có một vài nhiệm vụ.

Xác minh mọi yêu cầu

Kiểm tra khóa bí mật dùng chung ở mọi lệnh gọi và từ chối mọi thứ không khớp. Lưu khóa trong trình quản lý bí mật hoặc biến môi trường, không để trong code, và thay đổi nó nếu từng bị lộ.

Giữ mỗi cuộc trò chuyện tách biệt

Khách hàng nhắn tin song song. Hãy bảo đảm trạng thái, bộ nhớ và mọi tệp làm việc của agent chỉ thuộc phạm vi một cuộc trò chuyện, để thông tin của khách hàng này không bao giờ rò rỉ vào câu trả lời cho khách hàng khác.

Trả lời bằng các tin nhắn có kích thước phù hợp với chat

Các agent xây dựng cho ứng dụng web thường viết câu trả lời dài và có định dạng. WhatsApp được đọc trên điện thoại. Hãy yêu cầu agent viết tin nhắn ngắn, mỗi lần một câu hỏi, và tránh dùng nhiều Markdown trong câu trả lời.

Báo lỗi rõ ràng, không im lặng

Nếu một công cụ hết thời gian chờ hoặc nhà cung cấp mô hình trả về lỗi, hãy trả về một thông báo lỗi rõ ràng thay vì một câu trả lời dở dang. Một lỗi có thể dự đoán giúp luồng làm đúng việc, chẳng hạn chuyển cuộc trò chuyện cho người thật.

Phản hồi nhanh

Khách hàng mong đợi câu trả lời trong vài giây. Hãy tách các công việc chạy lâu ra khỏi đường trả lời khi có thể, và làm cho các công cụ của bạn nhanh hoặc bất đồng bộ.

Từng bước trong MonoChat

1. Triển khai agent của bạn phía sau HTTPS

Lưu trữ agent LangGraph, ADK, CrewAI hoặc tùy chỉnh của bạn trên máy chủ hoặc đám mây của riêng bạn, có thể truy cập qua HTTPS. Triển khai định dạng yêu cầu và phản hồi của MonoChat cùng bước kiểm tra khóa bí mật dùng chung.

2. Thêm một AI Harness với nhà cung cấp Custom

Trong MonoChat, thêm một AI Harness, chọn Custom và nhập URL endpoint cùng khóa bí mật dùng chung của bạn. Bạn chỉ thêm harness một lần và có thể dùng trong bao nhiêu luồng tùy thích.

3. Thêm node AI Agent vào một luồng

Trong luồng nhận các cuộc trò chuyện đến, thêm một node AI Agent và chọn harness tùy chỉnh của bạn. Hãy dùng phần luồng xung quanh cho những việc luồng làm tốt nhất: chào hỏi, định tuyến theo ngôn ngữ hoặc chủ đề, giờ làm việc và đường dẫn đến người thật.

4. Đặt ngân sách cho mỗi lượt chạy

Mỗi node AI Agent hỗ trợ giới hạn ngân sách cho mỗi lượt chạy. Hãy dùng chúng như một lưới an toàn bên cạnh các giới hạn bạn đã áp dụng trong code của riêng mình.

5. Kết nối WhatsApp và các kênh khác

Kết nối số WhatsApp Business của bạn, rồi gắn cùng luồng đó vào các kênh khác bạn sử dụng. Không có công việc tích hợp bổ sung cho từng kênh: endpoint của bạn thấy các cuộc trò chuyện, không phải API của kênh.

6. Kiểm thử, rồi đưa vào hoạt động

Phát lại các tin nhắn khách hàng thật qua luồng. Kiểm tra các lệnh gọi công cụ, thời gian phản hồi, giọng điệu và chuyển giao. Theo dõi sát những ngày đầu của lưu lượng thật, rồi mở rộng dần những gì agent được phép làm.

Ghi chú về các framework

LangGraph. Một đồ thị gồm các node và cạnh rất phù hợp với hành trình hỗ trợ (phân loại, tra cứu, giải quyết, chuyển cấp). Hãy bọc đồ thị đã biên dịch trong một dịch vụ HTTP nhỏ, tải trạng thái của cuộc trò chuyện ở mỗi yêu cầu và trả về tin nhắn cuối cùng.

Google ADK. Cây đa agent của ADK, một bộ điều phối cùng các sub-agent chuyên biệt, tương ứng tốt với các đội hỗ trợ, bán hàng và thanh toán. Hãy mở agent gốc qua endpoint của bạn và để ADK tự định tuyến bên trong.

CrewAI. Các crew gồm những agent theo vai trò hoạt động tốt với các nhiệm vụ có bước bàn giao rõ ràng, chẳng hạn nghiên cứu rồi trả lời. Hãy giữ crew nhỏ cho chat: mỗi agent thêm vào làm tăng độ trễ.

Code của riêng bạn. Một vòng lặp thuần với API mô hình và vài hàm thường là đủ. Bạn giữ toàn quyền kiểm soát, còn MonoChat cung cấp các kênh và hộp thư.

Chuyển giao: quyết định ngay trong luồng

Hãy quyết định trong luồng những cuộc trò chuyện nào chuyển cho người thật và đội nào nhận chúng, và viết agent của bạn sao cho nó nói thật với khách hàng khi không thể giúp thay vì đoán mò. Sau đó luồng chuyển cuộc trò chuyện cho đúng đội trong hộp thư chung với đầy đủ lịch sử. Chính sách Nhắn tin Doanh nghiệp của WhatsApp cũng mong đợi các câu trả lời tự động cung cấp đường dẫn rõ ràng đến người thật.

Hãy giữ agent của bạn trong phạm vi doanh nghiệp. Từ ngày 15 tháng 1 năm 2026, WhatsApp không cho phép các trợ lý AI đa dụng trên nền tảng; các agent phục vụ chính khách hàng của bạn thì được. Hướng dẫn về chính sách chatbot AI của WhatsApp của chúng tôi giải thích quy tắc này.

Khi nào không nên tự xây dựng

Agent tùy chỉnh là lựa chọn linh hoạt nhất và cũng là lựa chọn bạn phải bảo trì. Nếu bắt đầu từ đầu, một lựa chọn tích hợp sẵn giúp bạn đưa vào hoạt động nhanh hơn mà không phải lưu trữ gì:

• Harness tích hợp sẵn của MonoChat trên các mô hình AI MonoChat của bạn.
• OpenAI Agents SDK, chạy bên trong MonoChat (hướng dẫn).
• Claude Agent SDK hoặc Pi, chạy trên agent runner của MonoChat (hướng dẫn Claude).
• Agent được lưu trữ: OpenAI Agents API hoặc Claude Managed Agents, với khóa của riêng bạn.

Vì mọi lựa chọn đều dùng cùng một node AI Agent, bạn có thể bắt đầu với một lựa chọn và chuyển sang agent của riêng bạn sau này mà không động đến các kênh hay chuyển giao. So sánh chúng trên trang Agent Harness.