The agentic loop

A turnTurnLượtEverything between sending a message and getting the answer: checks, model calls, tool use, pauses for you, and the reply. It keeps running if you close the tab.Open in glossary — one message from you and everything the agent does about it — is an agentic loopAgentic loopVòng lặp agentThe cycle an agent repeats inside one turn: call the model, run the tools it asks for, read the results, and call the model again until it can answer.Open in glossary: several model callsModel callLệnh gọi mô hìnhOne request to a model. A single turn can make many, and each one is logged with its own cost.Open in glossary, not one. The reply is not a string but an ordered list of typed blocks, and every agent runs on the same shared host.

Key rules

1. One host serves every agent. An agent is a configuration bundle loaded per invocation; creating one never deploys a runtime.
2. A message is typed blocks. Thinking, text, tool use and tool result, saved in order.
3. You never see raw chain-of-thought. Only thinking summaries, tool and approval blocks, questions and the final text.
4. Cost is logged per model call and grouped by turn for display.
5. Earlier bytes are never rewritten. Each call only appends, so the prompt cache keeps working.

One host, many agents

A department agent or a personal agent is data in the portal database: instructions, a tool allowlist, knowledge base references and a model. The portal loads that bundle and injects it into the one parameterised host on every invocation. There is no runtime per agent, so creating, editing or deleting an agent deploys nothing.

What the bundle holds and how each part reaches the host is listed under Agent configuration.

How a turn loops

Each pass starts with a model call, and the call’s stop reason decides what happens next:

The model stops because…	What the loop does
It wants a tool (tool_use)	Runs the tool if permitted, appends the tool result, and makes another model call. With Ask before each action, it first saves an approval request and pauses until a person approves.
It needs your input (clarification)	Saves the question, pauses, and resumes the same task with another model call once you answer.
It has finished (end_turn)	The terminal text is the answer. The turn ends.
A provider limit or error	The turn is left unfinished.

How pauses work — who decides, what the card shows, what a denial does — is on Agent execution.

The loop follows a few rules:

Rule	Detail
Typed blocks	Thinking, text, tool_use and tool_result are stored in order, so history replays and the UI can draw tool activity.
What you see	Safe thinking summaries, tool and approval blocks, clarification requests and terminal text. Nothing else.
Cost per call	Every model call is logged. Chat groups the calls by turn for display; audit and chat keep separate retention.
Who iterates	The agent SDK owns the tool-use loop. Completion ends the turn, an interrupt pauses it, and a provider failure leaves it unfinished. The runtime sets no step cap and no cumulative token cap.
Liveness	While a model call is reasoning and producing nothing else, the runtime sends a heartbeat. The portal extends its idle deadline on it and stores none of it.
Abandonment	If nobody is left reading, the model call itself is aborted — not just the loop around it — so an unread turn stops being billed. Each call to the portal carries its own deadline for the same reason.
Runtime guidance	A short text merged into the agent’s system prompt, paid for on every model call (four to six per turn). See Why it works this way.

Progress and the answer

• Text written in a pass that goes on to use a tool stays its own block. It is never glued onto the answer, so a turn that tried, failed and tried again keeps that record.
• A turn renders in block order: work, the sentence about that work, more work, then the answer.
• Once an answer exists, the narration above it shrinks a size and fades, in place. While the turn runs — and in a turn that ended without answering — narration keeps its full size.
• A clarification is a saved pause: the question and your answers are stored before the same task resumes.
• Each pass resends the history plus tool results, so context grows faster than linearly. Caching the stable prefix is the main cost control; it is requested on the served model, not per call. See Model catalog and The message list.
• When the next call would fill 85% of the model’s context window, the turn first replaces its history with a summary and carries on. See Building the prompt.

Thinking summaries

The model’s reasoning never leaves the runtime. Instead, the organisation’s background model writes a few sentences, inside the runtime, on what the assistant considered and decided: one summaryThinking summaryTóm tắt suy nghĩA short, safe description of what the agent is considering, shown while it works. The model's raw reasoning is never shown.Open in glossary per turn, written while the answer is still arriving.

• An organisation with no background model gets no summary — and no error.
• The usage report names the model that wrote the summary, and the portal prices that call as its own work.

Finishing

Whatever the model stops on is the answer, and terminal text streams as it is written. The guidance allows an empty lookup to end a turn. The SDK runs until the model finishes, you stop it, or an error interrupts it.

What happened	Result
The provider’s output limit is hit in the answer	Recorded as agent_output_limit_exceeded. The next turn receives that failure reason, even when no complete block was saved.
The limit is hit while the model writes a tool call’s arguments	Those calls come back as failed results with the reason, and the model issues them again. Nothing behind them runs, because the arguments were never trusted.
A tool call’s arguments never arrive as valid JSON	The runtime keeps the blocks the response did produce, answers the unreadable call with its reason, and the model writes the call again.
Either of the two above, with no call named in the response	Fatal: the truncated part is the answer itself, and continuing would save half a sentence as the turn’s answer.

Effort levels

A turn runs at one of four effort levels. The agent’s author picks the level and a single message may override it (see Models and thinking effort). Effort sets the reasoning tokens allowed per model call:

Level	Thinking tokens per call
OFF	0 — reasoning disabled
LOW	1,024
MEDIUM	4,096
HIGH	16,384

• A model without reasoning support gets no thinking budget at any level.
• Each call may use the model’s published output capacity from the model catalogue, reasoning included. The thinking budget stays strictly below that capacity, as the provider requires.
• The portal adds no per-agent or deployment output cap, step limit or cumulative token limit on top.
• Generated code has no portal character cap, at the tool or the API boundary.
• History windows, tool-result previews, department budgets, cancellation and transport timeouts still apply as usual.

Planning a heavy task

How much planning a turn does depends on the request:

Request	Planning
Answered in one or two lookups	None
Clear work of three to five steps	A task list
Large or vague work — a report from several sources, a deck	A written spec → a plan → a task list

The spec and the plan are ordinary files in the conversation workspace, spec.md and plan.md, written by two builtin skills:

• brainstorming reads the request and its sources and writes the spec. It asks a clarification only when the answer would change what gets delivered.
• writing-plans turns the spec into tasks, each naming its inputs, output and check.

Neither stops for approval. The task list itself is not a file; it is kept by the update_tasks tool, described on Artifacts and skills.

The message list

Several hooks may change what a turn sends to the model:

• the evidence collector a report is checked against;
• the compression that stands in for a long tool result;
• the trim that cuts a document argument once its write has run;
• the recovery that fails a call the model could not finish writing;
• the repair that fixes a call’s arguments;
• the reader that picks up what you typed while the turn was working.

They are attached in one place, in one order, and share one rule: a model call adds messages and never rewrites bytes an earlier call already sent.

Why the prefix matters

The gateway’s prompt cache matches on that unchanged prefix. A hook that edited an earlier message would make every later call pay for its whole context again, at the cache-write rate instead of the cheaper cache-read rate. The document trim obeys the rule by landing early: it cuts the argument before the first call that would carry it.

Releasing pictures

Pictures are the one deliberate exception. Saving a file means inspecting every page, each page arrives as a picture, and a picture stays in the list for the rest of the turn — so a 37-page document would put 37 pictures into every later call. Once a turn holds more than twenty, the provider caps every picture at 2,000 pixels per side and refuses any call carrying a larger one.

So when a call would carry more than twenty pictures:

1. The pictures in every tool result except the newest are replaced with a note saying they were reviewed and can be inspected again.
2. The save still passes, because the inspection record it checks lives in the runtime.
3. A picture you attached is never released.
4. That one call pays for the cache again; the list then grows by appending until it crosses twenty again.

Agent configuration

The stored bundle is: instructions, model, tool allowlist, skill references, knowledge base bindings, memory policy and visibility. The portal intersects it with your effective access before the host runs — see Access resolution.

Part	How it reaches the host
System prompt, model, sampling settings, memory flag	In the invocation payload.
Tool allowlist	A separate call. The host registers only the tools it is told about, falls back to no optional tools if that call fails, and never advertises a tool the portal did not name.
Knowledge base ids	Never sent. Resolved on the server for each search, from the turn’s bindings, narrowed by your own rules.
Custom skill catalogue	Names and descriptions you are authorised to see, supplied by the backend. A skill picked with /slug supplies its instructions directly; other custom instructions load through the backend with access checks.
Builtin skills	Shipped in the agent image under skills/, listed as builtin:<slug> and loaded locally, with no database rows or bindings. The runtime merges both catalogues.
Other bindings	Visibility is settled at turn start, before the host is invoked.

Resumable streaming

You can refresh or lose the connection mid-turn without losing work:

• Agent events go to Redis Streams and reach the browser as server-sent events (SSE). Completed history and blocks are durable in PostgreSQL; Redis is only the replay buffer for an active run.
• Each turn has a stable run id and each event a sequence number, so a reconnect resumes strictly after the last event the browser received.
• Saving deduplicates on message and sequence, so a replayed event changes nothing and repeats no side effect.

The full mechanics — cursors, replay windows, oversized frames and abandoned runs — are on Turn lifecycle.

Why it works this way

Under the hood

Related