Agent Loop

The core execution cycle that turns a user message into an agent reply. Every message — from CLI, Telegram, Discord, web — goes through the same loop.

Lifecycle

intake → command-check → lane-acquire → context → model → tools → persist → drain-queue
  1. Intake — receive message from a channel, record metadata (sessionKey, channel, agent)
  2. Command-check — slash commands (/reset, /status, etc.) handled inline, no LLM call
  3. Lane-acquire — see Command Queue. If session is busy, queue or steer.
  4. Context — Context Engine builds the system prompt from 10 layers
  5. Model — call the LLM with assembled context + recent messages
  6. Tools — if LLM wants to call tools, execute them (with permission checks)
  7. Persist — append user message + assistant reply to session store
  8. Drain-queue — process any messages queued while busy

Hooks fired during the loop

  • agent:bootstrap — before model call, after context built
  • agent:tool-call — when LLM decides to call a tool
  • agent:tool-result — after tool execution returns
  • agent:complete — final reply ready
  • agent:error — anything fails
  • agent:queued — run rejected, message queued

Plugins can register handlers for these hooks to extend behavior without modifying core. See Plugin SDK.

Sync vs async

The gateway exposes two ways to run an agent loop:

  • Sync — POST /agent blocks the HTTP connection until the loop finishes
  • Async — POST /agent/async returns { runId, acceptedAt } immediately. Use POST /agent/run/:runId/wait to block, or POST /agent/run/:runId/abort to cancel.

Source

Implementation: apps/gateway/src/agent-loop.ts.

What's next?