Agent Loop
Overview
The Agent Loop is the core execution mechanism of the Work module in the workspace. It drives the AI Agent through an autonomous reasoning-execution loop: analyze the task → select a tool → execute the operation → evaluate the result → continue reasoning, until the task is complete or an exit condition is triggered.
The engine adopts a provider-agnostic architecture, supporting multiple model providers through a unified LLM Adapter interface.
Architecture
LLM Adapters
AgentEngine
│
├── OpenAIAdapter
│ ├── Responses API (incremental state management)
│ └── Chat Completions API (full context)
│
└── AnthropicAdapter
└── Messages API (native streaming + thinking)
The adapters automatically handle:
- Message format conversion (OpenAI ↔ Anthropic)
- Tool definition conversion
- Think Tag processing (automatically stripping the
<think>tags of models such as DeepSeek)
Loop Flow
┌─ Pre-flight Validation ────────────────────────────────────────────────────────┐
│ Reject prompts exceeding 60% of the input budget to prevent silent truncation │
└───────────────────────────────────────┬────────────────────────────────────────┘
▼
┌─ Main Loop (Round 0 → maxTurns-1) ─────────────────────────────────────────────┐
│ │
│ ① Context Management │
│ - Preemptive tool-result truncation (Layer 1) │
│ - Check whether compaction is needed (shouldPreemptiveCompact) │
│ │
│ ② LLM Call │
│ - Streaming inference (text_delta + thinking + tool_use) │
│ - Push events to the UI in real time │
│ │
│ ③ Tool Execution │
│ - validateToolCalls → validate legitimacy │
│ - Concurrency partitioning → group by concurrency metadata │
│ - Parallel execution → result normalization │
│ │
│ ④ Exit Decision │
│ - No tool calls → exit (end_turn) │
│ - Limit reached → exit (max_rounds/max_budget/deadline) │
│ - Exception → exit (circuit_breaker/fatal_error) │
│ - Tool calls present → continue to the next round │
│ │
└────────────────────────────────────────────────────────────────────────────────┘
Loop Parameters
| Parameter | Default | Description |
|---|---|---|
maxTurns |
25 | Maximum number of loop rounds |
maxErrors |
— | Consecutive tool error threshold |
maxBudgetInputTokens |
— | Upper limit on the input token budget |
maxExecutionMs |
— | Upper limit on execution time (milliseconds) |
snapshotStrategy |
every_tool_round |
Snapshot saving strategy |
resumeSessionId |
— | ID for resuming an interrupted session |
8 Exit Conditions
| Exit Reason | Trigger Condition |
|---|---|
| end_turn | The Agent has completed the task, with no further tool calls |
| max_rounds | The maxTurns limit has been reached (25 rounds by default) |
| circuit_breaker | 5 consecutive LLM call failures |
| no_tool_calls | No tool call request in the LLM response |
| user_cancel | Manually aborted by the user |
| context_overflow | Context still overflows after compression |
| fatal_error | Unrecoverable error (authentication failure, billing issue, etc.) |
| compaction_exhausted | Compaction retries exhausted (maximum 5 times) |
Circuit Breaker Mechanism
Prevents infinite retries caused by consecutive LLM failures:
| Parameter | Value | Description |
|---|---|---|
CIRCUIT_OPEN_THRESHOLD |
5 | 5 consecutive failures trigger the circuit breaker |
CIRCUIT_OPEN_WAIT_MS |
60,000 | 60-second cooldown after the circuit breaker opens |
Error classification and retry strategy:
| Error Type | Strategy |
|---|---|
rate_limit |
Exponential backoff + random jitter retry |
timeout / overloaded |
Immediate retry |
context_overflow |
Trigger context compression |
auth / billing / model_not_found |
Throw directly (no retry) |
Streaming Events
The Agent execution process notifies the UI in real time through streaming events:
| Event Type | Data | Description |
|---|---|---|
text_delta |
Text fragment | Incremental push of the Agent's text output |
thinking |
Thought fragment | Native chain-of-thought content (Anthropic thinking models) |
tool_use_start |
Tool name + parameters | Tool call started |
tool_result |
Execution result | Tool execution completed |
error |
Error information | Error during execution |
done |
Exit reason | This loop round has ended |
Events from sub-agents are passed through to the parent Agent's UI.
EMA Token Calibration
The engine uses an Exponential Moving Average (EMA) to dynamically calibrate the accuracy of token estimation:
| Parameter | Value | Description |
|---|---|---|
| Initial value | 3.0 chars/token | Conservative estimate (suited to mixed Chinese + code scenarios) |
| First 3 times | Mean convergence | Rapidly approach the true value |
| Subsequently | EMA α=0.15 | Smoothly track actual consumption |
| Filter | 0.5 < observed < 8 | Exclude outliers |
After each LLM call, the calibration factor is updated with the actual token consumption, ensuring that context budget estimation becomes increasingly accurate.
Session Snapshots
Supports persisting session state to prevent progress loss from unexpected interruptions:
| Strategy | Trigger Timing |
|---|---|
every_tool_round (default) |
After each tool call completes |
every_round |
After each round of LLM interaction |
manual |
Only manually triggered |
Snapshots are stored as JSON files, using atomic writes (.tmp + rename) to prevent file corruption. An interrupted session can be resumed via resumeSessionId.
What This Means for You
The Agent Loop is the capability that lets you feel the Agent "working continuously." When you say "help me refactor the code structure of this project," the Agent won't just reply with a single suggestion and stop—it will automatically browse files, analyze the structure, make changes one by one, and run tests, until it is done.
What you can observe:
- The Agent calls multiple tools in succession (list files → read files → modify files → run tests), and the tool calls appear one after another in the interface
- If the Agent fails 5 times in a row (e.g., API timeouts), it will pause for 60 seconds instead of retrying indefinitely—you will see a period of waiting followed by the Agent telling you it encountered a problem
- By default it runs for at most 25 rounds; extremely complex tasks may stop after 25 rounds and tell you "the maximum number of rounds has been reached"
What you can do:
- Click the Stop button at any time to abort the Agent's execution
- If the Agent goes off track, abort it and give clearer instructions
- For particularly complex tasks, you can have the Agent lay out a plan before executing ("first lay out a plan, then execute after I confirm")
Related Documentation
- 5-Layer Context Compression Strategy — Detailed explanation of context management
- Three-Dimensional Memory System — Memory injection and querying
- Work Conversational Interaction — The Agent Loop experience in the user interface