Bỏ qua đến nội dung
ShopNexus Docs
Trên trang này Các bước 1/3

Một câu hỏi là một lượt (turn). Một lượt chạy thành một hay nhiều đoạn (segment): mỗi lần tạm dừng rồi chạy tiếp, hay hỏi lại moderator rồi chạy tiếp, server mở một đoạn mới trên agent, nối từ checkpoint của đoạn trước. Agent không có database; checkpoint nằm ở server, trong cột state của lượt.

Console Trình duyệt của moderator
Server Module agent, cổng API và cổng MCP
Agent Service NestJS nội bộ
LiteLLM Cổng model của stack
  1. 1 Gửi câu hỏi
    Console → Server
    POST …/turns
  2. 2 Mở một đoạn chạy
    Server → Agent
    POST /runs, mode new
  3. 3 Gọi model
    Agent → LiteLLM
    alias của agent, user = moderator
  4. 4 Model trả lời, có thể xin gọi tool
    LiteLLM → Agent
  5. 5 Gọi tool qua MCP
    Agent → Server
    /mcp, kèm id của moderator
  6. 6 Trả từng dòng NDJSON
    Agent → Server
    event, tool call, checkpoint, tài liệu
  7. 7 Phát event qua SSE
    Server → Console
    GET …/events
  8. 8 Tạm dừng hoặc chỉnh hướng
    Console → Server
    POST …/pause, …/steer
  9. 9 Hỏi lệnh điều khiển mỗi giây
    Agent → Server
    GET …/control
  10. 10 Dòng end khép đoạn
    Agent → Server
    trạng thái, câu trả lời, nguồn, chi phí
Đủ các bước của một đoạn chạy, kể cả lệnh điều khiển.

Các bước

  1. Server nhận câu hỏi

    Server kiểm phiên console, đọc agent được chọn trong ai_agents (mặc định là Console assistant), kiểm ngân sách tháng, giới hạn 30 câu hỏi và cập nhật mỗi phút cho mỗi moderator, rồi làm sạch câu hỏi: bỏ ký tự điều khiển, ký tự độ rộng 0 và thẻ HTML. Câu hỏi quá 2000 ký tự bị từ chối với agent_input_rejected. Lượt mở ở trạng thái running dưới khoá dòng của cuộc chat, và console nhận 202 {conversation_id, turn_id}.

  2. Server mở một đoạn chạy

    Server gửi POST /runs tới agent với AGENT_SERVICE_TOKEN: câu hỏi, moderator và vai trò, bản ghi đang mở, 20 lượt đã xong gần nhất làm lịch sử, và agent_config (alias model, hướng dẫn, danh sách tool, giới hạn). Server chờ agent trả trạng thái tối đa 10 giây; khác 200 thì lượt mới bị bỏ và console nhận 503 agent_unavailable.

  3. Agent mở MCP và chạy vòng lặp

    Agent mở một client MCP mới cho đoạn chạy và chỉ giữ tool có readOnlyHint nằm trong danh sách của agent. Model mở bước bằng begin_step, gọi tool, đóng bước bằng end_step với một dòng tóm tắt, và trả lời bằng answer. Trước mỗi lần gọi model, agent ghi checkpoint và đọc các lệnh điều khiển đang chờ.

  4. Từng dòng chảy về server

    Agent ghi mỗi việc thành một dòng JSON và flush ngay. Server đọc stream ở chế độ nền: dòng event được lưu với số thứ tự kế tiếp rồi báo cho các stream đang mở qua pg_notify; checkpoint lưu trạng thái để chạy tiếp; tool_call cập nhật dòng của lần gọi tool; document lưu phiên bản mới của tài liệu.

  5. Console vẽ lượt chạy

    Console mở GET /v1/console/agent/turns/{id}/events. Server phát lại các event đã lưu rồi gửi tiếp event mới, mỗi event có id là số thứ tự. Mở lại trang thì console xin từ số thứ tự cuối nó đã thấy, qua Last-Event-ID. Khi moderator đóng tab, server đóng stream và lượt vẫn chạy trên agent.

  6. Dòng end khép đoạn

    Dòng cuối mang trạng thái, câu trả lời, các khối, nguồn, chi phí, checkpoint và event đóng. Server ghi tất cả trong một transaction. Stream đứt mà không có dòng end thì lượt đóng failed với agent_stuck.

Cách một đoạn kết thúc

SUCCEEDED

Model trả lời, qua answer hoặc bằng chữ thường.

PAUSED

Pause, Stop now, lượt đã bị xoá hoặc server đóng request.

AWAITING_INPUT

Model gọi ask_user và chờ moderator.

FAILED

Model hay MCP lỗi, hết lượt gọi model, hết ngân sách.

TIMED_OUT

Qua thời hạn của đoạn, mặc định 60 giây.

PAUSED và AWAITING_INPUT chưa khép lượt: moderator chạy tiếp, trả lời hoặc kết thúc. Lượt FAILED hay TIMED_OUT chạy tiếp được trong một số trường hợp, liệt kê ở Giới hạn và lỗi.

Server dọn lượt bị treo

Mỗi replica của server giữ một LISTEN agent_turn để báo các stream của lượt. Lúc khởi động và mỗi phút, server đóng các lượt còn running quá 30 giây sau thời hạn với agent_stuck, kể cả lượt của một replica đã sập giữa chừng.

ShopNexus Docs
EN VI