Skip to content
ShopNexus Docs
On this page Steps 1/3

A question is a turn. A turn runs as one or more segments: each time it is paused and continued, or asks the moderator and goes on, the server starts a new segment on the agent from the previous segment’s checkpoint. The agent has no database; the checkpoint lives on the server, in the turn’s state column.

Console The moderator's browser
Server Module agent, the API port and the MCP port
Agent Internal NestJS service
LiteLLM The stack's model gateway
  1. 1 Send the question
    Console → Server
    POST …/turns
  2. 2 Start a segment
    Server → Agent
    POST /runs, mode new
  3. 3 Call the model
    Agent → LiteLLM
    the agent's alias, user = moderator
  4. 4 Answer, maybe asking for tools
    LiteLLM → Agent
  5. 5 Call a tool through MCP
    Agent → Server
    /mcp, with the moderator's id
  6. 6 Stream NDJSON lines
    Agent → Server
    events, tool calls, checkpoints, documents
  7. 7 Send events over SSE
    Server → Console
    GET …/events
  8. 8 Pause or steer
    Console → Server
    POST …/pause, …/steer
  9. 9 Poll control every second
    Agent → Server
    GET …/control
  10. 10 The end line closes the segment
    Agent → Server
    status, answer, sources, cost
Every step of a segment, control included.

Steps

  1. The server takes the question

    The server checks the console session, reads the chosen agent from ai_agents (the Console assistant by default), checks the month’s budget and the limit of 30 questions and updates a minute per moderator, then cleans the question of control characters, zero-width characters and HTML tags. A question over 2000 characters is refused with agent_input_rejected. The turn opens running under the conversation’s row lock, and the console gets 202 {conversation_id, turn_id}.

  2. The server starts a segment

    The server sends POST /runs to the agent with AGENT_SERVICE_TOKEN: the question, the moderator and their role, the open record, the last 20 finished turns as history, and agent_config (model alias, instructions, tool list, limits). It waits at most 10 seconds for the status; anything but 200 drops the new turn and the console gets 503 agent_unavailable.

  3. The agent opens MCP and runs the loop

    The agent opens a new MCP client for the segment and keeps only tools that carry readOnlyHint and are on the agent’s list. The model opens a step with begin_step, calls tools, closes the step with end_step and a one-line summary, and answers with answer. Before each model call the agent writes a checkpoint and reads the control messages waiting for it.

  4. Lines flow back to the server

    The agent writes each thing it does as one JSON line and flushes it. The server reads the stream in the background: an event line is stored with the turn’s next sequence number and rung to open streams through pg_notify; checkpoint stores the state to resume from; tool_call updates the tool call’s row; document stores a new version of a document.

  5. The console draws the run

    The console opens GET /v1/console/agent/turns/{id}/events. The server replays the stored events, then sends new ones, each with its sequence number as id. A reloaded page asks from the last number it saw through Last-Event-ID. When the moderator closes the tab, the server closes the stream and the turn goes on running on the agent.

  6. The end line closes the segment

    The last line carries the status, the answer, its blocks, sources, cost, the checkpoint and the closing event. The server writes them all in one transaction. A stream that ends without an end line closes the turn failed with agent_stuck.

How a segment ends

SUCCEEDED

The model answered, through answer or as plain text.

PAUSED

Pause, Stop now, the turn was deleted, or the server closed the request.

AWAITING_INPUT

The model called ask_user and waits for the moderator.

FAILED

The model or MCP failed, model calls ran out, or the budget is spent.

TIMED_OUT

The segment's deadline passed, 60 seconds by default.

PAUSED and AWAITING_INPUT leave the turn open: the moderator continues, answers or ends it. A FAILED or TIMED_OUT turn can be continued in some cases, listed in Limits and failures.

Stuck turns

Each server replica holds one LISTEN agent_turn that rings the turn’s open streams. At start and every minute, the server closes turns still running 30 seconds past their deadline with agent_stuck, including turns of a replica that died midway.

ShopNexus Docs
EN VI