Vì sao nên kết nối agent AI với ứng dụng qua API

API agent AI là gì?

Một API agent AI cho phép phần mềm của bạn gửi tin nhắn đến một agent bạn đã tạo sẵn và nhận lại câu trả lời. Agent giữ nguyên hướng dẫn, kiến thức, mô hình, công cụ và quy tắc an toàn. Ứng dụng của bạn chỉ cần gửi câu hỏi.

Đó là điểm khác với API mô hình thô. API mô hình chỉ cho bạn khả năng sinh văn bản và để phần còn lại cho bạn tự lo: prompt, tìm kiếm tài liệu, bộ nhớ, giới hạn tần suất, tính phí. REST API của IMFA cho bạn một agent được quản lý đã có sẵn tất cả những thứ đó, phía sau một khóa riêng cho từng agent.

Bạn tạo agent bằng trình tạo chatbot AI. API là thêm một nơi agent có thể trả lời, bên cạnh website, WhatsApp, Instagram, Facebook, Telegram, Discord và đường dây giọng nói.

Khi nào nên kết nối agent qua API?

Hãy dùng API khi cuộc trò chuyện diễn ra bên trong sản phẩm của chính bạn:

• Ứng dụng hoặc cổng khách hàng của bạn cần một trợ lý hỗ trợ hiểu chính sách của bạn, mà không phải duy trì thêm một chatbot thứ hai.
• Backend của bạn cần trả lời câu hỏi từ hệ thống khác, như trang đơn hàng, công cụ đặt lịch hoặc dashboard nội bộ.
• Bạn muốn đưa khách hàng tiềm năng vào CRM. API trả về các khách tiềm năng mà agent thu thập trên mọi kênh, để bạn đồng bộ theo lịch.
• Bạn cần lịch sử hội thoại để báo cáo hoặc kiểm tra chất lượng.

Nếu bạn chỉ cần một bong bóng chat trên website, đoạn mã nhúng một dòng sẽ đơn giản hơn. API dành cho khi giao diện là sản phẩm của bạn, không phải widget.

API agent của IMFA hoạt động thế nào

Base URL là https://site.imfa.app/v1. Mọi lệnh gọi cần khóa của agent và phải đến từ mã chạy trên server đáng tin cậy, không bao giờ từ trình duyệt hay gói ứng dụng di động.

1. Xuất bản agent. Thiết lập hướng dẫn, kiến thức, mô hình và công cụ trong IMFA, thử bằng câu hỏi thật rồi xuất bản. API phục vụ phiên bản đã xuất bản.
2. Tạo khóa. Mở mục API của agent hoặc màn hình API Keys và tạo khóa. Khóa chỉ hiển thị một lần và chỉ được lưu dưới dạng hash. Giữ khóa trong biến môi trường trên server, ví dụ IMFA_API_KEY.
3. Gửi yêu cầu chat. POST /v1/agents/{slug}/chat với Authorization: Bearer <key>, một Idempotency-Key duy nhất (8 đến 128 ký tự) và body JSON gồm message cùng sessionId tùy chọn. Câu trả lời trả về kèm sessionId và usage.credits.
4. Tiếp tục cuộc trò chuyện. Bỏ trống sessionId ở lượt đầu, sau đó gửi lại đúng giá trị bạn nhận được. Agent sẽ nhớ ngữ cảnh.
5. Xem lại những gì đã diễn ra. GET /v1/agents/{slug}/sessions liệt kê các cuộc hội thoại, GET /v1/agents/{slug}/sessions/{sessionId}/messages đọc một cuộc, và GET /v1/agents/{slug}/leads trả về khách tiềm năng đã thu thập. Danh sách mặc định trả về 20 mục, tối đa 100, kèm cursor. GET /v1/agents xác nhận khóa đang phục vụ agent nào.

Giới hạn được nêu rõ: chỉ 4.000 ký tự đầu của tin nhắn được dùng, body tối đa 64.000 byte, và lỗi được phân loại (xác thực dữ liệu, xác thực danh tính, credit, giới hạn tần suất, server). Mã 429 đi kèm Retry-After; mã 402 nghĩa là chủ sở hữu đã hết credit.

Vì sao nên dùng API agent thay vì tự xây

Bạn bỏ qua nhiều tháng làm hạ tầng. Tìm kiếm tài liệu, phiên hội thoại, giới hạn tần suất, thử lại, tính credit và quy tắc chống prompt injection đã chạy sẵn. Đội của bạn chỉ cần viết một lệnh gọi HTTP.

Một agent, một cách hành xử. Câu trả lời ứng dụng của bạn hiển thị cũng chính là câu trả lời trên website và WhatsApp, vì đó là cùng một agent. Cập nhật một lần trong IMFA, mọi nơi đều theo.

Thử lại an toàn. Idempotency key giúp một lần thử lại do lỗi mạng trả về câu trả lời ban đầu, thay vì tính phí thêm một lượt.

Khách tiềm năng không còn nằm rải rác. Lấy mọi khách tiềm năng đã thu thập qua một endpoint duy nhất, dù họ đến từ kênh nào.

Bạn vẫn có thể tự làm hoàn toàn. Nếu cần kiểm soát mọi lớp, API mô hình thô cho bạn quyền đó, đổi lại bạn phải tự xây và tự vận hành. Các coding agent như Codex và Claude Code cũng có thể quản lý agent IMFA qua MCP, trong khi server của bạn dùng khóa REST để phục vụ khách hàng.

Câu hỏi thường gặp về API agent AI

Tôi có gọi API agent AI trực tiếp từ trình duyệt được không?

Không. Khóa tiêu credit của chủ sở hữu và phải nằm trên server đáng tin cậy. API không mở quyền truy cập rộng từ trình duyệt. Hãy để trình duyệt gọi endpoint được bảo vệ của chính bạn, rồi endpoint đó gọi IMFA.

Làm sao xác thực một yêu cầu API agent IMFA?

Tạo khóa riêng cho agent trong mục API của agent hoặc màn hình API Keys, sau đó gửi Authorization: Bearer YOUR_API_KEY từ mã server. Token MCP là một loại thông tin xác thực khác và không dùng được ở đây.

Làm sao tiếp tục cùng một cuộc trò chuyện qua API?

Bỏ trống sessionId ở yêu cầu chat đầu tiên, lưu sessionId mà API trả về và gửi kèm ở tin nhắn tiếp theo. Session ID từ cuộc trò chuyện trên website hoặc các kênh khác chỉ để đọc và không thể tiếp tục một cuộc trò chuyện API.

Vì sao chat bắt buộc phải có Idempotency-Key?

Để việc thử lại được an toàn. Một lần thử lại giống hệt với cùng khóa sẽ trả về cùng kết quả thay vì tạo lượt mới. Hãy dùng khóa mới cho mỗi tin nhắn mới.

API agent có dùng kiến thức và công cụ của tôi không?

Có. API gọi agent đã xuất bản với hướng dẫn, mô hình, kiến thức, skill, công cụ và quy tắc an toàn của nó. Câu trả lời vẫn phụ thuộc vào cấu hình đã xuất bản, số credit của bạn và giới hạn dịch vụ hiện tại.

Chuyện gì xảy ra khi API bị giới hạn tần suất hoặc hết credit?

Bạn nhận mã 429 kèm header Retry-After khi bị giới hạn tần suất, và mã 402 khi chủ sở hữu hết credit. Hãy xử lý mọi mã trạng thái được mô tả trong tài liệu khi tích hợp.