Client actions

Client action cho phép agent làm được việc trong ứng dụng của bạn: mở màn hình, gọi API client-side, cuộn tới mục — mọi thứ trình duyệt làm được. Khác với HTTP tool (server gọi API của bạn), client action chạy phía người dùng, nơi dữ liệu phiên đăng nhập sẵn có.

Cấu hình

1. Trong Studio, mở tab Công cụ của agent và thêm client action (tên khớp [a-z0-9_]{3,32}; tên bị đặt trước như request_handoff không dùng lại được).
2. Publish agent.
3. Phía ứng dụng chủ đăng ký handler bằng tên action:

client.registerAction("open_screen", async (args) => {
  router.push(String(args.screen));
  return { ok: true }; // kết quả đưa lại cho agent
});

Widget cũng đăng ký được: widget.registerAction(name, handler).

Hợp đồng chạy

Agent ──► data channel (không topic, envelope {type,payload})
          { type: "action.requested", payload: { requestId, name, args } }
Ứng dụng chủ ──► { type: "action.result", payload: { requestId, result | error } }

• Agent chờ kết quả tối đa 15 giây (ACTION_TIMEOUT_SECONDS); quá hạn coi như thất bại và nói câu chờ.
• Sau 0,8 s chưa có kết quả, agent nói câu chờ ngắn để người dùng không tưởng treo.
• Kết quả từ trình duyệt là dữ liệu không tin cậy: agent gắn nhãn và cắt còn 1.500 ký tự trước khi đưa vào hội thoại.

Thiết kế handler an toàn

• Không tin args: validate kiểu và giá trị trước khi dùng (ví dụ whitelist tên màn hình cho phép mở).
• Không trả dữ liệu nhạy cảm vào result — kết quả đi vào ngữ cảnh hội thoại của agent.
• Handler phải hoàn tất nhanh; xử lý dài thì trả { queued: true } và làm nền.

Phạm vi hỗ trợ

Client action hoạt động trên widget và SDK Web. Trang hosted và Playground chưa có handler nên action trả lỗi { error } — hãy nhúng bằng widget/SDK nếu agent dùng action.