Tổng Quan Kiến Trúc

Simplize Agent WebSocket là gì?

Simplize Agent WebSocket là giao thức streaming hai chiều cho phép client nhận kết quả từ AI agent theo thời gian thực. Agent xử lý ở phía server (background), client có thể ngắt kết nối và kết nối lại bất kỳ lúc nào mà không mất dữ liệu.

So Sánh WebSocket và SSE

Tiêu chí	SSE (HTTP)	WebSocket
Endpoint	`POST /v2/chat`	`wss://host/v2/ws`
Loại kết nối	Mỗi request tạo kết nối mới	Kết nối persistent
Reconnect	Re-fetch kèm `Last-Event-ID`	`subscribe` với `last_event_id`
Multi-turn chat	Mỗi lượt là 1 HTTP request	Nhiều lượt trên 1 kết nối
Dừng agent	`POST /v2/sessions/{id}/terminate`	`{"type": "stop", ...}`
Phê duyệt tool	Polling API riêng	Inline qua cùng kết nối

Khuyến nghị: Dùng WebSocket cho chat UI cần tương tác cao, reconnect liền mạch và HITL approval.

Luồng Tổng Quan

Client                      Server
  │                            │
  │──── kết nối ──────────────▶│
  │◀─── connected ─────────────│  ← thông số kết nối
  │                            │
  │──── auth {token} ─────────▶│  ← JWT bearer token
  │◀─── auth_ok ───────────────│
  │                            │
  │──── chat {message} ───────▶│  ← bắt đầu lượt mới
  │◀─── subscribed {running} ──│  ← task đã khởi động
  │                            │
  │◀─── message_start ─────────│
  │◀─── content_block_start ───│  ← block thinking
  │◀─── content_block_delta ───│  (streaming...)
  │◀─── content_block_stop ────│
  │◀─── content_block_start ───│  ← block text
  │◀─── content_block_delta ───│  (streaming...)
  │◀─── content_block_stop ────│
  │◀─── message_delta ─────────│
  │◀─── message_stop ──────────│  ← lượt hoàn thành

Vòng Đời Session

Mỗi session đại diện cho một chuỗi hội thoại liên tục (nhiều lượt với cùng context).

Tạo session mới:
  chat (không có session_id)
    → server tạo session_id
    → subscribed {session_id, status: "running"}

Lượt tiếp theo trong session:
  chat {session_id: "uuid"}
    → subscribed {status: "running"}

Reconnect giữa chừng:
  subscribe {session_id, last_event_id}
    → subscribed {status: "running"}
    → replay events còn thiếu + tiếp tục live

Reconnect sau khi xong:
  subscribe {session_id, last_event_id}
    → subscribed {status: "completed"}
    → replay events còn thiếu, sau đó dừng

Gửi message khi agent đang bận:
  chat {session_id} hoặc push_message
    → message_queued (xếp hàng, tự động xử lý sau)

Vòng Đời Một Lượt (Turn)

Mỗi lượt agent trả lời luôn bắt đầu bằng message_start và kết thúc bằng message_stop. Giữa hai event này là các block nội dung.

message_start
  content_block_start  (index: 0, type: "thinking")
  content_block_delta  × N
  content_block_stop

  content_block_start  (index: 1, type: "tool_use")
  content_block_delta  × N
  content_block_stop

  content_block_start  (index: 2, type: "tool_result")
  content_block_delta  × N
  content_block_stop

  content_block_start  (index: 3, type: "text")
  content_block_delta  × N
  content_block_stop

message_delta
message_stop

index là số nguyên tăng dần từ 0 trong phạm vi một lượt.

Trạng Thái Session

Trạng thái	Mô tả
`running`	Agent đang xử lý, có thể subscribe để nhận live events
`completed`	Agent đã xong, có thể replay lịch sử events

Event Replay (Không Mất Dữ Liệu)

Mọi event được server lưu lại có thứ tự, mỗi event có event_id dạng UUID v7 (sortable theo thời gian). Client lưu event_id cuối cùng nhận được, dùng khi reconnect để nhận lại các events còn thiếu.

TTL của event log: 1 giờ sau khi session hoàn thành.

Danh Sách Đầy Đủ Tất Cả Events

Client → Server

type	Bắt buộc sau	Mô tả
`auth`	`connected`	Xác thực
`chat`	`auth_ok`	Bắt đầu lượt hội thoại
`subscribe`	`auth_ok`	Đăng ký nhận events session có sẵn
`stop`	`auth_ok`	Dừng agent
`push_message`	`auth_ok`	Xếp hàng message
`approval`	nhận `approval_request`	Phê duyệt / trả lời
`ping`	bất kỳ lúc nào	Keep-alive
`pong`	nhận `ping`	Phản hồi keep-alive

Server → Client

type	Nhóm	Mô tả
`connected`	Control	Kết nối thành công
`auth_ok`	Control	Xác thực thành công
`subscribed`	Control	Đã đăng ký stream
`message_queued`	Control	Message đã xếp hàng
`ping`	Control	Keep-alive từ server
`pong`	Control	Phản hồi ping từ client
`error`	Control	Lỗi
`message_start`	Turn	Bắt đầu lượt agent
`message_delta`	Turn	Lý do kết thúc lượt
`message_stop`	Turn	Kết thúc lượt
`content_block_start`	Block	Bắt đầu block
`content_block_delta`	Block	Nội dung block
`content_block_stop`	Block	Kết thúc block

Block Types (trong `content_block_start.content_block.type`)

type	Xuất hiện khi	Có delta không
`thinking`	Đầu lượt, Claude suy luận	Có (`thinking_delta`)
`text`	Câu trả lời văn bản	Có (`text_delta`)
`tool_use`	Agent gọi tool	Có (`input_json_delta`)
`tool_result`	Sau khi tool thực thi xong	Có (`tool_result_delta`)
`file_processing`	Có `content_urls` trong chat	Có (cập nhật `status`)
`approval_request`	Tool cần phê duyệt	Không
`approval_result`	Sau khi user quyết định	Có (`decisions`)
`approval_timeout`	Hết thời gian phê duyệt	Không
`terminal_user_stopped`	User gửi lệnh `stop`	Có (`terminal_user_stopped`)
`terminal_error`	Lỗi agent không phục hồi	Có (`terminal_error`)

Simplize Agent WebSocket là gì?​

So Sánh WebSocket và SSE​

Luồng Tổng Quan​

Vòng Đời Session​

Vòng Đời Một Lượt (Turn)​

Trạng Thái Session​

Event Replay (Không Mất Dữ Liệu)​

Danh Sách Đầy Đủ Tất Cả Events​

Client → Server​

Server → Client​

Block Types (trong content_block_start.content_block.type)​