Runtime & subagents.
How an agent decomposes work, parallelizes via subagents, streams events, and verifies its own output. The runtime is what turns a single prompt into a structured, observable, replayable run.
§ 01The agent loop
Every Essarion agent follows the same outer loop. Tool call, result, reason, repeat — until the agent decides it is done, or hits a stop condition.
- The agent receives the user's prompt and the project context.
- It reasons about the next action and emits a tool call.
- The runtime executes the tool and returns a tool result.
- The agent reads the result, updates its plan, and either emits the next tool call or signals completion.
- On completion the agent writes a final response, saves any artifacts, and the run closes.
Every step in this loop is a typed event on the run timeline. There is no hidden chain-of-thought stage that doesn't show up in the record. The reasoning is internal; the actions and their outputs are not.
§ 02Tools available to agents
The tool surface is intentionally small. Each tool is a noun-verb pair the agent can call by name.
| Tool | Purpose |
|---|---|
| read_file | Read a file from the project drive or workspace. |
| write_file | Write a file into the workspace area. |
| search_web | Search the open web for relevant pages. |
| execCommand | Run a shell command in the agent's PTY. |
| execPython | Run a Python snippet in a managed interpreter. |
| browser_navigate | Navigate the cloud Chromium to a URL. |
| browser_act | Perform an intent-level action on the current page. |
| browser_extract | Pull structured data off the current page. |
| View_Skills | List the skill bundles available to this agent. |
| Read_Skill | Load the markdown for a named skill into context. |
| save_output | Persist a deliverable as an artifact on the run. |
| spawn_subagents | Fan out work to one or more subagents. |
Tools are identical across surfaces — there is one read_file the agent calls regardless of whether the file came from the drive, the workspace, or a subagent's output.
§ 03Subagents
The runtime can fan out work in parallel. An agent that needs to do five independent things at once spawns five subagents, lets them run concurrently, and joins their results.
Subagent tools
spawn_subagents— start one or more subagents with their own prompts and contexts.wait_for_agents— block until a set of subagents complete and return their outputs.check_agent— peek at a running subagent's status without blocking.stop_agent— terminate a subagent early.
Examples
Where subagents matter most:
- Researching multiple companies in parallel. One subagent per company, each builds its own brief, the parent agent synthesizes the cross-cuts.
- Splitting an analysis across documents. One subagent per contract, each extracts its own structured fields, the parent agent produces a comparison matrix.
- Verifying a draft against multiple sources. One subagent per source, each checks the draft's claims against its source, the parent agent reconciles disagreements.
§ 04Streaming events (SSE)
Every run emits a stream of typed events that any client can subscribe to. The same event stream that powers the workspace UI is available programmatically.
| Event | Meaning |
|---|---|
| started | The run has been accepted and is now executing. |
| tool_call | The agent has invoked a tool — name and arguments are included. |
| tool_result | A tool has returned — output, duration, and success/failure are included. |
| terminal_output | A chunk of stdout/stderr from the agent's PTY. |
| browser_session | A browser session has been opened, navigated, or closed. |
| artifact_created | The agent has saved a deliverable through save_output(). |
| surface_switch | The agent has changed which surface is in focus. |
| completed | The run finished successfully — final response and totals included. |
| error | The run terminated with an error — code, message, and last-known state included. |
For the wire format and an end-to-end SSE example see Streaming with SSE.
§ 05LLM routing
Agents run against a locked default model — a current-generation, GPT-class model held constant across users so behavior is consistent and reproducible. The platform does not silently swap models behind the scenes, and runs do not split themselves between models for cost optimization without disclosure.
Three things follow from that:
- Per-token costing. Every run accumulates input and output token totals against the active model. The cost is calculated per token, not per request.
- Credit accounting. Each user has a credit balance derived from their plan. Tokens debit credits at the model's rate.
- Plan-aware enforcement. Daily limits, total balance, and per-feature ceilings are enforced before the agent loop starts, so a run either has the headroom to complete or is rejected up front with a typed error.
§ 06Verification loops
Some agents run a final pass before declaring complete: re-reading their own output and checking it against a policy bundle. This is most common in jobs that ship a typed deliverable — contract summaries, executive briefs, RFP responses — where the deliverable has structural requirements (sections present, citations attached, totals reconciling).
The verification loop is itself an agent step: a tool call to validate, a tool result with pass/fail and a list of issues, optional re-work, and only then a completed event. If verification fails too many times, the run completes with the best draft and a flagged set of unresolved issues rather than retrying indefinitely.
§ 07Where to go next
- The skills and policies that shape an agent's behavior → Skills & jobs.
- The drive and artifact lifecycle → Drive & artifacts.
- The wire format for the event stream → Streaming with SSE.