---
title: "How the agent loop works Code Agent SDK"
source: https://docs.autohand.ai/agent-sdk/concepts/agent-loop
---

# How the agent loop works

The Autohand SDKs are thin wrappers around the Autohand CLI. The reasoning loop runs inside the CLI subprocess; your code observes it through JSON-RPC events. This page maps the loop you see in your stream to what is actually happening on the other side of the pipe.

## The shape of one turn

Each turn the CLI takes follows the same pattern. The default strategy is ReAct (Reason → Act → Observe), but plan-and-execute, parallel, and reflexion strategies are available as CLI flags.

1.  **Reason**: the model emits an assistant message. You see this as \`message\_start\` → \`message\_update\` (deltas) → \`message\_end\`.
2.  **Act**: the model calls a tool. You see \`tool\_start\` → optional \`tool\_update\` chunks → \`tool\_end\`. If permissions are interactive, a \`permission\_request\` arrives first and the loop pauses until you respond.
3.  **Observe**: the tool result feeds back into the next prompt. The CLI starts the next turn or, if the model decides it is done, emits \`agent\_end\`.

The whole turn is bracketed by \`turn\_start\` and \`turn\_end\`. A run is bracketed by \`agent\_start\` and \`agent\_end\`.

## Run the loop

The high-level \`Agent\` API runs the loop to completion and returns the final result. Use it when you do not need to render intermediate events.

## Observe the loop with streamed events

Use the low-level streaming API when you need to render every step of the loop, route tool output to a UI, or implement permission prompts.

## Loop strategies

The CLI exposes four strategies. Pick one with the \`--loop-type\` flag or the equivalent CLI config; the SDKs forward the choice without changing the public API.

-   **react** (default): the model alternates between reasoning and acting. Good for open-ended work.
-   **plan-and-execute**: the agent writes a plan first, then executes each step. Good for refactors and multi-file changes.
-   **parallel**: independent tool calls run concurrently. Good for read-heavy discovery passes.
-   **reflexion**: the agent self-critiques after each step and retries on error. Good for tasks with verifiable success criteria.

Plan mode is a related but distinct feature: it restricts the loop to read-only planning tools until you accept the plan. See \`enablePlanMode()\` and \`setPlanMode()\` in the TypeScript SDK.

## Bound the loop

Two limits keep a runaway loop in check.

-   **Iterations**: in Python, \`AutohandSDK(max\_iterations=10)\`. In TypeScript, configure on the CLI side via \`~/.autohand/config.json\` or per-run flags.
-   **Per-request timeout**: every SDK accepts a \`timeout\` (in ms) in the constructor. The default is generous (5 minutes) because long tool runs are common.

Use \`sdk.abort()\` to cancel an in-flight run from your application code, for example when the user clicks Stop in your UI.

## Best practices

-   Pick the smallest loop that fits the job. ReAct is the right default; reach for plan-and-execute only when planning meaningfully changes the result.
-   Stream events into your UI so users can see what the agent is doing and stop it early when needed.
-   Always handle \`permission\_request\` in \`interactive\` mode. Forgetting to respond will hang the loop.
-   Keep instructions short and concrete. The loop length is largely a function of how clear the prompt is.
-   Pair a tight \`max\_iterations\` with explicit success criteria when the job has a verifiable goal (tests pass, file compiles).