How a question runs
From the moderator pressing send to the agent's last line, who calls whom, what is stored and the ways a segment ends.
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.
- 1 Send the questionConsole → Server
POST …/turns - 2 Start a segmentServer → Agent
POST /runs, modenew - 3 Call the modelAgent → LiteLLMthe agent's alias,
user= moderator - 4 Answer, maybe asking for toolsLiteLLM → Agent
- 5 Call a tool through MCPAgent → Server
/mcp, with the moderator's id - 6 Stream NDJSON linesAgent → Serverevents, tool calls, checkpoints, documents
- 7 Send events over SSEServer → Console
GET …/events - 8 Pause or steerConsole → Server
POST …/pause,…/steer - 9 Poll control every secondAgent → Server
GET …/control - 10 The end line closes the segmentAgent → Serverstatus, answer, sources, cost
Steps
-
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 withagent_input_rejected. The turn opensrunningunder the conversation’s row lock, and the console gets202 {conversation_id, turn_id}. -
The server starts a segment
The server sends
POST /runsto the agent withAGENT_SERVICE_TOKEN: the question, the moderator and their role, the open record, the last 20 finished turns as history, andagent_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 gets503 agent_unavailable. -
The agent opens MCP and runs the loop
The agent opens a new MCP client for the segment and keeps only tools that carry
readOnlyHintand are on the agent’s list. The model opens a step withbegin_step, calls tools, closes the step withend_stepand a one-line summary, and answers withanswer. Before each model call the agent writes a checkpoint and reads the control messages waiting for it. -
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
eventline is stored with the turn’s next sequence number and rung to open streams throughpg_notify;checkpointstores the state to resume from;tool_callupdates the tool call’s row;documentstores a new version of a document. -
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 asid. A reloaded page asks from the last number it saw throughLast-Event-ID. When the moderator closes the tab, the server closes the stream and the turn goes on running on the agent. -
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
endline closes the turnfailedwithagent_stuck.
How a segment ends
The model answered, through answer or as plain text.
Pause, Stop now, the turn was deleted, or the server closed the request.
The model called ask_user and waits for the moderator.
The model or MCP failed, model calls ran out, or the budget is spent.
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.