Xử lý sự cố kết nối Agent AI

Phần lớn sự cố kết nối Agent AI xử lý được ngay trong trang Kết nối Agent AI: xem cột Dùng lần cuối, trạng thái và các lệnh gần đây kèm mã lỗi, rồi tạo key mới, kết nối lại hoặc bật lại webhook.

Mỗi mục dưới đây đi theo thứ tự Dấu hiệu → Nguyên nhân → Cách xử lý. Mã lỗi Agent AI nhận được khi một lệnh không làm được nằm ở trang Mã lỗi.

Agent AI báo 401 hoặc invalid_token thì làm gì?

• Dấu hiệu: mọi lệnh đều bị từ chối với mã 401, có khi kèm invalid_token.
• Nguyên nhân: API key gõ sai hoặc thiếu ký tự, key đã bị thu hồi, hoặc kết nối của ứng dụng Agent AI đã hết hạn.
• Cách xử lý: mở trang Kết nối Agent AI, tìm kết nối đó và xem trạng thái cùng cột Dùng lần cuối. Key đã thu hồi hoặc mất thì bấm Tạo API key để tạo key mới rồi dán vào công cụ của bạn; kết nối ứng dụng hết hạn thì kết nối lại theo trang Kết nối Agent AI.

Agent AI báo 503 thì làm gì?

• Dấu hiệu: mọi lệnh trả 503, trang Kết nối Agent AI hiện dòng "Kết nối Agent AI đang tạm tắt".
• Nguyên nhân: tính năng kết nối Agent AI đang tạm tắt trên hệ thống.
• Cách xử lý: giữ nguyên key và kết nối hiện có. Các kết nối đã có sẽ hoạt động lại khi tính năng mở, không cần tạo lại.

Agent AI báo 429 thì làm gì?

• Dấu hiệu: lệnh trả 429 sau một loạt lệnh gọi liên tiếp.
• Nguyên nhân: Agent AI gọi quá dồn trong thời gian ngắn.
• Cách xử lý: chờ một phút rồi thử lại. Nếu Agent AI tự gọi lệnh liên tục, dặn nó gọi thưa hơn và gộp việc vào ít lệnh hơn.

Agent AI báo thiếu quyền thì làm gì?

• Dấu hiệu: lệnh trả mã SCOPE_INSUFFICIENT.
• Nguyên nhân: kết nối chỉ có quyền Đọc, trong khi lệnh cần quyền Sửa dữ liệu hoặc Ra lệnh máy.
• Cách xử lý: với API key, tạo key mới có đúng quyền cần dùng rồi thu hồi key cũ. Với ứng dụng đã kết nối, kết nối lại ứng dụng và tích thêm quyền trên màn đồng ý. Ý nghĩa từng quyền: Bậc hậu quả.

Agent AI không thấy lệnh mới hoặc vẫn gọi lệnh đã ngừng thì làm gì?

• Dấu hiệu: Agent AI không biết một lệnh vừa ra mắt, hoặc nhận mã TOOL_RETIRED khi gọi lệnh cũ.
• Nguyên nhân: ứng dụng Agent AI còn giữ danh sách lệnh cũ từ lần kết nối trước.
• Cách xử lý: làm mới kết nối trong ứng dụng Agent AI; các bước cho từng ứng dụng nằm ở trang Kết nối Agent AI. Lịch ngừng hỗ trợ và tên thay thế nằm ở trang Thay đổi hợp đồng.

Màn đồng ý báo lỗi thì làm gì?

• Dấu hiệu: màn đồng ý báo "Yêu cầu kết nối đã hết hạn", hiện nhãn Ứng dụng chưa xác minh, hoặc báo "Đã đạt số kết nối tối đa".
• Nguyên nhân: yêu cầu kết nối chỉ dùng được trong một thời gian ngắn; ứng dụng xin kết nối không thuộc danh sách đã xác minh; hoặc tài khoản đã có đủ số kết nối cho phép.
• Cách xử lý: hết hạn thì quay lại ứng dụng Agent AI và bấm kết nối lần nữa. Ứng dụng chưa xác minh thì chỉ bấm Cho phép khi chính bạn vừa bấm kết nối trong ứng dụng đó. Đạt số kết nối tối đa thì thu hồi một kết nối không còn dùng trong trang Kết nối Agent AI rồi kết nối lại.

Đổi mật khẩu có ngắt Agent AI không?

• Dấu hiệu: bạn đã đổi mật khẩu hoặc đăng xuất mọi thiết bị, nhưng Agent AI vẫn gọi lệnh được.
• Nguyên nhân: API key và kết nối ứng dụng chỉ mất hiệu lực khi bạn tự thu hồi; đổi mật khẩu không thu hồi chúng.
• Cách xử lý: muốn ngắt Agent AI thì bấm Thu hồi ở từng kết nối, hoặc Thu hồi ứng dụng để ngắt mọi kết nối của một ứng dụng, trong trang Kết nối Agent AI.

Webhook không nhận được sự kiện thì làm gì?

• Dấu hiệu: hệ thống của bạn không nhận được sự kiện nào, hoặc webhook hiện trạng thái đã tự tắt.
• Nguyên nhân: URL không bắt đầu bằng https://; webhook đã tự tắt sau nhiều lần gửi không được; hoặc sự kiện bạn cần chưa được tích.
• Cách xử lý: kiểm tra URL bắt đầu bằng https:// và trỏ tới một địa chỉ công khai, tích đúng sự kiện cần nhận, sửa hệ thống nhận rồi bấm Bật lại nếu webhook đã tự tắt. Bấm Gửi thử để nhận một sự kiện mẫu và xác nhận đường gửi đã thông. Chi tiết: Webhook.

Chữ ký webhook không khớp thì làm gì?

• Dấu hiệu: hệ thống nhận tính ra chữ ký khác giá trị trong header X-Tds-Signature.
• Nguyên nhân: chữ ký được tính trên thân request đã parse rồi ghi lại, thiếu timestamp, hoặc dùng sai secret.
• Cách xử lý: tính HMAC-SHA256 trên chuỗi <X-Tds-Timestamp>.<thân request nguyên văn>, khoá là nguyên chuỗi secret kể cả tiền tố. Đã xoay secret thì cập nhật secret mới vào hệ thống nhận. Mã mẫu nằm ở trang Webhook.

Webhook nhận trùng sự kiện thì làm gì?

• Dấu hiệu: cùng một sự kiện tới hệ thống của bạn hơn một lần, hoặc có sự kiện mang test: true.
• Nguyên nhân: Tự Động Sale gửi lại khi hệ thống nhận không trả mã 2xx kịp; sự kiện mang test: true là lượt Gửi thử.
• Cách xử lý: lưu id của sự kiện đã xử lý và bỏ qua bản trùng; bỏ qua hoặc chỉ ghi log các sự kiện có test: true. Bảng trường của từng sự kiện: Tham chiếu webhook.

Lỡ dán API key vào khung chat thì làm gì?

Không bao giờ dán API key hay secret webhook vào khung chat với bất kỳ ai, kể cả Agent AI hỗ trợ trong ứng dụng. Agent AI hỗ trợ tự che mã bí mật trước khi lưu, nhưng mã đã rời khỏi tay bạn thì coi như đã lộ: thu hồi key đó (hoặc xoay secret webhook) trong trang Kết nối Agent AI rồi tạo mã mới.