> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# The agentic loop
> How a worker plans, acts, and observes results in a loop — steps, tool calls, the max-steps backstop, run modes, and how a turn ends.
Every message you send to a worker can trigger many small actions behind the scenes before you see a reply. This page explains the loop that drives that work — what a step is, how tool calls play out, when the loop stops, and the safety net that keeps a task from running away.
## How the loop works
A worker doesn't answer in one shot. It repeats a simple cycle for as long as there's work left to do:
1. **Plan** — the worker decides what to do next, based on your request and everything that's happened so far in the task.
2. **Act** — if there's a concrete next move, it calls a tool: read a file, run code in its sandbox, call a connected app, delegate to another worker, or update its task plan.
3. **Observe** — the tool's result (data, a file, a success message, or an error) is added back into the conversation so the worker can see exactly what happened.
4. **Repeat** — the worker looks at the updated picture and decides again: call another tool, or answer.
The loop keeps going **only** as long as the worker keeps reaching for tools. The moment it replies with plain text and no tool call, that reply is treated as the answer, and the turn ends. There's no hidden "keep going" signal — the worker itself decides, at every step, whether the task needs another action.
```mermaid theme={null}
flowchart TB
A[Worker plans the next move] --> B{Call a tool?}
B -->|Yes| C[Tool runs]
C --> D[Result observed and added to context]
D --> A
B -->|No - plain text reply| E[Turn ends: reply sent to you]
```
This is why a single message from you can produce a long chain of file edits, sandbox commands, and connection calls before the worker ever writes back — it's all one turn, driven by the loop, not a separate exchange per action.
## What a step is
Each pass through plan → act → observe counts as one **step**. A quick question might resolve in a step or two; a task that touches several files, runs code, and checks the result can take many steps, all inside the same turn.
To keep the work visible while it runs, workers keep a running plan (a checklist of what's pending, in progress, and done) and label each tool call with a short reason. You see this as the task progresses in the [cowork session](/cowork/tasks/overview), rather than as one long silence followed by a final message.
## The max-steps backstop
Steps aren't unlimited. Every turn has a hard ceiling — a fixed, generous number of steps far beyond what a normal task needs. It exists purely as a **runaway guard**: protection against a worker stuck looping on the same failing action, not the normal way a task finishes. In the overwhelming majority of turns, the worker reaches a plain-text answer long before the ceiling matters.
If a turn does hit the ceiling while the worker is still mid-task, it doesn't just go silent. It closes out with one last summary — what it did, where things stand, and what's left — instead of returning nothing.
## Tool calls and results
Tools are how a worker actually gets things done — everything from editing a file and running a script in its [sandbox](/cowork/tasks/execution) to calling an integration through a [connection](/cowork/workers/capabilities) or handing off part of the task to another [worker](/cowork/collaborate/agents). Each tool call and its result become part of the task's history, including errors — a failed action isn't hidden from the worker, it's shown back so the worker can adjust its next move rather than repeat the same mistake blind.
You can also attach your own logic to this cycle — running a check before a tool executes, or a validation after — see [Hooks](/cowork/loop/hooks).
## Run modes
Not every tool call should happen without a check-in. Tasks run under a **run mode** — a policy that decides how much a worker can do on its own before it needs your OK.
Run mode is a task-level dial: it governs what a worker already working on your request can do unattended, turn by turn. That's a different question from the [autonomy ladder](/cowork/autonomy/proactivity), which governs whether a worker can pick up proactive or ambient work in the first place.
Today, every task runs in **Build mode**: reading files and running code proceed automatically, while anything that reaches outward — sending a message, calling an external system — or anything destructive pauses the task and asks you first. See [Human-in-the-loop](/cowork/collaborate/human-in-the-loop) for how those approval requests work.
Additional run modes (a stricter ask-first mode, a plan-only mode, a more autonomous mode, and a break-glass override) are on the roadmap. Build mode is the only one available today.
## How a turn ends
Every turn resolves one of three ways:
* **Task complete** — the worker replied with a plain-text answer and no more tool calls. The task's status shows as **done** (or **idle** if there's nothing pending) in the [cowork session](/cowork/tasks/overview).
* **Awaiting input** — the worker needs something from you: approval for a sensitive action (Run modes, above) or an answer to a question it asked. The task shows as **needs you** until you respond, then picks the loop back up with your answer in hand.
* **Paused** — the task's sandbox goes idle between turns and resumes automatically the next time there's work to do. See [Execution, sandbox & files](/cowork/tasks/execution).
Every step is checkpointed durably as it happens, and side-effectful actions carry an idempotency guard — so a crash or a resume never replays an action that already ran. What the worker actually sees at each step is covered in [Context & memory](/cowork/loop/context-and-memory).
## Next steps
See what the worker actually sees at each step, and how long tasks stay coherent.
Run your own logic before or after a tool call, or when a task stops.
How the sandbox pauses and resumes, and where task files live.
How one worker delegates part of a task to another.