An agent run is the durable execution record for a chat request, scheduled task, integration event, messaging event, widget refresh, or delegated job.
The caller supplies the user, agent, trigger source, conversation, and optional model override. The engine resolves the effective agent settings and available models, then creates the run record.
The prompt context can include:
Large history and tool results are compacted before model calls.
The engine classifies the request as a direct response or an execution task, selects a planning depth, and activates a bounded tool catalog. Complex runs can produce an execution plan, use subagents, and request a final verification pass.
Model selection is scoped to the user and agent. Explicit run or task overrides take precedence when the requested model is enabled and available.
Each model turn can return text, completion state, or tool calls. Before a tool runs:
before_tool_call hooks execute.The engine records steps, run events, model usage, timing, and artifacts. Repetition guards and loop limits prevent unbounded retries.
Run control is checked at model and tool boundaries. Abort and interruption are terminal; pause cancels the active model or command, records a checkpoint, and parks the in-process run until the authenticated resume action releases it. If a state-changing tool is interrupted after dispatch, its outcome is recorded as unknown and must be verified before the model can attempt it again.
The final response is sanitized and stored. Messaging-triggered runs send an explicit message or use the final response as a fallback when nothing visible was already delivered.
The engine emits run:complete, persists prompt and usage metrics, refreshes
conversation summaries and working state, and cancels unfinished subagents.
Failures and user stops produce separate terminal run states.
Terminal transitions are first-writer-wins. A late model, tool, verifier, or delivery callback cannot overwrite an earlier stop or interruption, and active run, step, and delegation rows are settled together.
Completed conversations can run structured memory consolidation. The engine extracts durable candidates, reconciles updates, and invalidates prompt caches after memory changes.
The on_loop_end hook provides a non-blocking observer for learning and
analytics. Hook errors cannot change the completed run outcome.