Simplize Agent WebSocket — Tài Liệu Tích Hợp

Tài liệu này dành cho frontend developer, mobile developer, và đối tác tích hợp muốn kết nối với Simplize Financial Agent qua WebSocket.

---

Mục Lục

File	Nội dung
Tổng quan kiến trúc	Kiến trúc tổng quan, vòng đời session, danh sách tất cả events
Kết nối & Xác thực	Kết nối WebSocket, xác thực JWT, heartbeat
Lệnh Client	Các lệnh client gửi lên server
Event Stream	Định dạng event stream, tất cả block types kèm ví dụ
Tool Calls	Tool call events, cách render trạng thái
Phê duyệt (HITL)	Luồng phê duyệt tool call (Human-in-the-Loop)
Hỏi Người Dùng	Luồng agent hỏi ngược lại người dùng
History API	HTTP API lấy lịch sử hội thoại
Reconnect & Timeout	Xử lý reconnect, server restart, các timeout
Message Reference	Reference đầy đủ tất cả message types (client↔server)
Widget System	Widget system — parse, render, tất cả widget types

---

Quick Start — Luồng Tối Thiểu

const ws = new WebSocket('wss://api.simplize.vn/v2/ws')

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data)

  switch (msg.type) {
    case 'connected':
      ws.send(JSON.stringify({ type: 'auth', token: accessToken }))
      break

    case 'auth_ok':
      ws.send(JSON.stringify({
        type: 'chat',
        message: 'Phân tích cổ phiếu VNM',
      }))
      break

    case 'ping':
      ws.send(JSON.stringify({ type: 'pong' }))
      break

    case 'subscribed':
      console.log('Session:', msg.session_id, 'Status:', msg.status)
      break

    case 'message_start':
      console.log('Agent bắt đầu trả lời')
      break

    case 'content_block_delta':
      if (msg.delta?.type === 'text_delta') {
        process.stdout.write(msg.delta.text)
      }
      break

    case 'message_stop':
      console.log('\nXong sau', msg.duration_ms, 'ms')
      break
  }
}

---

Tham Chiếu Nhanh — Toàn Bộ Events

Client → Server

type	Mô tả
auth	Xác thực với JWT token
chat	Bắt đầu lượt hội thoại mới
subscribe	Đăng ký nhận events của session có sẵn
stop	Dừng agent đang chạy
push_message	Xếp hàng message khi agent đang bận
approval	Gửi quyết định phê duyệt / trả lời câu hỏi
ping / pong	Keep-alive

Server → Client (Điều Khiển)

type	Mô tả
connected	Kết nối thành công, kèm thông số kết nối
auth_ok	Xác thực thành công
subscribed	Đã đăng ký stream thành công
message_queued	Message đã được xếp hàng chờ xử lý
ping / pong	Keep-alive
error	Lỗi protocol hoặc nghiệp vụ

Server → Client (Agent Output)

type	Mô tả
message_start	Bắt đầu một lượt agent trả lời
message_delta	Lý do kết thúc lượt
message_stop	Kết thúc lượt, kèm thời gian xử lý
content_block_start	Bắt đầu một block nội dung
content_block_delta	Nội dung tiếp theo của block
content_block_stop	Kết thúc block

Block Types (trong content_block_start)

type	Khi nào xuất hiện
thinking	Claude đang suy luận (chain of thought)
text	Câu trả lời văn bản của AI
tool_use	Agent gọi một công cụ
tool_result	Kết quả thực thi công cụ
file_processing	Đang xử lý file đính kèm
approval_request	Agent cần người dùng phê duyệt trước khi thực thi
approval_result	Kết quả quyết định phê duyệt
approval_timeout	Hết thời gian chờ phê duyệt
terminal_user_stopped	Người dùng đã dừng agent
terminal_error	Lỗi không thể phục hồi