Skip to content
ShopNexus Docs
On this page The four parts 1/4

A moderator opens a ticket, a report case or an account in the console and asks the agent a question in plain words. The agent picks tools to read the data, splits the work into named steps and answers with text, key figures, tables or charts. Each claim in the answer carries a number such as 1 that points to the record it came from.

The agent can

  • Read tickets, report cases, accounts, orders, listings and the console's audit log
  • Count, summarise and compare a listing's price with similar listings
  • Write documents with versions inside the chat
  • Ask the moderator back when a question is unclear

Outside the agent's reach

  • Suspending, hiding or messaging: the moderator does these in the console
  • Following text users wrote in messages, notes or listing descriptions
  • Requests from outside: only the server can call it, on the internal network
  • Storage: the server keeps every chat, run and tool call

The read-only rule is BR-MOD-03. The agent has no tool that changes data, so a prompt injection hidden in a user’s message can at worst produce a wrong proposal, which a moderator then reviews.

The four parts

The console calls only the server. The server starts each run segment on the agent. The agent calls the model through LiteLLM and reads data through the MCP server that the server opens on a port of its own. Everything the agent does flows back to the server as lines; the server stores them and sends them on to the console.

Console The moderator asks and watches each step
Server Checks the session, stores the turn, sends events
Agent The model loop, with no database
LiteLLM Picks the model, counts the budget
  1. 1 Send the question
    Console → Server
    POST …/turns answers 202 at once
  2. 2 Start a segment
    Server → Agent
    POST /runs with the agent's config
  3. 3 Call the model
    Agent → LiteLLM
    user is the moderator's id
  4. 4 Read data through MCP
    Agent → Server
    read-only tools, the member checked on each call
  5. 5 Stream NDJSON lines
    Agent → Server
    events, tool calls, checkpoints, end
  6. 6 Send events over SSE
    Server → Console
    closing the tab leaves the run going
One question through the four parts. Dashed arrows are data flowing back.

The agent is a NestJS service of its own in the shopnexus/agent repo, running a Strands loop on the model LiteLLM picks. The decision to run it apart and have it read through the server’s MCP is ADR-0003.

The moderator’s screen

A run shows up as it happens: each step with a one-line summary, each tool call with its timing, then the answer and its sources. While it runs, the moderator presses Pause (or Esc), or types a line to steer the agent.

A finished run on a report case. The data is an example.

One chat per record

A ticket, a report case or an account has one chat, shared by every moderator who opens it, so the next shift sees what was asked, and each question shows who asked it. A chat with no record belongs to the moderator who opened it. Use cases: UC-MOD-06, UC-MOD-07, UC-MOD-08.

Pages in this tab

ShopNexus Docs
EN VI