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).